Echo Framework Guide

Applies to: Echo v4+, REST APIs, Microservices, High-Performance Web Applications Language Guide: @.claude/skills/go-guide/SKILL.md

Overview

Echo is a high-performance, extensible, minimalist Go web framework. It features an optimized HTTP router, middleware support, data binding, and rendering.

Use Echo when:

• You need high performance with minimal overhead
• You want a clean, intuitive API
• Built-in middleware matters (JWT, CORS, Gzip, etc.)
• You prefer automatic TLS via Let's Encrypt

Consider alternatives when:

• You want the most popular framework (use Gin)
• You need WebSocket support built-in (use Fiber)
• Maximum community resources are needed (use Gin)

Project Structure

myproject/
├── cmd/
│   └── api/
│       └── main.go           # Entry point
├── internal/
│   ├── config/
│   │   └── config.go         # Configuration
│   ├── handler/
│   │   ├── handler.go        # Handler container
│   │   ├── user.go           # User handlers
│   │   └── auth.go           # Auth handlers
│   ├── middleware/
│   │   ├── auth.go           # JWT middleware
│   │   └── custom.go         # Custom middleware
│   ├── model/
│   │   ├── user.go           # User model
│   │   └── response.go       # Response models
│   ├── repository/
│   │   ├── repository.go     # Repository interface
│   │   └── user.go           # User repository
│   ├── service/
│   │   ├── service.go        # Service container
│   │   └── user.go           # User service
│   └── validator/
│       └── validator.go      # Custom validators
├── pkg/
│   └── response/
│       └── response.go       # Response helpers
├── migrations/
├── .env.example
├── go.mod
├── go.sum
├── Makefile
└── README.md

• cmd/ for entry points; one main.go per binary
• internal/ for private application code; not importable externally
• handler/ contains Echo handler functions, thin HTTP layer only
• service/ holds business logic; no Echo or HTTP dependencies
• repository/ encapsulates data access; accepts context.Context
• model/ defines domain structs, request/response DTOs
• middleware/ for custom Echo middleware functions
• validator/ for custom validation rules via go-playground/validator

Application Setup

e := echo.New()
e.HideBanner = true
e.Validator = validator.NewCustomValidator()

// Global middleware (order matters)
e.Use(echoMw.Recover())   // First: catch panics
e.Use(echoMw.Logger())    // Second: log all requests
e.Use(echoMw.RequestID()) // Third: trace IDs
e.Use(echoMw.CORSWithConfig(echoMw.CORSConfig{
    AllowOrigins: cfg.CORSOrigins,
    AllowMethods: []string{http.MethodGet, http.MethodPost,
        http.MethodPut, http.MethodPatch, http.MethodDelete},
    AllowHeaders: []string{echo.HeaderOrigin,
        echo.HeaderContentType, echo.HeaderAccept,
        echo.HeaderAuthorization},
}))

Setup guidelines:

• Set e.HideBanner = true in production
• Register Recover() first to catch panics in all handlers
• Use RequestID() for distributed tracing
• Always implement graceful shutdown with e.Shutdown(ctx)
• See references/patterns.md for full main.go with graceful shutdown

Routing

Route Groups and Versioning

func setupRoutes(e *echo.Echo, h *handler.Handlers, authMw *middleware.AuthMiddleware) {
    // Health check (ungrouped)
    e.GET("/health", func(c echo.Context) error {
        return c.JSON(http.StatusOK, map[string]string{"status": "ok"})
    })

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

    // Public routes
    auth := v1.Group("/auth")
    auth.POST("/login", h.Auth.Login)
    auth.POST("/register", h.Auth.Register)
    auth.POST("/refresh", h.Auth.Refresh)

    // Protected routes
    users := v1.Group("/users")
    users.POST("", h.User.Create)
    users.Use(authMw.Authenticate)
    users.GET("", h.User.GetAll)
    users.GET("/me", h.User.GetCurrent)
    users.GET("/:id", h.User.GetByID)
    users.PUT("/:id", h.User.Update)
    users.DELETE("/:id", h.User.Delete, authMw.RequireAdmin)
}

Routing guidelines:

• Group routes by resource and version (/api/v1/users)
• Apply middleware at group level, not per-route when possible
• Use /:param for path parameters (e.g., /:id)
• Append per-route middleware as extra handler args (e.g., RequireAdmin)
• Keep health check outside API groups for monitoring tools

Middleware

Built-in Middleware (use these first)

Middleware	Purpose
Recover()	Catch panics, return 500
Logger()	Request logging
RequestID()	Unique request IDs
CORS()	Cross-origin requests
Gzip()	Response compression
RateLimiter()	Rate limiting
Secure()	Security headers
BodyLimit()	Request size limits

Custom Middleware Pattern

// Middleware that injects request-scoped values
func RequestTimerMiddleware(next echo.HandlerFunc) echo.HandlerFunc {
    return func(c echo.Context) error {
        start := time.Now()
        err := next(c)
        duration := time.Since(start)
        c.Response().Header().Set("X-Response-Time",
            duration.String())
        return err
    }
}

// Middleware with configuration
type RateLimitConfig struct {
    Rate  int
    Burst int
}

func RateLimitMiddleware(cfg RateLimitConfig) echo.MiddlewareFunc {
    limiter := rate.NewLimiter(
        rate.Limit(cfg.Rate), cfg.Burst,
    )
    return func(next echo.HandlerFunc) echo.HandlerFunc {
        return func(c echo.Context) error {
            if !limiter.Allow() {
                return c.JSON(http.StatusTooManyRequests,
                    model.ErrorResponse("rate limit exceeded"))
            }
            return next(c)
        }
    }
}

Middleware guidelines:

• Return echo.HandlerFunc from middleware
• Call next(c) to continue the chain; skip to short-circuit
• Configurable middleware returns echo.MiddlewareFunc
• Order matters: register Recover() first, then logging, then auth

Echo Context

Reading Values

func handler(c echo.Context) error {
    // Path params
    id := c.Param("id")

    // Query params
    page := c.QueryParam("page")
    search := c.QueryParam("q")

    // Form values
    name := c.FormValue("name")

    // Headers
    token := c.Request().Header.Get("Authorization")

    // Request-scoped values (set by middleware)
    userID, ok := c.Get("user_id").(uint)

    // Real IP (respects X-Forwarded-For)
    ip := c.RealIP()

    // Underlying context.Context for DB/service calls
    ctx := c.Request().Context()

    return c.JSON(http.StatusOK, data)
}

Context guidelines:

• Use c.Request().Context() when passing to services/repositories
• Use c.Get()/c.Set() for request-scoped values between middleware and handlers
• Type-assert values from c.Get() with ok check
• Never store echo.Context beyond the request lifecycle

Request Binding and Validation

Binding

type CreateUserRequest struct {
    Email     string `json:"email" validate:"required,email"`
    Password  string `json:"password" validate:"required,min=8"`
    FirstName string `json:"first_name" validate:"required,min=1,max=100"`
    LastName  string `json:"last_name" validate:"required,min=1,max=100"`
}

func (h *UserHandler) Create(c echo.Context) error {
    var req CreateUserRequest
    if err := c.Bind(&req); err != nil {
        return c.JSON(http.StatusBadRequest,
            model.ErrorResponse(err.Error()))
    }
    if err := c.Validate(&req); err != nil {
        return err // Custom validator returns HTTPError
    }
    // Process valid request...
}

Custom Validator

type CustomValidator struct {
    validator *validator.Validate
}

func NewCustomValidator() *CustomValidator {
    v := validator.New()
    v.RegisterTagNameFunc(func(fld reflect.StructField) string {
        name := strings.SplitN(fld.Tag.Get("json"), ",", 2)[0]
        if name == "-" {
            return ""
        }
        return name
    })
    return &CustomValidator{validator: v}
}

func (cv *CustomValidator) Validate(i interface{}) error {
    if err := cv.validator.Struct(i); err != nil {
        return echo.NewHTTPError(
            http.StatusBadRequest,
            formatValidationErrors(err),
        )
    }
    return nil
}

Binding guidelines:

• Always Bind then Validate as separate steps
• Use struct tags: json for binding, validate for rules
• Register custom validator on e.Validator at startup
• Return structured validation errors, not raw messages
• Use pointer fields for optional/partial updates (*string)

Response Patterns

Use a consistent JSON envelope across all endpoints:

// Success: c.JSON(http.StatusOK, SuccessResponse(data))
// Error:   c.JSON(http.StatusNotFound, ErrorResponse("not found"))
// Delete:  c.NoContent(http.StatusNoContent)

type Response struct {
    Success bool        `json:"success"`
    Data    interface{} `json:"data,omitempty"`
    Error   string      `json:"error,omitempty"`
}

func SuccessResponse(data interface{}) *Response {
    return &Response{Success: true, Data: data}
}

func ErrorResponse(msg string) *Response {
    return &Response{Success: false, Error: msg}
}

• Use response DTOs; never expose domain models directly (omit passwords, internal IDs)
• For paginated responses, include meta with page/total counts
• See references/patterns.md for PaginatedResponse struct

Error Handling

Domain Errors

var (
    ErrUserNotFound       = errors.New("user not found")
    ErrUserAlreadyExists  = errors.New("user already exists")
    ErrInvalidCredentials = errors.New("invalid credentials")
)

Handler Error Mapping

func (h *UserHandler) GetByID(c echo.Context) error {
    id, err := strconv.ParseUint(c.Param("id"), 10, 32)
    if err != nil {
        return c.JSON(http.StatusBadRequest,
            model.ErrorResponse("invalid user ID"))
    }

    user, err := h.userService.GetByID(
        c.Request().Context(), uint(id),
    )
    if err != nil {
        if errors.Is(err, service.ErrUserNotFound) {
            return c.JSON(http.StatusNotFound,
                model.ErrorResponse(err.Error()))
        }
        return c.JSON(http.StatusInternalServerError,
            model.ErrorResponse(err.Error()))
    }

    return c.JSON(http.StatusOK,
        model.SuccessResponse(user.ToResponse()))
}

Error handling guidelines:

• Define domain errors as sentinel values in the service layer
• Map domain errors to HTTP status codes in handlers only
• Use errors.Is() / errors.As() for error checking
• Never expose internal errors to clients in production
• Log detailed errors server-side; return safe messages to clients

Configuration

• Load from environment variables (12-factor app) via godotenv
• Provide sensible defaults for development only
• Never hardcode secrets; use empty defaults to force explicit config
• Parse durations and validate at startup, not at use time
• See references/patterns.md for full config struct example

Commands Reference

# Initialize project
go mod init myproject

# Install dependencies
go mod tidy

# Run development server
go run cmd/api/main.go

# Build binary
go build -o bin/api cmd/api/main.go

# Run tests
go test ./...
go test -v -cover ./...

# Run with race detection
go test -race ./...

# Lint
golangci-lint run

# Database migrations (golang-migrate)
migrate -path migrations -database "$DATABASE_URL" up
migrate -path migrations -database "$DATABASE_URL" down

Dependencies

// Core
github.com/labstack/echo/v4          // Web framework
github.com/go-playground/validator/v10 // Validation
github.com/golang-jwt/jwt/v5          // JWT auth
github.com/joho/godotenv              // Env loading

// Database
gorm.io/gorm                          // ORM
gorm.io/driver/postgres               // PostgreSQL driver

// Crypto
golang.org/x/crypto                    // bcrypt, etc.

// Testing
github.com/stretchr/testify           // Assertions and mocks

Best Practices Checklist

Echo-Specific

• Use custom validator with go-playground/validator
• Use echo.Context for request handling only (not in services)
• Use middleware groups for route organization
• Return errors from handlers for centralized handling
• Use echo.Bind for request binding
• Configure proper timeouts and graceful shutdown
• Set e.HideBanner = true in production

Performance

• Configure database connection pooling (SetMaxOpenConns, etc.)
• Implement pagination for list endpoints
• Use Gzip() middleware for response compression
• Implement request logging middleware for observability
• Use BodyLimit() to prevent oversized requests

Advanced Topics

For detailed patterns and examples, see:

• references/patterns.md -- Handler examples, database repository, authentication, WebSocket, testing patterns

External References

• Echo Documentation
• Echo GitHub
• Echo Cookbook
• GORM Documentation
• go-playground/validator