golang-rules

name	golang-rules
description	Go coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .go, go.mod, go.sum, Gin, Echo, Gorilla, testing, gofmt. Load when writing, reviewing, or editing Go code.
effort	medium
user-invocable	false
allowed-tools	Read

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.

Go Security

Input Validation

• Validate all input at API boundaries. Use struct tags or manual validation.
• Use validator package for struct validation: validate:"required,email".
• Parse and validate numeric IDs: strconv.Atoi() with error checking.
• Limit request body size: http.MaxBytesReader(w, r.Body, maxBytes).

SQL Injection

• Always use parameterized queries: db.Query("SELECT * FROM users WHERE id = $1", id).
• Never concatenate user input into SQL strings.
• Use sqlx.In() for safe dynamic IN clauses.
• Use ORM query builders (GORM, Ent) for dynamic query construction.

Command Injection

• Use exec.Command("binary", args...) with separate arguments, not shell strings.
• Never use exec.Command("sh", "-c", userInput).
• Validate and sanitize file paths against traversal attacks.
• Use filepath.Clean() and verify paths are within allowed directories.

Cryptography

• Use crypto/rand for random values, never math/rand for security.
• Use bcrypt or argon2 for password hashing: golang.org/x/crypto/bcrypt.
• Use crypto/subtle.ConstantTimeCompare() for timing-safe comparisons.
• Use crypto/tls with tls.Config{MinVersion: tls.VersionTLS12}.

Secrets

• Load secrets from environment variables: os.Getenv("SECRET_KEY").
• Never hardcode secrets, tokens, or API keys in source code.
• Use go-envconfig or similar for validated env var loading.
• Use Go build tags or ldflags for build-time configuration.

HTTP Security

• Set ReadTimeout, WriteTimeout, IdleTimeout on http.Server.
• Use helmet-equivalent headers: HSTS, X-Content-Type-Options, X-Frame-Options.
• Implement rate limiting with golang.org/x/time/rate or middleware.
• Use net/http with TLS. Never serve production HTTP without encryption.

Concurrency Safety

• Use sync.Mutex or sync.RWMutex for shared mutable state.
• Run go test -race in CI to detect data races.
• Avoid shared state where possible. Prefer channels for communication.
• Use atomic package for simple counters and flags.

Dependencies

• Run govulncheck ./... in CI to check for known vulnerabilities.
• Use go mod tidy to remove unused dependencies.
• Pin dependencies via go.sum. Review dependency changes in PRs.
• Audit transitive dependencies. Use go mod graph to inspect the tree.

Error Information Disclosure

• Never expose internal error messages to clients.
• Log detailed errors server-side, return generic messages to clients.
• Use error codes for machine-readable error classification.
• Do not include stack traces in production API responses.

Go Testing

Framework

• Use the standard testing package. No external test frameworks required.
• Use testify/assert and testify/require for readable assertions.
• Use testify/mock or mockgen for generating mocks.
• Use go test -race in CI to detect data races.

File Naming

• Test files: *_test.go in the same package.
• Black-box tests: use package foo_test to test only exported API.
• White-box tests: use package foo to test internals.
• Test helpers: testutil_test.go or testdata/ directory.

Table-Driven Tests

• Use table-driven tests for functions with multiple input/output cases.
• Name each case: {name: "empty input returns error", input: "", wantErr: true}.
• Use t.Run(tc.name, func(t *testing.T) { ... }) for subtests.
• Use t.Parallel() in subtests when tests are independent.

Test Helpers

• Use t.Helper() in helper functions for correct line reporting.
• Use t.Cleanup() for teardown instead of defer in test functions.
• Use testing.TB interface to share helpers between tests and benchmarks.
• Use testdata/ directory for test fixtures (excluded from build).

Mocking

• Define interfaces at the consumer, not the provider.
• Use mockgen to auto-generate mocks from interfaces.
• Use httptest.NewServer() for HTTP integration tests.
• Use httptest.NewRecorder() for handler unit tests.

Integration Tests

• Use build tags: //go:build integration to separate from unit tests.
• Use testcontainers-go for database/service containers in tests.
• Use t.Setenv() (Go 1.17+) for environment variable testing.

Benchmarks

• Use func BenchmarkXxx(b *testing.B) with b.N loop.
• Use b.ResetTimer() after expensive setup.
• Use b.ReportAllocs() to track allocations.
• Run: go test -bench=. -benchmem.

Coverage

• Run: go test -coverprofile=coverage.out ./....
• View: go tool cover -html=coverage.out.
• Set minimum coverage threshold in CI.
• Focus coverage on business logic, not generated code.