Golang Rules

Go Rules

These rules come from app/rules/golang/ in ai-toolkit. They cover the project's standards for coding style, frameworks, patterns, security, and testing in Go. Apply them when writing or reviewing Go code.

Go Coding Style

Naming

• MixedCaps/mixedCaps only. No underscores in Go names (except test functions).
• Exported: PascalCase. Unexported: camelCase. Acronyms: HTTPClient, userID.
• Short variable names in small scopes: i, r, w, ctx, err.
• Descriptive names in larger scopes: userRepository, requestTimeout.
• Package names: short, lowercase, singular (auth, user, not utils, helpers).

Packages

• One package per directory. Package name = directory name.
• Avoid util, common, helpers packages. Name by what it provides.
• Keep package APIs small. Export only what consumers need.
• Use internal/ directory for packages not meant for external consumption.

Functions

• Accept interfaces, return structs.
• First parameter ctx context.Context if the function does I/O or may be cancelled.
• Return (result, error) tuple. Error is always last return value.
• Use named return values only for documentation, not for naked returns.
• Keep functions short. If >40 lines, consider splitting.

Error Handling

• Always check errors. Never use _ to discard errors silently.
• Wrap errors with context: fmt.Errorf("fetching user %s: %w", id, err).
• Use sentinel errors (var ErrNotFound = errors.New(...)) for expected conditions.
• Use errors.Is() and errors.As() for error checking, not type assertions.

Formatting

• Use gofmt / goimports. No formatting debates in Go.
• Use golangci-lint with a .golangci.yml config in CI.
• Use go vet as minimum static analysis.

Struct Design

• Use struct embedding for composition, not inheritance.
• Prefer value receivers for small structs, pointer receivers for large or mutable.
• Be consistent: all methods on a type use the same receiver type.
• Use struct literals with field names: User{Name: "Ada", Age: 30}.

Concurrency

• Do not start goroutines without a plan to stop them.
• Use sync.WaitGroup or errgroup.Group to coordinate goroutines.
• Use channels for communication, mutexes for state protection.
• Prefer context.Context for cancellation and timeouts over manual signaling.

Go Frameworks

Standard Library HTTP

• Use http.NewServeMux() (Go 1.22+ with method patterns) for simple APIs.
• Use http.HandlerFunc for handlers. Compose with middleware pattern.
• Use context.Context from r.Context() in all handlers.
• Use http.TimeoutHandler to prevent slow handlers from hanging.

Chi / Gorilla Mux

• Use Chi for routing with middleware chains and URL params.
• Use chi.URLParam(r, "id") to extract path parameters.
• Use middleware groups: r.Group(func(r chi.Router) { r.Use(authMiddleware) }).
• Prefer Chi over Gorilla Mux (Gorilla was archived, Chi actively maintained).

Gin / Echo

• Use Gin for high-performance APIs with built-in validation.
• Use binding tags: binding:"required,email" on struct fields.
• Use middleware for cross-cutting: logging, recovery, CORS, auth.
• Use c.ShouldBindJSON() over c.BindJSON() to handle errors yourself.

GORM / sqlx / pgx

• Use sqlx for SQL-first with struct scanning (lightweight).
• Use pgx directly for PostgreSQL-specific features and performance.
• Use GORM only when rapid prototyping outweighs SQL control.
• Always use prepared statements or parameterized queries.
• Use sqlx.In() for dynamic IN clauses safely.

gRPC

• Define services in .proto files. Generate Go code with protoc.
• Use interceptors for auth, logging, and tracing (equivalent to middleware).
• Use deadlines (context timeout) on every RPC call.
• Use streaming RPCs for real-time data, unary for request-response.

Configuration

• Use envconfig or viper for configuration from env/files.
• Use struct tags for env mapping: envconfig:"DATABASE_URL".
• Validate config at startup. Fail fast on invalid configuration.
• Use flag package for CLI arguments in tools and utilities.

Observability

• Use slog (Go 1.21+) for structured logging. Replace log package.
• Use OpenTelemetry for distributed tracing and metrics.
• Export metrics via Prometheus endpoint.
• Use pprof for CPU and memory profiling in development.

Project Layout

• Follow Standard Go Project Layout: cmd/, internal/, pkg/.
• Entry points in cmd/appname/main.go.
• Business logic in internal/. Shared libraries in pkg/.
• Use Makefile for common tasks: build, test, lint, run.

Go Patterns

Error Handling

• Wrap errors with context at each call site: fmt.Errorf("loading config: %w", err).
• Define domain error types with errors.New() or custom error structs.
• Use errors.Is() for sentinel errors, errors.As() for typed errors.
• Return errors, do not panic. Reserve panic for truly unrecoverable states.
• Handle errors immediately after the call. No deferred error checking.

Concurrency

• Use errgroup.Group for concurrent operations that may fail.
• Use sync.Once for one-time initialization (singleton pattern).
• Use sync.Map only for append-mostly maps with concurrent access.
• Use buffered channels as semaphores: sem := make(chan struct{}, maxConcurrency).
• Prefer context.WithTimeout over manual timers for deadline management.

Interface Design

• Keep interfaces small: 1-3 methods. Compose larger interfaces from smaller ones.
• Define interfaces where they are consumed, not where they are implemented.
• Use io.Reader, io.Writer, fmt.Stringer and standard interfaces where applicable.
• Avoid returning interfaces from functions. Return concrete types.

Options Pattern

• Use functional options for constructors with many optional parameters.
• Pattern: func WithTimeout(d time.Duration) Option { return func(c *Client) { c.timeout = d } }.
• Provide sensible defaults. Options override defaults.
• Use Option type alias: type Option func(*Config).

Dependency Injection

• Pass dependencies through constructor functions, not global variables.
• Accept interfaces in constructors: func NewService(repo UserRepo) *Service.
• Use wire or manual wiring in main() for dependency graph.
• Avoid init() functions for anything other than simple registration.

Resource Management

• Use defer for cleanup immediately after acquiring a resource.
• Use context.Context for cancellation propagation across goroutines.
• Close channels from the sender side, never the receiver.
• Use sync.Pool for frequently allocated temporary objects (buffers).

Anti-Patterns

• Global mutable state: use dependency injection instead.
• interface{} / any everywhere: use generics (Go 1.18+) or specific types.
• Goroutine leaks: always ensure goroutines can exit.
• Ignoring context.Context: propagate it through all I/O paths.
• Large interfaces: split into focused, composable pieces.