CLAUDE.md · labstack/echo

Sections

1. About This Project
2. Development Commands
3. Code Architecture
4. File Organization
5. Code Style
6. Testing

First lines (shown under the repo's MIT license)

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## About This Project

Echo is a high performance, minimalist Go web framework. This is the main repository for Echo v5, which is available as a Go module at `github.com/labstack/echo/v5`.

## Development Commands

The project uses a Makefile for common development tasks:

- `make check` - Run linting, vetting, and race condition tests (default target)
- `make init` - Install required linting tools (golint, staticcheck)
- `make lint` - Run staticcheck and golint
- `make vet` - Run go vet
- `make test` - Run short tests
- `make race` - Run tests with race detector
- `make benchmark` - Run benchmarks

Example commands for development:
```bash
# Setup development environment
make init

# Run all checks (lint, vet, race)
make check

# Run specific tests
go test ./middleware/...
go test -race ./...

# Run benchmarks
make benchmark
```

## Code Architecture

### Core Components

**Echo Instance (`echo.go`)**
- The `Echo` struct is the top-level framework instance
- Contains router, middleware stacks, and server configuration
- Not goroutine-safe for mutations after server start

**Context (`context.go`)**
- The `Context` struct represents HTTP request/response context
- Provides methods for request/response handling, path parameters, data binding
- Core abstraction for request processing

**Router (`router.go`)**
- Radix tree-based HTTP router with smart route prioritization
- Supports static routes, parameterized routes (`/users/:id`), and wildcard routes (`/static/*`)
- Each HTTP method has its own routing tree

**Middleware (`middleware/`)**
- Extensive middleware system with 50+ built-in middlewares
- Middleware can be applied at Echo, Group, or individual route level
- Common middleware: Logger, Recover, CORS, JWT, Rate Limiting, etc.

### Key Patterns

**Middleware Chain**
- Pre-middleware runs before routing
- Regular middleware runs after routing but before handlers
- Middleware functions have signature `func(next echo.HandlerFunc) echo.HandlerFunc`

**Route Groups**
- Routes can be grouped with common prefixes and middleware
- Groups support nested sub-groups
- Defined in `group.go`

**Data Binding**
- Automatic binding of request data (JSON, XML, form) to Go structs
- Implemented in `binder.go` with support for custom binders

**Error Handling**
- Centralized error handling via `HTTPErrorHandler`
- Automatic panic recovery with stack traces

## File Organization

- Root directory: Core Echo functionality (echo.go, context.go, router.go, etc.)
- `middleware/`: All built-in middleware implementations
- `_test/`: Test fixtures and utilities
- `_fixture/`: Test data files

## Code Style

- Go code uses tabs for indentation (per .editorconfig)
- Follows standard Go conventions and formatting
- Uses gofmt, golint, and staticcheck for code quality

## Testing

- Standard Go testing with `testing` package
- Tests include unit tests, integration tests, and benchmarks
- Race condition testing is required (`make race`)
- Test files follow `*_test.go` naming convention