go-services

Go HTTP Services AI Skill Guide (Claude)

Overview & Engine Architecture

Go services ship as single static binaries: net/http (or a thin http.Handler router) accepts traffic, goroutines handle concurrency, and context.Context carries deadlines and cancellation into DB/HTTP clients. Since Go 1.22, stdlib ServeMux supports method + wildcard patterns (GET /items/{id}). Agents treat timeouts, context propagation, and deadline-bounded Shutdown as first-class contracts—not optional polish.

┌─────────────────────────────────────────────────────────────┐
│                 Go HTTP service path                          │
│                                                             │
│  main / cmd/<svc>                                           │
│  ├── signal.NotifyContext → cancel root ctx                 │
│  └── http.Server{ timeouts + Handler }                      │
│                                                             │
│  Handler stack                                              │
│  ├── middleware: recover / request-id / access log          │
│  ├── ServeMux: "METHOD /path/{id}" → handlers               │
│  └── handlers → services → stores (ctx first arg)           │
│                                                             │
│  Lifecycle                                                  │
│  ├── readiness flip → srv.Shutdown(fresh deadline ctx)      │
│  └── close pools / workers (reverse init order)             │
└─────────────────────────────────────────────────────────────┘

When to use / when not to

Use when

• Building REST/JSON backends, workers fronted by HTTP, or internal APIs in Go.
• Structuring cmd/ + internal/ modules, middleware, and table-driven go test.
• Fixing leaked goroutines, ignored contexts, missing server timeouts, or broken graceful drain.

Do not use when

• The product surface is GraphQL schema/resolvers → @graphql-apis (Go host still OK for transport).
• You need managed PaaS Node stacks as the primary runtime → @nodejs / @express / @nextjs.
• Someone asks to hardcode secrets, open 0.0.0.0 admin debug without auth, or disable TLS verification in prod → refuse; use env/secret stores and @docker/@vault patterns.