go-service

Go Service Layer Patterns

Thesis: Services own business logic and data access. They are framework-agnostic, verify resource membership, and never trust the caller to have checked permissions.

Refrain: Validate → Authorize → Execute → Respond

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

Structure

type XService struct {
    pool              *pgxpool.Pool
    paginationDefault int
    paginationMax     int
}
func NewXService(pool *pgxpool.Pool, paginationDefault, paginationMax int) *XService { ... }

This is the canonical shape for paginated CRUD services. Real services diverge based on their dependencies — NewUserService(pool, publicBaseURL), NewAuthService(pool, jwtSecret, jwtIssuer, accessDuration, refreshDuration, passwordResetTTL), NewFeatureService(pool) — but every service follows the same "concrete struct + constructor + framework-agnostic methods" rule. Match the constructor shape that fits the dependencies, not the template literally.

Before modifying a module's service (changes to status transitions, cross-module calls, or the API surface), read docs/modules/{module}/spec.md for state machine constraints and business rules. If available, also check docs/dependency-graph.md for blast radius and docs/flows.md for cross-module transaction boundaries.

• Constructor takes *pgxpool.Pool plus whatever the service genuinely needs (pagination config for list endpoints, external service handles, frontend URL for redirects, etc.).
• No Echo imports — services must be framework-agnostic. No echo.Context, no echo.NewHTTPError. Use apperror for errors, plain context.Context for context.
• Define input/output structs in the same file (e.g., CreateItemInput, ItemDetail).
• Return *Detail structs with formatted timestamps (time.RFC3339), not raw DB types.

Auth Pattern

Every method that operates on a scoped resource must verify membership, not just role:

// Resolve user → entity relationship
access, err := s.verifyResourceAccess(ctx, resourceID, userID)
// Then check specific permissions
if !access.IsAdmin { return apperror.Forbidden("...") }