go-api-scaffolding - GitLite

KO | EN

gitlite — search

#deep-learning #rag #generative-ai #kotlin #c #pdf #ui #docker #json #openai

go-api-scaffolding

(★ 9)

Go REST API scaffold: spec-first OpenAPI, chi, pgx/sqlc, OpenTelemetry, JWKS auth, embedded migrations, one-command resource generation.

File Explorer

ZIP Download

- - ci.yml
  - codeql.yml
  - release.yml
- CONTRIBUTING.md
- dependabot.yml
- PULL_REQUEST_TEMPLATE.md
- SECURITY.md
- oapi-codegen.yaml
- openapi.go
- openapi.yaml
- - main.go
- - init.go
  - init_test.go
  - main.go
  - main_test.go
- - main.go
- - otel-collector-config.yaml
  - prometheus.yml
  - tempo.yaml
- docker-compose.yml
- Dockerfile
- - 0001-record-architecture-decisions.md
  - 0002-vertical-slice-modules.md
  - 0003-type-safe-codegen.md
  - 0004-stdlib-and-chi-no-framework.md
- - logo.webp
- architecture.md
- - authenticator.go
  - middleware.go
  - middleware_test.go
  - principal.go
  - principal_test.go
  - verifier.go
  - verifier_test.go
- - config.go
  - config_test.go
- - idempotency.go
  - idempotency_test.go
  - queries.sql
- - reaper.go
  - reaper_test.go
- - doc.go
  - logger.go
  - otel.go
  - redact.go
  - redact_test.go
- - outbox.go
  - outbox_test.go
  - queries.sql
- - admin.go
  - api_integration_test.go
  - docs.go
  - docs_test.go
  - health.go
  - idempotency_integration_test.go
  - middleware.go
  - middleware_test.go
  - realip.go
  - realip_test.go
  - router.go
  - server.go
- - doc.go
  - postgres.go
- 00001_widgets.sql
- 00002_outbox.sql
- 00003_idempotency.sql
- embed.go
- go.mod
- go.sum
.air.toml
.dockerignore
.editorconfig
.env.example
.gitattributes
.gitignore
.golangci.yml
.goreleaser.yaml
.pre-commit-config.yaml
go.mod
go.sum
LICENSE
README.md
sqlc.yaml
Taskfile.yml

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<p align="center">
  <img src="docs/assets/logo.webp" alt="Go" width="160">
</p>

<h1 align="center">go-api-scaffolding</h1>

<p align="center">
  A Go API service to clone, rename and build on. The production concerns are
  wired and tested; none of it is a framework.
</p>

<p align="center">
  <a href="https://github.com/y0f/go-api-scaffolding/actions/workflows/ci.yml"><img src="https://github.com/y0f/go-api-scaffolding/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://pkg.go.dev/github.com/y0f/go-api-scaffolding"><img src="https://pkg.go.dev/badge/github.com/y0f/go-api-scaffolding.svg" alt="Go Reference"></a>
  <img src="https://img.shields.io/badge/go-1.26+-00ADD8?logo=go&logoColor=white" alt="Go 1.26+">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT"></a>
</p>

## What you get

- **HTTP.** `net/http` and chi. Requests are validated against `api/openapi.yaml`,
  the typed server interface is generated from it, and CI fails on drift. Errors
  are RFC 9457 `problem+json` carrying the trace ID. Per-client rate limiting
  that keys on the forwarded client behind the proxies in
  `FORGE_HTTP_TRUSTED_PROXIES`. Readiness-first graceful drain.
- **Data.** pgx/v5, sqlc-generated queries checked against the real schema,
  goose migrations embedded in the binary and applied as a deploy step.
- **Auth.** Bearer tokens verified against JWKS (OIDC) or an RSA key. RBAC in
  the service layer. In development a token is minted and logged at startup.
- **Docs.** The spec served verbatim at `/openapi.yaml` and an interactive
  reference at `/docs`.
- **Observability.** Prometheus `/metrics`; slog with `trace_id` and `span_id`
  on every line and secret redaction.

- **Tracing.** OpenTelemetry spans exported over OTLP, with a Collector, Tempo,
  Prometheus and Grafana compose profile.


- **Outbox.** Events written in the same transaction as the state change,
  relayed at-least-once by a poller.


- **Idempotency.** `Idempotency-Key` on unsafe requests: the response is stored
  with the write and replayed on retry, scoped to the caller.


- **Admin.** pprof and expvar on a separate token-gated port.

- **Testing.** Unit tests without a database. Integration tests on a real
  Postgres via testcontainers, each test on its own clone of a migrated
  template database.
- **Supply chain.** SHA-pinned Actions, govulncheck and CodeQL, distroless
  non-root image, cosign-signed releases with an SBOM.
- **Growth.** `forge add resource <Name>` stamps a new vertical slice.

## Start a project

Needs Go, git, Docker and [Task](https://taskfile.dev).

```bash
go run github.com/y0f/go-api-scaffolding/cmd/forge@latest new myapp
cd myapp
task up
```

`new` clones the scaffold into `myapp`, asks for your module path and which
optional slices to keep (example resource, outbox, idempotency keys, OTLP
export with the Grafana stack, admin listener), deletes the rest, removes the
installer, and regenerates and builds the result. In a clone you already have,
run `go run ./cmd/forge init` instead. Non-interactive:

```bash
go run ./cmd/forge init -yes -module github.com/you/app -drop outbox,admin
```

The `FORGE_` environment prefix and the `forge` command name stay; both are
independent of the module path. The rest of this file describes the scaffold
with everything kept.

## Quickstart

Needs Docker and [Task](https://taskfile.dev).

```bash
git clone https://github.com/y0f/go-api-scaffolding
cd go-api-scaffolding
task up          # Postgres, migrations, API on :8080
```

The API log prints a development bearer token at startup. The API reference
is at `http://localhost:8080/docs`.

```bash
export TOKEN="<token from the api log>"

curl -s localhost:8080/v1/widgets

curl -s -X POST localhost:8080/v1/widgets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"first"}'
```

Add `-H "Idempotency-Key: $(uuidgen)"` to the POST and a retry replays the
stored response instead of creating a second widget.

`task down` stops the stack and deletes the database volume.

To run the binary outside Docker against any Postgres, copy `.env.example` to
`.env` (Task loads it), then:

```bash
task setup       # build the pinned toolchain from tools/go.mod into ./bin
task migrate
task run
```

## Add a resource

```bash
go run ./cmd/forge add resource Order
```

This writes `internal/modules/order` (domain, store, service, handler, test,
queries) and a migration, registers the queries with sqlc, and prints the
remaining steps: `task generate`, add the handler to `RouterDeps.Mounts`, grant
the write permission, `task migrate`.

Generated modules are plain chi handlers with authentication, authorization,
validation and `problem+json` errors. Make one spec-first by adding its paths
to `api/openapi.yaml` and implementing the generated interface.

The `widget` module is that spec-first form of the same slice.

## Tasks

```bash
task generate          # regenerate sqlc and OpenAPI code
task lint              # golangci-lint
task test              # unit tests with coverage
task test:race         # unit tests under the race detector (needs a C toolchain)
task test:integration  # integration tests on real Postgres (needs Docker)
task vuln              # govulncheck
task ci                # every gate CI runs
task build             # api, migrate and forge into ./bin
```

`task observe` starts the full stack with the OpenTelemetry Collector, Tempo,
Prometheus and Grafana. Grafana is at `http://localhost:3000` with both data
sources provisioned; traces flow from the API through the Collector into Tempo.

The toolchain (linter, generators, scanner, live reload) is pinned in
`tools/go.mod`, a module of its own so none of it enters the application's
dependency graph. CI builds the same versions from the same file.

## Layout

```
api/           the OpenAPI contract
cmd/           api (composition root), migrate, forge
internal/      config, server, auth, observability, platform, modules, gen
migrations/    versioned SQL, embedded into the binaries
deployments/   Dockerfile, docker compose
docs/          architecture and ADRs
tools/         pinned developer toolchain
```

The package-level tree, the request flow and the reasoning behind the design
are in [`docs/architecture.md`](docs/architecture.md) and
[`docs/adr`](docs/adr). Conventions: [`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md).

## Verify a release

```bash
cosign verify-blob \
  --bundle checksums.txt.bundle \
  --certificate-identity-regexp 'https://github.com/y0f/go-api-scaffolding' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  checksums.txt
```

## License

MIT. See [LICENSE](LICENSE).