architecture
How a backend service is laid out and started: its directories, its main(), the App container, graceful shutdown, where shared code lives, how to run the stack locally, and how to add a new service.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- architecture
- description
- How a backend service is laid out and started: its directories, its main(), the App container, graceful shutdown, where shared code lives, how to run the stack locally, and how to add a new service.
03 SKILL.md 正文
Skill: Service architecture
Every service is built the same way, so anyone who knows one knows them all.
When this skill applies
- Adding a new service
- Changing a
cmd/entrypoint,internal/app/, startup or shutdown - Deciding whether code belongs to one service or to
pkg/ - Starting, stopping or checking the app locally
A service's layout
<service>/
├── cmd/http/main.go # the entrypoint; cmd/grpc/ for a gRPC service
├── cmd/openapi/main.go # writes openapi.yaml from the routes' operations
├── openapi.yaml # the HTTP contract, generated: see the api-design skill
└── internal/
├── app/app.go # App: settings and connections opened once, shared by the routes
├── config/config.go # Config and Load(): see the configuration skill
├── controller/<domain>/ # business logic; defines the interfaces it needs
├── gateway/<domain>/<transport>/ # calls to other services: http/, grpc/
├── repository/<domain>/<driver>/ # the database: postgres/
├── handler/<domain>/<transport>/ # requests in: http/, grpc/
├── model/ # the domain's structs, shared by the layers
└── route/<domain>.go # wiring: gateway/repository → controller → handler → routes
A transport is always a directory of its own: HTTP and gRPC code never share a package. The api-design skill says what each layer may do.
main()
The order never changes:
logging.Init().cfg := config.Load(), then check every required setting andos.Exit(1)with a message naming the variable when one is missing.app.New(cfg): open what is opened once, such as a database pool;maincloses it once the server has stopped.ctxfromsignal.NotifyContext, which ends on SIGINT or SIGTERM.gin.New()(nevergin.Default()), withgin.Recovery()andmiddleware.CorrelationID(), andSetTrustedProxiesset explicitly.route.Register(ctx, application, r), which registers each domain's routes; an error is logged and exits 1.- Serve until
ctxends, then shut down with a timeout, so requests in flight finish.
api/cmd/http/main.go is the reference: copy it.
A service no client calls directly serves only the routes other services call, under
/internal/<service>/, so one rule at the edge can keep them all private. Authentication happens
once, in the service that faces clients; services behind it trust its calls and do not check again.
The App container
internal/app.App holds the settings and what is opened once. Routes receive *app.App; it is a
struct, never an interface. A helper every handler needs, such as the signed-in user, is a method
on it.
Where code goes
| Where | For |
|---|---|
pkg/ at the root |
code more than one service uses: logging, errors, HTTP helpers, middleware |
<service>/pkg/ |
code shared inside one service only |
Move code to the root pkg/ only when a second service needs it, and then move it rather than
copy it.
Running it
The local stack is docker-compose.yaml at the project's root; run compose there.
- Start:
docker compose up -d. The first start compiles for a minute. - Check:
curl -sf --retry 30 --retry-all-errors http://localhost:8000/healthanswers onceapihas compiled; each service has its own host port. - Logs:
docker compose logs <service>; add-fonly in a terminal a person watches, since it never returns. - Stop:
docker compose down.
A new service
- Copy
api/to<service>/and replaceapiin its import paths. - Keep
internal/config,internal/app, the health route,cmd/http/main.goandcmd/openapi/main.go; remove the domains it does not have, fromroute.Registerandroute.Operations()too, and regenerate itsopenapi.yamlwithgo run ./<service>/cmd/openapi. - Add it to
docker-compose.yaml, asapiis, with a host port of its own. go vet ./... && go test ./..., thendocker compose up -d, and check that its/healthanswers on its port, as Running it says.
Definition of done
- [ ] The layout matches the tree above, with each transport in a directory of its own
- [ ]
main()keeps the order under main(), failing fast on a missing setting - [ ] Shared state hangs off
App, not package variables - [ ] Shutdown is graceful
- [ ] Code shared by services is in the root
pkg/, and only there
04 同仓库更多 Skills
notes
Where notes go.
naming
How things are named, including the sample's tables.
local
A skill only this project has.
hello
Greets sample's developers.
notes
Where notes go.
naming
How things are named, including the sample's tables.