go-gin-handlers

When to Use

• Creating new HTTP endpoints in a microservice
• Adding or modifying middleware
• Standardizing error responses
• Implementing request validation
• Setting up API versioning

Critical Patterns

Pattern	Rule
Handlers are thin	Handlers ONLY parse input, call application service, format output
No business logic	Zero domain logic in handlers — delegate to application layer
Standardized responses	ALL endpoints return the same JSON envelope
Validation at the edge	Validate request DTOs in the handler layer using binding tags
Context propagation	Always pass ctx from Gin to application service

Response Envelope

ALL API responses follow this structure:

Reference: assets/response.go

Handler Pattern

Reference: assets/handler.go

Error Mapping

Reference: assets/errors.go

Router Setup with Versioning

Reference: assets/router.go

Middleware Pattern

Reference: assets/auth_middleware.go

Commands

# Install Gin
go get -u github.com/gin-gonic/gin

# Run server locally
go run cmd/server/main.go

# Test endpoint
curl -X POST http://localhost:8080/api/v1/bookings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"caregiver_id": "uuid", "service_type": "walk", ...}'

Anti-Patterns

❌ Don't	✅ Do
Business logic in handlers	Call application service, return result
Raw c.JSON(500, ...) scattered	Use server.Fail() / server.OK()
Validate in application layer	Use Gin binding tags + ShouldBindJSON
Return different JSON shapes	Always use Response envelope
Parse JWT in every handler	Use auth middleware, read from c.GetString("user_id")