Biblioteca padrão primeiro, context em toda parte, erros encapsulados, sem estado global.
Constitution — Go HTTP service
Version 1.0.0 · Ratified 2026-11-10
These principles hold for every spec, plan and task of the project. A spec may add rules; it never weakens these.
-
Standard library first.
net/http,encoding/json,log/sloganddatabase/sqlare the default. A dependency (chi for routing is accepted) needs a reason in the plan saying what the standard library lacks. -
Context everywhere. Every function that does I/O takes
ctx context.Contextas its first parameter and passes the request context down. Nocontext.Background()inside a request path, and outgoing calls set a timeout withcontext.WithTimeout. -
Wrapped errors. Errors are returned, never ignored, and wrapped with
fmt.Errorf("...: %w", err)to add context. Callers branch witherrors.Isanderrors.Ason sentinel or typed errors, never by comparing strings.panicis reserved for programmer errors at startup. -
No global state. No package-level mutable variables and no
init()with side effects. Dependencies such as the database pool, logger and clients are fields of a server struct built inmainand passed in. -
Small interfaces at the consumer. Interfaces are declared where they are used and hold only the methods the consumer calls. Functions accept interfaces and return concrete types.
-
Graceful shutdown.
mainlistens for SIGTERM withsignal.NotifyContext, stops accepting requests withhttp.Server.Shutdownand drains within a set deadline. The server setsReadHeaderTimeout,ReadTimeoutandWriteTimeout. -
Tests and race checks. Handlers are tested with
httptestand table-driven tests. CI runsgo vet, staticcheck andgo test -race; a data race fails the build.