Golang API Server Standards

Priority: P0 (CRITICAL)

Router Selection

• Standard Lib (

  net/http

  ): Use for simple services or when zero deps is required. Use

  http.ServeMux

  (Go 1.22+ has decent routing).
• Echo (

  labstack/echo

  ): Recommended for production REST APIs. Excellent middleware support, binding, and error handling.
• Gin (

  gin-gonic/gin

  ): High performance alternative.

Guidelines

• Graceful Shutdown: MUST implement graceful shutdown to handle in-flight requests on termination (SIGINT/SIGTERM).
• DTOs: Separate Domain structs from API Request/Response structs. Map between them.
• Middleware: Use middleware for cross-cutting concerns (Logging, Recovery, CORS, Auth, Tracing).
• Health Checks: Always include

  /health

  and

  /ready

  endpoints.
• Content-Type: Enforce

  application/json

  for REST APIs.

Middleware Pattern

• Standard:

  func(next http.Handler) http.Handler

• Echo implementation:

  func(next echo.HandlerFunc) echo.HandlerFunc

Anti-Patterns

• Business Logic in Handlers: Handlers should only parse request -> call service -> format response.
• Global Router: Don't use global router variables. Pass router instance.

References

• Middleware Patterns
• Graceful Shutdown