Fiber Framework Guide

Applies to: Fiber v2.50+, Go 1.21+, High-Performance REST APIs, Microservices

Overview

Fiber is an Express-inspired web framework built on top of Fasthttp, the fastest HTTP engine for Go. It is designed for ease of use with zero memory allocation and performance in mind.

Key Features:

• Express-like API (familiar to Node.js developers)

• Built on Fasthttp (10x faster than net/http)

• Zero memory allocation in hot paths

• Built-in middleware collection

• WebSocket support, rate limiting, template engines

When to use Fiber:

• High-throughput APIs requiring maximum performance

• Teams familiar with Express.js migrating to Go

• Real-time applications with WebSockets

• Microservices requiring low latency

Project Structure

myapi/ ├── cmd/ │ └── api/ │ └── main.go # Application entry point ├── internal/ │ ├── config/ │ │ └── config.go # Configuration management │ ├── handler/ │ │ ├── handler.go # Handler container │ │ ├── user_handler.go # User handlers │ │ └── health_handler.go # Health check handlers │ ├── middleware/ │ │ ├── auth.go # JWT authentication │ │ ├── logger.go # Request logging │ │ └── recover.go # Panic recovery │ ├── model/ │ │ ├── user.go # User model │ │ └── dto.go # Data transfer objects │ ├── repository/ │ │ ├── repository.go # Repository interface │ │ └── user_repository.go # User repository │ ├── service/ │ │ ├── service.go # Service container │ │ ├── user_service.go # User business logic │ │ └── auth_service.go # Authentication service │ └── router/ │ └── router.go # Route definitions ├── pkg/ │ ├── validator/ │ │ └── validator.go # Custom validator │ └── response/ │ └── response.go # Response helpers ├── go.mod ├── go.sum └── README.md

• internal/ for private application code (not importable externally)

• pkg/ for reusable shared libraries

• cmd/ for application entry points

• Handlers are thin; business logic lives in services

• Data access isolated in repositories

Application Setup

// cmd/api/main.go package main

import ( "context" "log" "os" "os/signal" "syscall" "time"

"github.com/gofiber/fiber/v2"
"github.com/gofiber/fiber/v2/middleware/cors"
"github.com/gofiber/fiber/v2/middleware/helmet"
"github.com/gofiber/fiber/v2/middleware/limiter"
"github.com/gofiber/fiber/v2/middleware/requestid"

"myapi/internal/config"
"myapi/internal/handler"
"myapi/internal/middleware"
"myapi/internal/repository"
"myapi/internal/router"
"myapi/internal/service"

)

func main() { cfg, err := config.Load() if err != nil { log.Fatalf("Failed to load config: %v", err) }

db, err := config.NewDatabase(cfg)
if err != nil {
    log.Fatalf("Failed to connect to database: %v", err)
}

app := fiber.New(fiber.Config{
    AppName:      cfg.AppName,
    ReadTimeout:  cfg.ReadTimeout,
    WriteTimeout: cfg.WriteTimeout,
    IdleTimeout:  cfg.IdleTimeout,
    BodyLimit:    cfg.BodyLimit,
    Prefork:      cfg.Prefork,
    ErrorHandler: customErrorHandler,
})

// Global middleware stack
app.Use(requestid.New())
app.Use(middleware.Logger())
app.Use(middleware.Recover())
app.Use(cors.New(cors.Config{
    AllowOrigins:     cfg.CORSAllowOrigins,
    AllowMethods:     "GET,POST,PUT,DELETE,PATCH,OPTIONS",
    AllowHeaders:     "Origin,Content-Type,Accept,Authorization",
    AllowCredentials: true,
}))
app.Use(helmet.New())
app.Use(limiter.New(limiter.Config{
    Max:        cfg.RateLimitMax,
    Expiration: cfg.RateLimitExpiration,
    KeyGenerator: func(c *fiber.Ctx) string {
        return c.IP()
    },
    LimitReached: func(c *fiber.Ctx) error {
        return c.Status(fiber.StatusTooManyRequests).JSON(fiber.Map{
            "error": "Rate limit exceeded",
        })
    },
}))

// Initialize layers (dependency injection)
repos := repository.NewRepositories(db)
services := service.NewServices(repos, cfg)
handlers := handler.NewHandlers(services)

router.Setup(app, handlers, services.Auth)

// Graceful shutdown
go func() {
    if err := app.Listen(":" + cfg.Port); err != nil {
        log.Fatalf("Failed to start server: %v", err)
    }
}()

quit := make(chan os.Signal, 1)
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
<-quit

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

if err := app.ShutdownWithContext(ctx); err != nil {
    log.Fatalf("Server forced to shutdown: %v", err)
}

sqlDB, _ := db.DB()
sqlDB.Close()

}

func customErrorHandler(c *fiber.Ctx, err error) error { code := fiber.StatusInternalServerError message := "Internal Server Error"

if e, ok := err.(*fiber.Error); ok {
    code = e.Code
    message = e.Message
}

return c.Status(code).JSON(fiber.Map{
    "error":   message,
    "code":    code,
    "request": c.Locals("requestid"),
})

}

Routing and Grouping

// internal/router/router.go func Setup(app *fiber.App, h *handler.Handlers, authService service.AuthService) { // Health checks (public) app.Get("/health", h.Health.Health) app.Get("/ready", h.Health.Ready)

// API v1
v1 := app.Group("/api/v1")

// Auth routes (public)
auth := v1.Group("/auth")
auth.Post("/login", h.User.Login)
auth.Post("/register", h.User.Create)

// Protected auth routes
authProtected := auth.Group("", middleware.Auth(authService))
authProtected.Get("/profile", h.User.GetProfile)

// User routes (protected)
users := v1.Group("/users", middleware.Auth(authService))
users.Get("/", h.User.GetAll)
users.Get("/:id", h.User.GetByID)
users.Put("/:id", h.User.Update)
users.Delete("/:id", middleware.RequireRole("admin"), h.User.Delete)

}

Routing rules:

• Group routes by resource and version (/api/v1/users )

• Apply auth middleware at the group level, not per-route

• Use role-based middleware for fine-grained access control

• Health and readiness checks always public, at root level

Middleware

Authentication Middleware

func Auth(authService service.AuthService) fiber.Handler { return func(c *fiber.Ctx) error { authHeader := c.Get("Authorization") if authHeader == "" { return fiber.NewError(fiber.StatusUnauthorized, "Missing authorization header") }

    parts := strings.SplitN(authHeader, " ", 2)
    if len(parts) != 2 || parts[0] != "Bearer" {
        return fiber.NewError(fiber.StatusUnauthorized, "Invalid authorization format")
    }

    claims, err := authService.ValidateToken(parts[1])
    if err != nil {
        return fiber.NewError(fiber.StatusUnauthorized, "Invalid token")
    }

    c.Locals("userID", claims.UserID)
    c.Locals("userEmail", claims.Email)
    c.Locals("userRole", claims.Role)

    return c.Next()
}

}

Role-Based Access

func RequireRole(roles ...string) fiber.Handler { return func(c *fiber.Ctx) error { userRole, ok := c.Locals("userRole").(string) if !ok { return fiber.NewError(fiber.StatusForbidden, "Access denied") }

    for _, role := range roles {
        if userRole == role {
            return c.Next()
        }
    }

    return fiber.NewError(fiber.StatusForbidden, "Insufficient permissions")
}

}

Custom Logger and Recovery

func Logger() fiber.Handler { return func(c *fiber.Ctx) error { start := time.Now() err := c.Next() log.Printf("[%s] %s %s %d %s", c.Method(), c.Path(), c.IP(), c.Response().StatusCode(), time.Since(start)) return err } }

func Recover() fiber.Handler { return func(c *fiber.Ctx) error { defer func() { if r := recover(); r != nil { log.Printf("Panic recovered: %v\n%s", r, debug.Stack()) c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{ "error": "Internal server error", }) } }() return c.Next() } }

Request Handling and Validation

Generic Body Validator

func ValidateBody[T any](c *fiber.Ctx, v *CustomValidator) (*T, error) { var body T if err := c.BodyParser(&body); err != nil { return nil, fiber.NewError(fiber.StatusBadRequest, "Invalid request body") } if err := v.Validate(&body); err != nil { return nil, err } return &body, nil }

DTO Pattern with Validation Tags

type CreateUserRequest struct { Email string json:"email" validate:"required,email,max=255" Password string json:"password" validate:"required,min=8,max=72" Name string json:"name" validate:"required,min=2,max=100" }

type UpdateUserRequest struct { Email string json:"email" validate:"omitempty,email,max=255" Name string json:"name" validate:"omitempty,min=2,max=100" }

Response Helpers

func Success(c *fiber.Ctx, data interface{}) error { return c.JSON(fiber.Map{"success": true, "data": data}) }

func Created(c *fiber.Ctx, data interface{}) error { return c.Status(fiber.StatusCreated).JSON(fiber.Map{"success": true, "data": data}) }

func Error(c *fiber.Ctx, code int, message string) error { return c.Status(code).JSON(fiber.Map{"success": false, "error": message}) }

func Paginated(c *fiber.Ctx, data interface{}, page, pageSize int, total int64) error { totalPages := int(total) / pageSize if int(total)%pageSize > 0 { totalPages++ } return c.JSON(fiber.Map{ "success": true, "data": data, "meta": fiber.Map{ "page": page, "page_size": pageSize, "total_items": total, "total_pages": totalPages, }, }) }

Error Handling

• Use fiber.NewError(code, message) for HTTP errors in handlers

• Implement a custom ErrorHandler on the app for consistent responses

• Return domain errors from services; map them to HTTP codes in handlers

• Never expose internal error details to clients

func (h *UserHandler) Create(c *fiber.Ctx) error { req, err := validator.ValidateBody[model.CreateUserRequest](c, h.validator) if err != nil { if _, ok := err.(*fiber.Error); ok { return err } return response.ValidationError(c, err) }

user, err := h.service.Create(c.Context(), req)
if err != nil {
    if errors.Is(err, service.ErrUserAlreadyExists) {
        return response.Error(c, fiber.StatusConflict, "User already exists")
    }
    return err // Falls through to custom error handler
}

return response.Created(c, user.ToResponse())

}

Best Practices

Performance

• Enable Prefork for multi-core utilization in production

• Use Fasthttp's zero-allocation patterns

• Configure appropriate read/write/idle timeouts

• Use connection pooling for databases (25 max open, 5 min lifetime)

• Use fiber.Ctx.Context() for request-scoped context

Security

• Use helmet middleware for security headers

• Implement rate limiting per IP (built-in limiter middleware)

• Validate all inputs via go-playground/validator

• Use CORS middleware with explicit origins in production

• Hash passwords with bcrypt; use JWT HS256 for tokens

Code Organization

• Follow clean architecture: handler -> service -> repository

• Use dependency injection (no global state)

• Keep handlers thin (parse, validate, delegate, respond)

• Define interfaces where consumed, not where implemented

• Use DTO structs for request/response serialization

Error Handling

• Use a custom error handler on the Fiber app

• Return consistent JSON error responses with success , error , code

• Log errors with request context (request ID, method, path)

• Do not expose stack traces or internal details to clients

Commands

Development

go run cmd/api/main.go

Build

go build -o bin/api cmd/api/main.go

Production build

CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o bin/api cmd/api/main.go

Tests

go test ./... go test -cover ./... go test -race ./...

Swagger docs (with swag)

swag init -g cmd/api/main.go

Database migrations (with golang-migrate)

migrate -path migrations -database "$DATABASE_URL" up migrate -path migrations -database "$DATABASE_URL" down 1

Lint

golangci-lint run

Dependencies

Core: fiber/v2 , gofiber/swagger | Database: gorm , gorm/driver/postgres | Validation: go-playground/validator/v10 | Auth: golang-jwt/jwt/v5 , x/crypto/bcrypt | Testing: stretchr/testify | Docs: swaggo/swag

Advanced Topics

For detailed patterns and examples, see:

• references/patterns.md -- Handler examples, database, WebSocket, testing, and performance patterns

External References

• Fiber Documentation

• Fiber GitHub

• Fasthttp

• Fiber Recipes

• Fiber Awesome List