| name | nethttp-architect |
| version | 1.0.1 |
| description | Framework-specific delta on rest-api-architect — Go stdlib net/http (Go 1.22+ ServeMux, no router) on Go 1.26. Feature layout, struct-tag validation, RFC 7807 errors, JWT or IdP auth, graceful shutdown, OpenAPI via kin-openapi. Read rest-api-architect first for the cross-cutting REST conventions. Use when scaffolding or reviewing a stdlib net/http service. |
net/http Architecture
Targets the stdlib net/http on Go 1.26, using the Go 1.22+ enhanced ServeMux (method matching, path variables, host matching) — no router framework. Companion to go-architect, rest-api-architect, and sql-architect. Implementation skeletons in RECIPES.md; pinned deps in STACK.md.
1. Project structure — feature-based
Same shape as gin-architect and fastapi-architect: one folder per bounded context under internal/, each with handlers.go, service.go, repo.go, dto.go, queries/. Full tree in RECIPES.md.
handlers.go depends on service.go; never reaches into repo.go directly.service.go is pure Go — no net/http imports. Easy to unit-test.dto.go holds wire types; never reuse domain structs as DTOs.
2. Routing — http.ServeMux with method patterns (Go 1.22+)
The stdlib ServeMux supports method matching, path wildcards ({id}), and host matching. No third-party router needed. Registration skeleton in RECIPES.md.
- Method patterns:
"GET /v1/users/{id}" — method + path in one string. Mismatched methods auto-return 405 Method Not Allowed.
- Path variables:
id := r.PathValue("user_id") — typed parsing happens in your handler.
- Trailing slash:
"GET /v1/users/" matches everything under the prefix; "GET /v1/users/{$}" matches only the exact path. Be explicit.
- No "group" abstraction in stdlib — write the prefix per route or use a small helper. Don't reach for a router framework just for syntactic sugar.
3. Request validation
go-playground/validator (canonical per go-architect) — bind via json.NewDecoder(r.Body).Decode(&req) then validate.Struct(&req).
type CreateUserReq struct {
Email string `json:"email" validate:"required,email"`
Password string `json:"password" validate:"required,min=12"`
}
json.Decoder.DisallowUnknownFields() at decoder construction — equivalent of Pydantic's extra="forbid". Reject unknown fields rather than silently dropping them.- One shared
*validator.Validate stored on the handler, not per-request — instantiation is expensive.
- Limit body size: wrap
r.Body with http.MaxBytesReader(w, r.Body, 1<<20) before decode — prevents memory exhaustion from oversized payloads.
4. Response shaping
A tiny helper to serialise JSON consistently — every handler uses it.
func writeJSON(w http.ResponseWriter, status int, v any) {
w.Header().Set("Content-Type", "application/json; charset=utf-8")
w.WriteHeader(status)
if v != nil {
_ = json.NewEncoder(w).Encode(v)
}
}
- Set headers before
WriteHeader — once headers are sent, you can't change them.
http.StatusNoContent for empty responses (skip writeJSON body).- Return DTOs, not domain types. Same discipline as gin-architect.
5. Dependency injection
Explicit constructors. Dependencies wired in main.go; *Deps is passed where needed. For larger graphs, uber-go/fx (canonical per go-architect). Hand-wired is clearer for small services.
6. Lifespan & graceful shutdown
Identical pattern to gin-architect — the server abstraction is http.Server, not *gin.Engine. signal.NotifyContext for shutdown trigger; the cause records which signal (Go 1.26). All four timeouts (ReadHeaderTimeout, ReadTimeout, WriteTimeout, IdleTimeout) are mandatory in production — defaults are "unlimited," which is a DoS vector. Full skeleton in RECIPES.md.
7. Middleware — function wrapping
stdlib has no middleware abstraction. The standard pattern: a function that takes http.Handler and returns http.Handler. Compose with a tiny Chain helper (in RECIPES.md).
- Outermost first in
Chain — Recover wraps everything so even middleware panics are caught.
- Standard chain order: Recover → RequestID → SLog → CORS → GZip.
- Auth is per-route, not global — apply
AuthRequired only where needed (see §8).
- Never write your own logger middleware that calls
log.Printf — use slog (per go-architect).
8. Authentication & authorization
Patterns live in rest-api-architect/AUTH_PATTERNS.md. stdlib specifics:
- Pattern A — in-house JWT via
golang-jwt/jwt/v5 + argon2. Middleware skeleton in RECIPES.md.
- Pattern B — external IdP:
jwt.ParseWithClaims with a Keyfunc that resolves keys via cached JWKS. Verify aud and iss explicitly.
- Authorization per route, never global —
RequireScope middleware composed with AuthRequired (see RECIPES.md). When the wrap chain gets ugly, build a small helper that takes multiple Middlewares and the final handler.
9. Error handling — RFC 7807
Same problem package shape as gin-architect. Helpers take http.ResponseWriter + *http.Request instead of *gin.Context. Writer skeleton in RECIPES.md. The Recover middleware catches panics and emits a 500 problem with the correlation id — never a stack trace.
10. Concurrency, not "background tasks"
Same guidance as gin-architect — Go has no FastAPI-style BackgroundTasks. Detach with context.Background(), log errors, set timeouts.
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
go func() {
defer cancel()
if err := h.svc.SendWelcomeEmail(ctx, user.ID); err != nil {
slog.ErrorContext(ctx, "welcome email failed", "user_id", user.ID, "err", err)
}
}()
11. Testing
httptest.NewRecorder + the handler directly — no real socket. Skeleton in RECIPES.md.
testing/synctest (per go-architect §9) for any test that depends on goroutine completion timing — deterministic without time.Sleep.- Table-driven request-validation tests.
12. OpenAPI generation
stdlib net/http has no annotation-based generator like swaggo/swag (which is Gin-coupled). Two practical options:
getkin/kin-openapi — write the OpenAPI 3.1 spec in code, serve it at /v1/openapi.json, optionally use it for runtime request validation. The intended choice for stdlib.- Hand-written
openapi.yaml committed to the repo, served as a static file. Cheapest, but drifts; pair with the OpenAPI snapshot test from rest-api-architect §15.
CI snapshot-tests the spec either way.
When to pick net/http over Gin
- Minimal dependencies matter (binary size, supply chain, audit).
- Tight integration with stdlib middleware ecosystem (third-party
func(http.Handler) http.Handler chains work everywhere).
- Forward compatibility — Go's HTTP server gets faster every release; framework-coupled code lags.
- Predictable behavior — no framework-specific surprises (recovery semantics, body re-reads, etc.).
Pick Gin when: richer middleware/plugin ecosystem out of the box, team familiar with framework patterns, or you need features Gin provides that aren't in stdlib. Both bundles (gin and nethttp) are valid; this skill targets nethttp projects.
