go-samples-gin-restful: Instructions file for Claude Code

CLAUDE.md

Overview

REST API for managing football players built with Go and Gin Web Framework. Implements CRUD operations with SQLite + GORM, in-memory caching, and Swagger documentation. Architectural decisions are documented as ADRs in docs/adr/ — check them before proposing structural changes.

Structure

Layer rule: Routes → Controllers → Services → Data. Never skip a layer. Controllers must not contain business logic.

Coding Guidelines

• Pointers: Use pointers for structs in function signatures to avoid copying
• Logging: Standard log package (structured slog for new code)
• Migrations: migrations/embed.go embeds all .sql files into the binary at compile time (//go:embed *.sql). No migration files are needed on the filesystem at runtime. Migration files use 5-digit zero-padded names (00001_, 00002_).
• Seed tools: scripts in tools/ use //go:build ignore and are excluded from normal builds. Run individually with go run ./tools/seed_001_starting_eleven.go (recreates the DB from scratch).
• Tests: Table-driven tests for multiple cases; target 80%+ coverage for service, controller, route packages
• Test strategy: Integration tests with real in-memory SQLite for all happy paths and expected branches. Use MockPlayerService only for error branches that cannot be triggered with a healthy database (e.g. simulated connection failures). If a scenario can be exercised with a real database, it must use a real database.
• Mock pattern: MockPlayerService uses opt-in function fields — only set the Func relevant to the test scenario; unset methods return safe zero-value defaults. Never create a new mock type per test.
• Test naming: TestRequest{METHOD}{Resource}{Condition}Response{Outcome}:
  • Resource: explicit endpoint target — Players, PlayerByID, PlayerBySquadNumber
  • Condition: Existing, NonExisting, Unknown, InvalidParam, Mismatch, EmptyBody, TrailingSlash, Validation, RetrieveError, CreateError, UpdateError, DeleteError
  • Outcome: StatusOK, StatusCreated, StatusNoContent, StatusBadRequest, StatusNotFound, StatusConflict, StatusUnprocessableEntity, StatusInternalServerError, or Players / Player for body assertions
  • Examples: TestRequestGETPlayerByIDExistingResponseStatusOK, TestRequestPOSTPlayersEmptyBodyResponseStatusBadRequest, TestRequestDELETEPlayerByIDDeleteErrorResponseStatusInternalServerError
• Test godoc: Each Test* function must open with: // TestFuncName tests that a\n// {METHOD} request to {/path} {condition}\n// returns a {outcome}.
• Avoid: ignoring errors, panic in library code, global mutable state, interface{} without type assertions, complex goroutines for simple CRUD