← Tous les modèles

La bibliothèque standard d’abord, context partout, erreurs enveloppées, aucun état 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.

  1. Standard library first. net/http, encoding/json, log/slog and database/sql are the default. A dependency (chi for routing is accepted) needs a reason in the plan saying what the standard library lacks.

  2. Context everywhere. Every function that does I/O takes ctx context.Context as its first parameter and passes the request context down. No context.Background() inside a request path, and outgoing calls set a timeout with context.WithTimeout.

  3. Wrapped errors. Errors are returned, never ignored, and wrapped with fmt.Errorf("...: %w", err) to add context. Callers branch with errors.Is and errors.As on sentinel or typed errors, never by comparing strings. panic is reserved for programmer errors at startup.

  4. 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 in main and passed in.

  5. 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.

  6. Graceful shutdown. main listens for SIGTERM with signal.NotifyContext, stops accepting requests with http.Server.Shutdown and drains within a set deadline. The server sets ReadHeaderTimeout, ReadTimeout and WriteTimeout.

  7. Tests and race checks. Handlers are tested with httptest and table-driven tests. CI runs go vet, staticcheck and go test -race; a data race fails the build.