golang-api-server

name	golang-api-server
description	Build HTTP services, REST APIs, and middleware in Go. Use when building Go HTTP servers, REST APIs, or custom middleware.
metadata	{"triggers":{"files":["cmd/server/*.go","internal/adapter/handler/**"],"keywords":["http server","rest api","gin","echo","middleware"]}}

Golang API Server

Priority: P0 (CRITICAL)

Router Selection

• Standard Lib (net/http): Use for simple services or zero-dependency requirements. http.ServeMux (Go 1.22+) method-based routing.
• Echo (labstack/echo): Recommended for production REST APIs with middleware, binding, and error handling.
• Gin (gin-gonic/gin): High performance alternative.

Implementation Workflow

1. Choose router — Select based on complexity needs (stdlib for simple, Echo/Gin for production).
2. Separate concerns — Handlers parse requests, call services, and format responses. No business logic in handlers.
3. Add middleware — Use middleware for cross-cutting concerns (Logging, Recovery, CORS, Auth, Tracing).
4. Include health endpoints — Always expose /health and /ready endpoints.
5. Enforce content types — Require application/json for REST APIs.
6. Implement graceful shutdown — Handle SIGINT/SIGTERM to drain in-flight requests.

See graceful shutdown example and Echo handler patterns

Anti-Patterns

• No business logic in handlers: parse request, call service, and format response only.
• No global router vars: pass router instance via constructor or DI.
• No missing shutdown: handle SIGTERM to drain in-flight requests.

References

• Middleware Patterns
• Graceful Shutdown