toolchains-golang-core

name	toolchains-golang-core
description	Go 1.22-1.24 core patterns for minimalism, efficiency, code reuse, and performance
version	1.1.0
category	toolchains-golang
tags	["golang","go","patterns","performance","minimalism","efficiency"]
effort	medium

Go Core Patterns

Quick Start

• Accept interfaces, return structs — small interfaces at the consumer site
• Pre-allocate slices/maps with make([]T, 0, n) / make(map[K]V, n)
• Wrap errors with %w; check with errors.Is / errors.As
• Always run go test -race ./... in CI
• Profile with go tool pprof before optimizing anything

---

Minimalism Patterns

• Accept interfaces, return structs — narrow interface params improve testability; concrete return types preserve extensibility
• Define interfaces at the consumer — the calling package defines what it needs; avoid coupling interface to implementation
• Keep interfaces small — 1-2 methods; compose with embedding: type ReadWriter interface { Reader; Writer }
• Functional options for constructors — func WithTimeout(d time.Duration) Option returns a closure; keeps New* signatures stable
• Unexported option fields — export With* functions, keep struct fields private; one construction path, predictable outcome
• Constructor naming — NewServer(opts ...Option) *Server; the injection point for interface-typed dependencies
• Avoid init() side effects — prefer explicit initialization in main() or constructors; init() hides execution order

---

Efficiency Patterns

• Pre-allocate slices — make([]T, 0, n) eliminates grow-copy cycles; reduces GC pressure ~30%
• Pre-allocate maps — make(map[K]V, n) avoids rehashing; over-estimate rather than under-estimate
• strings.Builder over + — internal []byte buffer; call b.Grow(n) to pre-size before writing
• sync.Pool for short-lived objects — reuse buffers, byte slices, response structs; always reset before returning to pool
• Avoid any / interface{} in hot paths — boxing causes heap allocation and dynamic dispatch; use concrete types or generics
• strconv over fmt.Sprintf in hot paths — fmt arguments escape to heap; strconv.Itoa, AppendInt stay on stack
• Value receivers for small immutable types — no pointer indirection; both T and *T satisfy value-receiver methods
• Pointer receivers for large structs or mutation — avoids copying; be consistent within a type (all pointer or all value)
• Return values not pointers for small types — keeps allocation on stack; reduces GC pressure in tight loops
• Move loop-invariant work outside loops — constant calculations inside hot loops multiply with iteration count

---

Code Reuse

• Generics: any for store/pass only — no operations needed; suitable for containers like Stack[T any]
• Generics: comparable for equality — required for map keys, sets, Contains(); any does not satisfy comparable
• Generics: constraints.Ordered for comparisons — covers int, float, string; needed for sort, min, max helpers
• Generics: prefer function params over method constraints — pass cmp func(T, T) int rather than requiring a Compare method
• Generics: start concrete, genericize on duplication — add type params only when the same logic repeats for multiple types
• Embed structs for implementation reuse — promoted fields and methods; override selectively; avoid deep embedding chains
• Domain packages over layer packages — internal/user/, internal/order/ not internal/handlers/, internal/services/
• No catch-all utils packages — every package has a focused purpose; move helpers into the domain that owns them

---

Modern Go (1.22-1.23)

• Range over integers (1.22) — for i := range 10 replaces for i := 0; i < 10; i++
• Loop variable fix (1.22) — each iteration creates new variables; closure capture bugs eliminated
• Enhanced ServeMux (1.22) — "GET /items/{id}" registers method + wildcard; r.PathValue("id") extracts segments
• Wildcard catch-all (1.22) — "/files/{path...}" matches remaining path; must appear at end of pattern
• Request.Pattern (1.23) — matched pattern available on the request for logging and observability
• Range over function iterators (1.23) — func(func(K, V) bool) as range expressions; stable in 1.23
• iter package (1.23) — iter.Seq[V] and iter.Seq2[K, V] standard types; foundation for custom iterators
• slices / maps iterators (1.23) — slices.All, slices.Collect; maps.Keys, maps.Values, maps.Collect
• unique package (1.23) — canonical interning of comparable values; deduplication and memory savings
• slog for structured logging — JSON handler in prod, text in dev; slog.SetDefault bridges legacy log.Printf calls
• Contextual log fields — pass request_id, user_id, trace_id via slog.With() to correlate log lines
• LogValuer for sensitive types — redact PII; skips expensive computation when log level is disabled

---

Modern Go (1.24)

• tool directive in go.mod (1.24) — track executable dependencies natively; go get -tool adds them, go tool <name> runs them. Replaces the old blank-import tools.go workaround
• Generic type aliases (1.24) — type Set[T comparable] = map[T]struct{} now parameterizable like defined types; alias generic instantiations without re-declaring
• Swiss Tables map (1.24) — runtime swaps the builtin map to a Swiss Tables implementation; measurable improvement on map-heavy workloads and faster large-map access with no code changes
• weak package + runtime.AddCleanup (1.24) — weak.Pointer[T] for caches/canonicalization maps that must not pin memory; AddCleanup supersedes SetFinalizer (multiple cleanups, interior pointers, no leak cycles)
• os.Root directory jail (1.24) — os.OpenRoot(dir) confines all subsequent Open/Create to that subtree; prevents path-traversal escapes in untrusted file handling
• testing.B.Loop() (1.24) — for b.Loop() replaces the for range b.N benchmark idiom; keeps args alive and runs setup once, removing a class of benchmark mistakes
• testing/synctest (1.24, experimental) — fake-clock virtual time + goroutine-blocking detection for deterministic concurrency tests; gate behind GOEXPERIMENT=synctest
• T.Context / T.Chdir (1.24) — per-test context auto-cancelled at test end; per-test working directory restored on cleanup; prefer over manual context.WithCancel + defer os.Chdir
• slog.DiscardHandler (1.24) — drop-in no-op handler; cleaner than slog.New(slog.NewTextHandler(io.Discard, nil)) for silencing logs in tests

---

Performance

• Profile first — go tool pprof for CPU, heap, mutex, goroutine; never optimize without measurement data
• inuse_space for leak detection — alloc_space is lifetime total; inuse_space is currently retained memory
• Escape analysis — go build -gcflags="-m" shows heap escapes; target hot-path allocations
• Returning pointers causes escape — local variable outlives function; prefer return-by-value for small types
• Closures in hot loops allocate — avoid closures in tight loops; pass values as explicit function arguments
• Struct field ordering — largest to smallest reduces padding; use fieldalignment linter to verify
• Avoid false sharing — pad cache lines between fields accessed by different goroutines in concurrent structs
• Size channels deliberately — unbuffered for synchronization; buffered with known capacity for decoupling; never unbounded
• errgroup for fan-out — golang.org/x/sync/errgroup propagates first error and waits for all goroutines; replaces manual WaitGroup + error channel
• Context cancellation — pass cancellable context.Context; check ctx.Done() in goroutine loops to prevent leaks

---

Testing

• Table-driven + t.Run — named subtests allow selective execution with -run TestFoo/case_name
• Parallel subtests — t.Parallel() inside t.Run reduces suite runtime ~30-40%; ensure no shared mutable state
• testify/require for setup, assert for checks — require stops immediately on failure; assert continues and collects failures
• httptest.NewServer — real HTTP on localhost; tests full request/response cycle without mocking transport
• Fuzz testing — f.Add(seed) then f.Fuzz(func(t *testing.T, s string){...}); run with -fuzz flag and -fuzztime in CI
• testcontainers-go — spin up real Postgres, Redis, or any Docker image during integration tests
• goleak.VerifyNone(t) — fails if goroutines survive after test completes; catches goroutine leaks early
• Always -race — go test -race ./... in CI; required for all concurrent code
• t.Cleanup — registered functions run LIFO after test; prefer over manual defer teardown

---

Error Handling

• Wrap with %w — fmt.Errorf("load config: %w", err) preserves chain for errors.Is / errors.As
• errors.Is for sentinel checks — traverses wrapping chain; replaces direct err == ErrNotFound comparison
• errors.As for typed extraction — var e *APIError; errors.As(err, &e) pulls typed error from any depth
• Sentinel errors as package vars — var ErrNotFound = errors.New("not found"); exported for expected recoverable conditions
• Custom error types for rich context — implement Error() string and Unwrap() error; carry HTTP status, codes, metadata
• Handle errors immediately — if err != nil right after the call; early return; no deep nesting
• errors.Join for concurrent errors — since Go 1.20; collect multiple goroutine errors into one returned value
• Panic only for programmer errors — nil map write, index out of bounds; never panic for expected runtime failures in libraries
• Recover at goroutine boundaries — defer func() { if r := recover(); r != nil { log... } }() prevents cascade crashes

---

Anti-Patterns

• Goroutine leak: unclosed channel — range over a channel blocks forever if sender never closes; always close from the sender
• Goroutine leak: unbuffered send, no receiver — goroutine blocks permanently; use buffered channel or select with ctx.Done()
• Goroutine leak: early return without draining — buffer results or use select with context so goroutines can exit
• time.Sleep for synchronization — use sync.WaitGroup, channels, or context; Sleep is a race condition
• Copying sync.Mutex / sync.WaitGroup — always pass by pointer; copying creates an independent, incorrect lock
• init() with side effects — database connections, file reads, HTTP calls in init() make testing and reuse impossible
• Naked returns in long functions — named returns with bare return obscure flow in functions longer than ~5 lines
• utils / common / helpers packages — signals unclear ownership; split into domain-specific packages instead