Go API Patterns

Core Philosophy

1. Standard library first — net/http is production-grade. Reach for a framework only when it saves significant boilerplate (route groups, parameter binding). A thin router like Chi adds value; a full framework adds coupling.
2. Explicit over magic — Pass dependencies as constructor arguments, not globals. Use context.Context for request-scoped values, not package-level state. Wire things visibly in main().
3. Errors are values — Return errors, wrap them with %w for context, handle them at the boundary. Panics are for programmer bugs, not business logic. Middleware recovers from panics; handlers return errors.
4. Composition over inheritance — Build middleware as func(http.Handler) http.Handler. Stack behaviors by chaining, not by inheriting from a base controller. The http.Handler interface is the universal contract.
5. Fail fast at startup, gracefully at runtime — Validate configuration, ping databases, and bind ports at startup. At runtime, drain connections on SIGTERM, respect context cancellation, and shut down cleanly.

Quick-Start: Common Problems

"How do I structure a Go API project?"