Go application architecture with net/http 1.22+ routing, project structure patterns, graceful shutdown, and dependency injection. Use when building Go web servers, designing project layout, or structuring application dependencies.
Instrucciones de origen · Vista previa de solo lectura
name
go-architect
description
Go application architecture with net/http 1.22+ routing, project structure patterns, graceful shutdown, and dependency injection. Use when building Go web servers, designing project layout, or structuring application dependencies.
Standard library first -- Use net/http and the Go 1.22+ enhanced ServeMux for routing. Only reach for a framework (chi, echo, gin) when you have a concrete need the stdlib cannot satisfy (e.g., complex middleware chains, regex routes).
Dependency injection over globals -- Pass databases, loggers, and services through struct fields and constructors, never package-level var.
Explicit over magic -- No init() side effects, no framework auto-wiring. main.go is the composition root where everything is assembled visibly.
Small interfaces, big structs -- Define interfaces at the consumer, keep them narrow (1-3 methods). Concrete types carry the implementation.
Hard gates
Use this sequence when implementing or reviewing work that claims to follow this skill. Do not skip ahead; each step has a pass condition you can answer with tooling or a concrete file path.
Toolchain vs APIs — If the code uses Go 1.22+ ServeMux features (method+path patterns like "GET /x/{id}", r.PathValue, or {path...}): run go version and pass only if the reported toolchain is go1.22+. If the project must stay on an older Go, pass only by not using those APIs (use a compatible router or older patterns) and say so in the review or PR.
Composition root — Pass when main.go or cmd/.../main.go visibly constructs the server and injects shared dependencies (DB, logger, config). Fail if shared dependencies are wired in init() or package-level var instead of explicit construction in main (or a run() called from main).
Production HTTP shutdown — For a long-lived HTTP service, pass only if shutdown uses http.Server.Shutdown with a bounded context (e.g. context.WithTimeout) after waiting on signal.NotifyContext (or equivalent). Cite the file path when reporting; see references/graceful-shutdown.md for the full pattern.
No env/globals in handlers — Pass when handlers and domain code take dependencies via structs/arguments. Fail if handlers read os.Getenv for secrets or use package-level var for DB/clients (loading env in main or a dedicated config package is fine).
Go 1.22+ Enhanced Routing
Go 1.22 upgraded http.ServeMux with method-based routing and path parameters, eliminating the most common reason for third-party routers.
func(s *Server) handleGetUser(w http.ResponseWriter, r *http.Request) {
id := r.PathValue("id")
if id == "" {
http.Error(w, "missing id", http.StatusBadRequest)
return
}
user, err := s.users.GetUser(r.Context(), id)
if err != nil {
s.logger.Error("getting user", "err", err, "id", id)
http.Error(w, "internal error", http.StatusInternalServerError)
return
}
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(user)
}
Wildcard and Exact Match
// Exact match on trailing slash -- serves /api/files/ only
mux.HandleFunc("GET /api/files/", s.handleListFiles)
// Wildcard to end of path -- /api/files/path/to/doc.txt
mux.HandleFunc("GET /api/files/{path...}", s.handleGetFile)
Routing Precedence
The new ServeMux uses most-specific-wins precedence:
GET /api/users/{id} is more specific than GET /api/users/
GET /api/users/me is more specific than GET /api/users/{id}
Method routes take precedence over method-less routes
Server Struct Pattern
The Server struct is the central dependency container for your application. It holds all shared dependencies and implements http.Handler.
type Server struct {
db *sql.DB
logger *slog.Logger
router *http.ServeMux
}
funcNewServer(db *sql.DB, logger *slog.Logger) *Server {
s := &Server{
db: db,
logger: logger,
router: http.NewServeMux(),
}
s.routes()
return s
}
func(s *Server) routes() {
s.router.HandleFunc("GET /api/users/{id}", s.handleGetUser)
s.router.HandleFunc("POST /api/users", s.handleCreateUser)
s.router.HandleFunc("GET /healthz", s.handleHealth)
}
func(s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
s.router.ServeHTTP(w, r)
}
Middleware Wrapping
Apply middleware at the http.Server level or per-route:
// Wrap entire server
httpServer := &http.Server{
Addr: ":8080",
Handler: requestLogger(s),
}
// Or per-route
s.router.Handle("GET /api/admin/", adminOnly(http.HandlerFunc(s.handleAdmin)))
Flat structure -- single package, all files in root. Best for CLIs, small services, < ~10 handlers. See references/project-structure.md.
Modular/domain-driven -- cmd/, internal/ with domain packages. For larger apps with multiple bounded contexts. See references/project-structure.md.
Start flat. Migrate when you see the signs described in the reference.
Graceful Shutdown
Every production Go server needs graceful shutdown. The pattern uses signal.NotifyContext to listen for OS signals and http.Server.Shutdown to drain connections.
Discussing package layout or directory organization
The project is growing and needs restructuring
Load graceful-shutdown.md when:
Setting up a production HTTP server
Implementing signal handling or clean shutdown
Discussing deployment or container readiness
Load dependency-injection.md when:
Designing how services, stores, and handlers connect
Making code testable with interfaces
Reviewing constructor functions or wiring logic
Anti-Patterns
Global database variables
// BAD -- untestable, hidden dependencyvar db *sql.DB
funchandleGetUser(w http.ResponseWriter, r *http.Request) {
db.QueryRow(...)
}
Pass db through a Server or Service struct instead.
Framework-first thinking
Do not start with gin.Default() or echo.New(). Start with http.NewServeMux(). Only introduce a framework if you hit a real limitation of the stdlib that justifies the dependency.
God packages
A single handlers package with 50 files is not organization. Group by domain (user, order, billing), not by technical layer.
Using init() for setup
// BAD -- invisible side effects, untestablefuncinit() {
db, _ = sql.Open("postgres", os.Getenv("DATABASE_URL"))
}
All initialization belongs in main() or a run() function so it can be tested and errors can be handled.
Reading config in business logic
// BAD -- couples handler to environmentfunc(s *Server) handleSendEmail(w http.ResponseWriter, r *http.Request) {
apiKey := os.Getenv("SENDGRID_API_KEY") // don't do this
}
Inject configuration values or clients through constructors.
