go-handler

Go Handler Layer Patterns

Thesis: Handlers are thin translators between HTTP and services. They validate input, extract auth, delegate to services, and return JSON — nothing more.

Refrain: Extract → Validate → Delegate → Return

Reference files: auth.go, user.go, middleware/stack.go

Before modifying a module's handler (changes to validation, auth, or route registration), read docs/modules/{module}/spec.md for API surface and validation rules. For cross-module request chains, also check docs/flows.md.

Structure

type XHandler struct { xService xServicer }
func NewXHandler(xService *service.XService) *XHandler { ... }

• Handlers are thin — validate input, delegate to service, return JSON.
• No business logic in handlers. No direct DB access.
• Struct field is the interface (xServicer), constructor takes the concrete type. This is the standard pattern — make new-module generates it automatically.

Service Interfaces

Handlers use unexported interfaces (authServicer, userServicer, sseHubber), not concrete service types. This enables mock-based testing. Constructor takes concrete types (callers unchanged), struct field is the interface. See handler/interfaces.go.

Scaffold Output

make new-module name=items generates:

• handler/item.go — Handler with interface-typed service field
• handler/item_test.go — Mock struct + 5 test stubs (Create success, Create validation, List, GetByID not found, Delete)
• Interface entry appended to handler/interfaces.go
• Fill in test bodies for your specific validation logic and error paths.

Auth Extraction

Every protected handler starts with:

userID, err := requireUserID(c)
if err != nil { return err }
userType, err := requireUserType(c)
if err != nil { return err }

Role guards (when needed) go after extraction:

if userType != "admin" {
    return apperror.Forbidden("Only admins can create items")
}

Resource-level authorization is handled by the service layer, not the handler.