golang-patterns

Wrap errors with context using fmt.Errorf and the %w verb, define sentinel errors with errors.New for common cases, and create custom error types for domain-specific failures. Check errors with errors.Is for sentinel values and errors.As for typed errors.

Use buffered channels or select statements with ctx.Done() so goroutines can exit when the context is cancelled. Coordinate multiple goroutines with errgroup or sync.WaitGroup, and always ensure channels are closed by their sender.

Place entry points in cmd/, private application code in internal/ (handler, service, repository, config), public libraries in pkg/, API definitions in api/, and test fixtures in testdata/. Keep package names short, lowercase, and free of underscores.

Functions should accept interfaces and return concrete struct types. Define small, focused interfaces in the consumer package where they are used, not in the provider package, and compose larger interfaces from single-method ones like Reader and Writer.

Use functional options when a constructor has many optional parameters with sensible defaults, such as server timeouts or loggers. Define an Option type as func(*T), provide WithX helpers, and apply them in a variadic constructor.

Run go vet, staticcheck, and golangci-lint with linters like errcheck, gosimple, ineffassign, unused, gofmt, and goimports. Also run go test with -race and -cover flags to detect data races and measure coverage.