Golang Starter

A REST API starter built with Golang and Huma, structured with hexagonal architecture (ports and adapters).

We'll be building an API to manage the library of a Movie streaming service.

Layout

cmd/golang-gin-starter/    wiring only: read config, construct adapters, inject, serve
internal/domain/           entities and domain errors — imports nothing but stdlib
internal/app/              use cases; defines the port interfaces it consumes
internal/adapters/http/    Huma handlers, wire models, routing, error mapping
internal/adapters/memory/  in-memory MovieRepository
internal/adapters/metrics/ Prometheus ActionCounter
internal/config/           config struct, loading, validation

Dependencies point inward. No framework type (huma.Context, http.Request) crosses out of internal/adapters, which is why internal/app is tested with port fakes and no infrastructure.

The repository ships an in-memory MovieRepository, so the starter runs with no external services. A real service replaces it with an internal/adapters/postgres package using pgx plus numbered SQL migrations, and changes nothing in app or domain.

Running

make run       # listens on the address in application.yaml
make test
make coverage
make install   # stamps build info into the binary, reported by /healthz

API documentation

The OpenAPI schema is generated by Huma from the registered operations and the struct tags on the request and response models — there is no generation step and no checked-in spec.

Path	What
/docs	Schema documentation (/ redirects here)
/openapi.json	Raw OpenAPI spec
/openapi.yaml	Raw OpenAPI spec
/healthz	Liveness probe with build info
/metrics	Prometheus metrics
/api/movies	The movies API

Configuration

Configuration is a single application.yaml, read from CONFIG_FILE or from ./application.yaml, and validated on load — an invalid value is a startup failure naming the field, not a surprise at request time. In Kubernetes it is delivered as a ConfigMap under one application key (see charts/golang-gin-starter).

Secrets do not live in application.yaml; they come from Google Secret Manager.

Dependencies

• go mod for dependency management
• Huma for the REST framework and OpenAPI generation
• Prometheus for metrics