go-fiber

REQUIRED BACKGROUND: This skill depends_on: [clean-code, backend-fundamentals]. Both are loaded transitively — clean-code gives universal code quality, backend-fundamentals gives stack-agnostic backend patterns (services/selectors, idempotency, envelopes, N+1, migrations, auth). This skill adds ONLY Fiber-specific layering on top.

Pre-Code Checklist

• Read docs/engineering/fiber-rules.md — canonical Fiber policy
• If touching HTTP handlers: read docs/playbooks/fiber-service.md
• If touching request parsing: read docs/api-contracts/error-format.md
• Confirm Fiber version in go.mod (v3, Go 1.25+; see references/fiber-v3-patterns.md)
• go vet ./... clean before editing

Handler Pattern

Every handler has the same signature and lifecycle:

func ListOrders(svc *service.Orders) fiber.Handler {
    return func(c fiber.Ctx) error {
        // 1. Parse + validate
        var q ListQuery
        if err := c.Bind().Query(&q); err != nil {
            return fiber.NewError(fiber.StatusBadRequest, "invalid query")
        }
        if err := validate.Struct(&q); err != nil {
            return fiber.NewError(fiber.StatusUnprocessableEntity, err.Error())
        }

        // 2. Call the service with a context (cancellation propagates)
        orders, err := svc.List(c.Context(), q)
        if err != nil {
            return err  // central error handler renders the envelope
        }

        // 3. Respond
        return c.Status(fiber.StatusOK).JSON(fiber.Map{
            "data": orders,
            "meta": fiber.Map{"count": len(orders)},
        })
    }
}

Rules:

• No business logic inside the handler. Orchestrate only.
• No direct DB calls. Handler → service → repository.
• Always pass c.Context() downstream — never context.Background().

Error Envelope

Central error handler in app.Config{}:

app := fiber.New(fiber.Config{
    ErrorHandler: func(c fiber.Ctx, err error) error {
        code := fiber.StatusInternalServerError
        msg  := "internal error"
        if e, ok := err.(*fiber.Error); ok {
            code = e.Code
            msg  = e.Message
        }
        return c.Status(code).JSON(fiber.Map{
            "error": fiber.Map{
                "code":    statusToSlug(code),
                "message": msg,
                "details": extractDetails(err),
            },
        })
    },
})