Go Language Cheatsheet

Go types and interfaces, control flow, errors, goroutines, channels, sync and context, the standard library, idioms such as functional options and table-driven tests, performance tooling and the go toolchain. Each entry gives the problem, how it works, runnable Go snippets, real-world notes and pitfalls.

Updated: 2026-10-07

27 entries

Quick tables

Reference and comparison tables for quick scanning.

Zero values & type quick reference

Every variable is initialised; `var x T` gives the zero value of T. Many types are usable as-is, a few (nil map write, nil func call) panic.

Zero values & type quick reference
TypeZero valueComparable?Notes
int, uint, ...`0`YesFixed size except `int`/`uint` (32 or 64 bit by platform).
float64`0`Yes`NaN != NaN`, so a NaN map key can never be found again.
string`""`YesImmutable; `len` counts bytes, not runes.
bool`false`Yes
pointer `*T``nil`YesDereferencing nil panics; calling a pointer-receiver method on nil is legal if the method tolerates it.
slice `[]T``nil`Only to `nil``len`, `cap`, `range`, `append` all work on nil. Encodes to JSON `null`, unlike an empty slice (`[]`).
map `map[K]V``nil`Only to `nil`Reading a nil map returns the zero value; writing panics; `delete` and `len` are fine.
channel `chan T``nil`Yes (identity)Send/receive on nil blocks forever; `close(nil)` panics. A nil channel in `select` is never ready.
func`nil`Only to `nil`Calling a nil func panics.
interface`nil` (no type, no value)Yes (may panic)Comparing two interfaces with the same uncomparable dynamic type panics. An interface holding a nil pointer is not `nil`.
structAll fields zeroedIf all fields are comparableMake the zero value useful (`sync.Mutex`, `bytes.Buffer`).
array `[N]T`N zeroed elementsIf the element type is comparableA value type: assignment and passing copy all N elements.

Not comparable (compile error with `==`, and not allowed as map keys): slices, maps, funcs, and any struct or array containing them.

Which synchronization tool?

Which synchronization tool?
NeedUseNotes
Protect shared state`Mutex` / `RWMutex`Mutex by default; RWMutex only when reads dominate and critical sections are not tiny
Counter or flag`sync/atomic``atomic.Int64`, `atomic.Bool` (Go 1.19); one word only, not multi-field invariants
Hand off ownership or dataChannelUnbuffered to synchronise, buffered to decouple; the sender closes
Wait for N goroutines`WaitGroup` / `errgroup``errgroup` (x/sync) adds first-error and cancellation; `Add` before `go`
Run something once`sync.Once``OnceFunc` / `OnceValue` (Go 1.21) for lazy init with a result
Cache of read-mostly keys`sync.Map`Only for write-once/read-many or disjoint key sets; otherwise a map plus a mutex
Bounded parallelismBuffered channel / `x/sync/semaphore``make(chan struct{}, n)` as a semaphore; `errgroup.SetLimit` also works
Cancellation and deadlines`context`First parameter `ctx`; always `defer cancel()`
Reuse temporary objects`sync.Pool`Reduces allocations, not a cache (see sync-pool in performance)

fmt verbs

Outputs were produced by running the code. Quotes around results mark leading or trailing spaces and are not printed.

fmt verbs
VerbMeaningExample (value → output)
`%v`Default format`P{1, "a"}` → `{1 a}`; `[]int{1, 2}` → `[1 2]`; `&P{1, "a"}` → `&{1 a}`
`%+v`Default, with struct field names`P{1, "a"}` → `{X:1 Y:a}`
`%#v`Go-syntax representation`P{1, "a"}` → `main.P{X:1, Y:"a"}`; `[]int{1, 2}` → `[]int{1, 2}`
`%T`Type of the value`1` → `int`; `3.0` → `float64`; `[]any{1}` → `[]interface {}`
`%%`A literal percent sign`%5.1f%%` with `99.5` → `" 99.5%"`
`%t`Boolean`true` → `true`
`%d`Integer, base 10`42` → `42`; `[]int{1, 2}` → `[1 2]`
`%b`Integer, base 2`42` → `101010`; `%#b` with `5` → `0b101`
`%o`Integer, base 8`42` → `52`; `%#o` with `8` → `010`
`%x` / `%X`Integer, base 16 (lower/upper); `#` adds `0x``255` → `ff` / `FF`; `%#x` with `255` → `0xff`; `-255` → `-ff`
`%c`Character for a code point`'G'` → `G`; `%3c` with `'x'` → `" x"`
`%q`Quoted character or string, safely escaped`'G'` → `'G'`; `%q` with `"hi\n"` → `"hi\n"`
`%U`Unicode code point`'G'` → `U+0047`; `%#U` with `'世'` → `U+4E16 '世'`
`%e`Scientific notation`1234.5678` → `1.234568e+03`
`%f`Decimal point, no exponent (default precision 6)`1234.5678` → `1234.567800`
`%g`Shortest of `%e`/`%f` that round-trips`1234.5678` → `1234.5678`; `1e21` → `1e+21`; `100000.0` → `100000`
`%s`String, or the `Error()`/`String()` result`"hi"` → `hi`; `errors.New("boom")` → `boom`; `[]string{"a", "b"}` → `[a b]`
`%q` on stringsQuoted and escaped; also works elementwise on slices`"hi\n"` → `"hi\n"`; `[]string{"a", "b c"}` → `["a" "b c"]`; `%#q` with `"hi"` → `` `hi` ``
`%x` on strings / `[]byte`Hex of the bytes; `% x` adds spaces`"hi"` → `6869`; `[]byte("Hello")` → `48656c6c6f`; `% X` → `48 65 6C 6C 6F`
`%p`Pointer address (varies per run)`&x` → `0xc000012345`
`%w`Wrap an error; valid only in `fmt.Errorf``fmt.Errorf("read: %w", io.EOF)` → `read: EOF`, and `errors.Is(err, io.EOF)` is true
`%6.2f`Width 6, precision 2`3.14159` → `" 3.14"`
`%-8s`Left-justify in width 8`"ab"` → `"ab "`
`%08d`Zero-pad to width 8 (sign counts)`42` → `00000042`; `-42` → `-0000042`
`%+d`Always print the sign`42` → `+42`
`%[1]d`Explicit argument index (reuse or reorder)`%[2]d %[1]d` with `1, 2` → `2 1`; `%[1]d %[1]b %[1]o` with `12` → `12 1100 14`
`%*d`Width taken from an argument`%*d` with `5, 42` → `" 42"`; `%-*d` with `5, 42` → `"42 "`
Wrong verb or arityNever panics; the output shows the problem (`go vet` catches these)`%d` with `"x"` → `%!d(string=x)`; missing arg → `%!d(MISSING)`; extra arg → `%!(EXTRA int=2)`

Implementing `String() string` or `Error() string` changes what `%v` and `%s` print; `GoString()` changes `%#v`. Printing a value from inside its own `String()` with `%v` recurses forever.

time layout reference (2006-01-02 15:04:05)

Layouts are written by showing how the reference time `Mon Jan 2 15:04:05 MST 2006` (the digits 1 2 3 4 5 6 7) would look. Examples format 2024-03-05 14:07:09.123456789 in a UTC+8 zone named CST.

time layout reference (2006-01-02 15:04:05)
ComponentLayout tokenExample
Year`2006``2024`
Year (2 digits)`06``24`
Month (zero-padded)`01``03`
Month (no padding)`1``3`
Month (short name)`Jan``Mar`
Month (full name)`January``March`
Day (zero-padded)`02``05`
Day (no padding)`2``5`
Day (space-padded)`_2``" 5"`
Weekday (short)`Mon``Tue`
Weekday (full)`Monday``Tuesday`
Hour (24h)`15``14`
Hour (12h, zero-padded)`03``02`
Hour (12h, no padding)`3``2`
AM/PM`PM` (or `pm`)`PM`
Minute`04` / `4``07` / `7`
Second`05` / `5``09` / `9`
Fraction, fixed digits`.000` (also `.000000`)`.123` / `.123456`
Fraction, trailing zeros trimmed`.999` (also `.999999999`)`.123` (omitted entirely when zero)
Zone abbreviation`MST``CST`
Zone offset`-0700` / `-07:00``+0800` / `+08:00`
Zone offset, `Z` for UTC`Z0700` / `Z07:00``+0800` / `+08:00`; in UTC: `Z`
`time.RFC3339``2006-01-02T15:04:05Z07:00``2024-03-05T14:07:09+08:00`
`time.RFC3339Nano``2006-01-02T15:04:05.999999999Z07:00``2024-03-05T14:07:09.123456789+08:00`
`time.DateOnly` (Go 1.20+)`2006-01-02``2024-03-05`
`time.TimeOnly` (Go 1.20+)`15:04:05``14:07:09`
`time.DateTime` (Go 1.20+)`2006-01-02 15:04:05``2024-03-05 14:07:09`
`time.Kitchen``3:04PM``2:07PM`

Layouts are matched by text, so `2006-1-2` and `2006-01-02` differ, and digits such as `1` to `6` inside literal text are read as tokens, so format such text in separate pieces. Parse without a zone assumes UTC.

go test flags

go test flags
FlagEffectExample
`-run`Run tests matching a regexp (unanchored; `/` splits subtest levels)`-run '^TestX$/case'`
`-skip`Skip tests matching a regexp (Go 1.20+)`-skip 'Integration'`
`-v`Print every test and its log output`go test -v ./...`
`-count`Run each test n times; `1` bypasses the result cache`-count=1`
`-race`Enable the data race detector (slower, more memory)`go test -race ./...`
`-cover` / `-coverprofile`Report coverage / write a profile for `go tool cover``-coverprofile=c.out`
`-bench` / `-benchmem` / `-benchtime`Run benchmarks, report allocations, set duration or count`-run '^$' -bench . -benchmem -benchtime 100x`
`-short`Sets `testing.Short()` to skip slow tests`go test -short ./...`
`-timeout`Fail and dump goroutines if the test binary runs too long (default 10m)`-timeout 30s`
`-parallel`Max concurrent `t.Parallel()` tests (default `GOMAXPROCS`)`-parallel 4`
`-shuffle`Randomize test order; prints the seed`-shuffle=on`, `-shuffle=12345`
`-failfast`Stop after the first failing test`-failfast`
`-tags`Enable build tags (e.g. integration tests)`-tags integration`
`-fuzz` / `-fuzztime`Fuzz one target; bound the run by time or `Nx` executions`-fuzz FuzzParse -fuzztime 30s`
`-cpuprofile` / `-memprofile`Write pprof profiles (single package only)`-cpuprofile cpu.out`
`-json`Emit machine-readable `test2json` events`go test -json ./... > out.json`

Results are cached only in package-list mode and with cacheable flags (`-run`, `-short`, `-v`, `-timeout`, `-parallel`, `-failfast`, `-benchtime`, ...); `-count=1` always re-runs.

go mod & module commands

go mod & module commands
CommandWhat it doesWhen
`go mod init <path>`Create `go.mod` with the module pathStarting a new module
`go mod tidy`Add missing and remove unused requirements, update `go.sum`After changing imports; in CI as `-diff`
`go get pkg@v1.2.3`Add or change a requirement (`@latest`, `@none` to remove)Adding or upgrading one dependency
`go get -u ./...`Upgrade dependencies of the packages to newer minor/patch versionsPlanned dependency refresh
`go list -m -u all`List all modules and the available updatesAuditing outdated dependencies
`go mod download`Fetch modules into the module cacheWarming caches in Docker/CI
`go mod vendor`Copy dependencies into `vendor/`Hermetic or offline builds
`go mod verify`Check cached modules still match their `go.sum` hashesSecurity check, CI
`go mod why -m <mod>`Show why a module or package is neededChasing an unexpected dependency
`go mod graph`Print the module requirement graphDebugging version selection
`go mod edit`Edit `go.mod` from scripts (`-replace`, `-require`, `-json`)Tooling and automation
`go work init/use/sync`Create and maintain a `go.work` workspaceDeveloping several local modules together
`go get -tool pkg` / `go tool name`Track and run executable dependencies (Go 1.24+)Pinning dev tools such as generators

Environment: `GOPROXY`, `GOSUMDB`, `GOPRIVATE` (sets `GONOPROXY`/`GONOSUMDB` defaults), `GOFLAGS=-mod=mod|vendor|readonly`, `GOWORK=off`.

Common linters

golangci-lint v2: `linters.default: standard` enables exactly the five marked yes; add the rest under `linters.enable`.

Common linters
LinterCatchesIn v2 default set?
`errcheck`Unchecked returned errorsYes
`govet`Everything `go vet` finds: printf verbs, copylocks, lost cancel, ...Yes
`ineffassign`Assignments whose value is never usedYes
`staticcheck`Bugs, deprecated API use and simplifications (v2 includes the old gosimple and stylecheck)Yes
`unused`Unused constants, variables, functions, types and fieldsYes
`gosec`Security issues: weak crypto, SQL built by string concat, file permissions, ...No
`revive`Style and naming rules (a configurable golint successor)No
`errorlint``==` on errors instead of `errors.Is/As`, `%v` instead of `%w`No
`bodyclose`Unclosed `http.Response.Body`No
`contextcheck`Functions that drop the incoming `context.Context`No
`gocritic`Assorted bug, performance and style diagnosticsNo
`misspell`Spelling mistakes in comments and stringsNo
`nolintlint`Malformed or unexplained `//nolint` directivesNo

gofmt, goimports, gofumpt and gci are formatters in v2 (top-level `formatters:`), not linters. Check the set with `golangci-lint linters`.

Language basics

Built-in and composite types, zero values, implicit interfaces, type assertions, the nil-interface trap, and the basics of generics.

The problem

Go has a small, static type system, and most bugs come from not knowing what a value is before you touch it: its zero value, whether it can be compared, whether an interface is really nil. Interfaces and generics are the two tools for writing code that works over many types without losing static checking.

How it works

  • Every type has a zero value (`0`, `""`, `false`, `nil`, or all fields zeroed), so `var x T` is always initialised. Good designs make the zero value useful.
  • Composite types: arrays `[N]T` are values (length is part of the type); slices `[]T` are (pointer, len, cap) views of an array; maps are hash tables that need `make` before writes; structs group fields.
  • A defined type (`type Celsius float64`) has the same underlying type but a different identity and its own method set; a type alias (`type A = B`) is just another name.
  • Interfaces are satisfied implicitly: any type with the right methods implements them, with no `implements` keyword. Define interfaces where they are consumed, and keep them small.
  • `any` is an alias for `interface{}`. Get the concrete value back with `v, ok := x.(T)` (never panics) or a `switch x := v.(type)`; the single-result form `x.(T)` panics on mismatch.
  • An interface value is (dynamic type, dynamic value) and is `nil` only if both are absent. Returning a nil `*MyErr` as `error` yields a non-nil interface, so `err != nil` is true.
  • Generics (Go 1.18+): `func Sum[T Number](xs []T) T`. A constraint is an interface that may list types (`~int | ~float64`); `~T` includes every type whose underlying type is T.
  • `comparable` allows `==` and map keys; since Go 1.20 it is satisfied by interface types too, which can still panic at run time if the dynamic type is not comparable. `cmp.Ordered` covers `<`.
  • Type arguments are usually inferred from function arguments; methods cannot declare their own type parameters, only the generic type can.

Go sketch

Go
import "fmt"

type Shape interface {
    Area() float64
}

type Rect struct{ W, H float64 }

func (r Rect) Area() float64 { return r.W * r.H }

type Number interface {
    ~int | ~int64 | ~float64
}

func Sum[T Number](xs []T) T {
    var total T
    for _, x := range xs {
        total += x
    }
    return total
}

type MyErr struct{}

func (*MyErr) Error() string { return "my error" }

func mayFail(fail bool) error {
    var p *MyErr
    if fail {
        p = &MyErr{}
    }
    // BUG: "return p" would return a non-nil error holding a nil *MyErr.
    if p == nil {
        return nil
    }
    return p
}

func describe(v any) string {
    switch x := v.(type) {
    case nil:
        return "nil"
    case int:
        return fmt.Sprintf("int %d", x)
    case Shape:
        return fmt.Sprintf("shape %.1f", x.Area())
    default:
        return fmt.Sprintf("other %T", x)
    }
}

func asRect(s Shape) (Rect, bool) {
    r, ok := s.(Rect)
    return r, ok
}

Zero values you can use directly, and the nil-map write trap.

Go
import "fmt"

type Stats struct {
    Count int
    Tags  []string
    Seen  map[string]bool
}

func (s *Stats) Add(tag string) {
    s.Count++
    // append works on a nil slice.
    s.Tags = append(s.Tags, tag)
    // A nil map must be made before writing, otherwise: panic.
    if s.Seen == nil {
        s.Seen = make(map[string]bool)
    }
    s.Seen[tag] = true
}

func zero() {
    var s Stats
    s.Add("a")
    fmt.Println(s.Count, len(s.Tags), s.Seen["a"])

    var arr [3]int
    b := arr
    b[0] = 9
    fmt.Println(arr, b)
}

In practice

  • io.Reader / io.Writer — One-method interfaces that make files, sockets, buffers and gzip streams interchangeable; the textbook case of small, consumer-side interfaces.
  • sort / slices / maps — `slices.Sort`, `slices.Index` and `maps.Keys`-style helpers (Go 1.21+) replaced many hand-written loops with constrained generics.
  • database/sql — `driver.Valuer` and `sql.Scanner` are implemented implicitly by user types such as nullable wrappers; no registration needed.
  • Pitfall — Returning a typed nil pointer as an `error` or interface makes `x != nil` true; return the literal `nil` instead.

Trade-offs

Pros

  • Implicit interfaces decouple packages: the consumer defines what it needs, producers need no import.
  • Zero values and a tiny type system keep code predictable and easy to read.
  • Generics remove copy-paste for containers and algorithms while staying statically checked.

Cons

  • Typed-nil in an interface is not `nil`; this bites most often with `error`.
  • `x.(T)` without the comma-ok form panics on mismatch; `comparable` types can still panic when comparing interfaces holding slices or maps.
  • Writing to a nil map panics, and a slice shares its backing array with its sub-slices, so `append` can silently overwrite data.
  • Generics are limited: no methods with type parameters, and overusing them where an interface suffices hurts readability.

Every form of for, switch without fallthrough, if with init, labels, and defer semantics (LIFO, argument timing, named results).

The problem

Go deliberately has one loop keyword, no `while`, no ternary and no implicit switch fallthrough. Knowing every form of `for`, how `switch` selects a branch, and exactly when `defer` evaluates its arguments avoids the classic bugs: captured loop variables, leaked file handles, and lost errors from deferred calls.

How it works

  • `for` has four shapes: three-clause `for i := 0; i < n; i++`, condition-only `for cond {}`, infinite `for {}`, and `for range`.
  • `range` works on slices/arrays (index, copy of element), strings (byte index, rune, decoding UTF-8), maps (random order), channels (until closed) and, since Go 1.22, integers: `for i := range 10`.
  • The range expression is evaluated once. Ranging over an array copies it unless you range over a pointer or the index only. Deleting map entries during iteration is safe; entries added may or may not be visited.
  • Since Go 1.22 (module `go 1.22` or later) each iteration of a `for` loop has its own copy of the loop variables, so closures and goroutines capture the per-iteration value.
  • `break` and `continue` apply to the innermost `for`, `switch` or `select`; a label (`outer:`) lets them target an outer loop. `goto` exists but is almost never needed.
  • `switch` runs the first matching case and does not fall through; use `fallthrough` explicitly (rare) or list values: `case 1, 2, 3:`. An expressionless `switch {}` is a clean if-else chain.
  • A type switch `switch v := x.(type)` branches on the dynamic type; `v` has the case's type in single-type cases. `fallthrough` is not allowed in it.
  • `if v, err := f(); err != nil {}` scopes `v` and `err` to the if/else chain; keep the happy path unindented by returning early.
  • `defer` runs when the function returns (not the block), in LIFO order. Arguments and the receiver are evaluated at the `defer` statement; a deferred closure can read and modify named results.

Go sketch

Go
import (
    "fmt"
    "os"
)

func loops() {
    for i := range 3 { // Go 1.22+
        fmt.Println(i)
    }
    n := 10
    for n > 1 {
        n /= 2
    }
    for i, r := range "héllo" {
        // i is the byte offset; r is a rune.
        fmt.Println(i, string(r))
    }
outer:
    for i := range 3 {
        for j := range 3 {
            if j == 2 {
                continue outer
            }
            if i == 2 {
                break outer
            }
            fmt.Println(i, j)
        }
    }
}

func classify(n int) string {
    switch {
    case n < 0:
        return "negative"
    case n == 0:
        return "zero"
    default:
        return "positive"
    }
}

func deferOrder() {
    x := 1
    defer fmt.Println("x when deferred:", x) // prints 1
    x = 2
    for i := range 3 {
        defer fmt.Println("deferred", i) // runs 2, 1, 0
    }
}

func firstLine(path string) (err error) {
    f, err := os.Open(path)
    if err != nil {
        return err
    }
    defer func() {
        // Keep the Close error if nothing else failed.
        if cerr := f.Close(); err == nil {
            err = cerr
        }
    }()
    return nil
}

Go 1.22 per-iteration loop variables, and why defer in a loop holds resources.

Go
import (
    "fmt"
    "os"
)

func capture() []func() int {
    var fs []func() int
    for i := range 3 {
        // Go 1.22+: each closure sees its own i (0, 1, 2).
        // Before 1.22 (or with an older go.mod) all of them saw 3.
        fs = append(fs, func() int { return i })
    }
    return fs
}

func processAll(paths []string) error {
    for _, p := range paths {
        // A defer here would run only when processAll returns,
        // keeping every file open. Wrap the body in a function instead.
        err := func() error {
            f, err := os.Open(p)
            if err != nil {
                return err
            }
            defer f.Close()
            _, err = fmt.Fprintln(os.Stderr, "opened", f.Name())
            return err
        }()
        if err != nil {
            return err
        }
    }
    return nil
}

In practice

  • net/http servers — Handlers conventionally `defer r.Body.Close()` and use early-return `if err != nil` blocks; nearly every Go service is written in this shape.
  • Go 1.22 loopvar change — Fixed a long-running source of goroutine bugs. It depends on the `go` line in go.mod, so old modules keep the old semantics until upgraded.
  • database/sql — `defer rows.Close()` right after a successful Query, and check `rows.Err()` after the loop; `defer tx.Rollback()` is the standard transaction safety net.
  • Pitfall — `defer` inside a long-running loop (workers, file walkers) accumulates until the function exits; extract the body into a helper function.

Trade-offs

Pros

  • One loop keyword and no implicit fallthrough keep control flow easy to scan.
  • `defer` puts cleanup next to acquisition, and runs on every return path and on panic.
  • `if`/`switch` init statements keep temporaries tightly scoped.

Cons

  • `defer` runs at function exit, not block exit; deferred calls in loops pile up.
  • Deferred arguments are evaluated immediately, so `defer log(time.Since(t))` measures nothing; wrap it in a closure.
  • Map iteration order is random on purpose; never rely on it, and sort keys when output must be stable.
  • `range` over a string yields runes with byte offsets, and over an array yields a copy; both surprise newcomers. Loop-variable semantics depend on the go.mod version.

Multiple and named results, variadics, closures and loop variables, and value vs pointer receivers with method sets.

The problem

Functions are first-class values, methods are functions with a receiver, and closures capture variables by reference. Most real-world confusion comes from three things: how named results interact with `defer`, which receiver kind to pick, and what a closure actually captures.

How it works

  • Functions can return multiple values; the idiom is `(result, error)` with the error last. Callers must handle or explicitly discard (`_`) each value.
  • Named results (`func f() (n int, err error)`) are pre-declared zero-valued variables; a bare `return` returns them. Use sparingly: mostly for documentation and for `defer` that rewrites `err`.
  • Variadic parameters (`xs ...int`) arrive as a slice; pass an existing slice with `f(xs...)`, which shares the backing array rather than copying.
  • Functions are values: assign them, pass them, store them in maps and structs. The zero value is `nil`, and calling it panics.
  • A closure captures variables, not values: it sees later changes, and the variable lives as long as the closure does (it escapes to the heap if needed).
  • Since Go 1.22 each `for` iteration has its own loop variable, so closures created in the loop see per-iteration values; earlier versions share one variable.
  • A method is a function with a receiver. Use a pointer receiver (`func (c *T)`) when it mutates, when the struct is large, or when it contains a `sync.Mutex`; otherwise a value receiver is fine. Do not mix both on one type.
  • Method sets: `T` has the value-receiver methods; `*T` has both. So a `T` value in an interface cannot call pointer methods, while `c.Inc()` on an addressable variable is sugar for `(&c).Inc()`.
  • Method value `f := c.Value` binds (and copies, for value receivers) the receiver now; method expression `(*Counter).Inc` is a plain function that takes the receiver as its first argument.

Go sketch

Go
import (
    "fmt"
    "strings"
)

func divmod(a, b int) (q, r int, err error) {
    if b == 0 {
        err = fmt.Errorf("divide %d by zero", a)
        return
    }
    return a / b, a % b, nil
}

func join(sep string, parts ...string) string {
    return strings.Join(parts, sep)
}

func counter() func() int {
    n := 0
    return func() int {
        n++
        return n
    }
}

type Counter struct{ n int }

func (c *Counter) Inc() {
    c.n++
}

func (c Counter) Value() int {
    return c.n
}

type Incer interface{ Inc() }

func methods() {
    var c Counter
    // c is addressable, so this is (&c).Inc().
    c.Inc()
    // Counter{}.Inc() and "var i Incer = c" do not compile:
    // the method set of Counter does not include Inc.
    var inc Incer = &c
    inc.Inc()

    f := c.Value // receiver copied now
    c.Inc()
    fmt.Println(f(), c.Value()) // 2 3

    g := (*Counter).Inc // method expression
    g(&c)

    next := counter()
    next()
    fmt.Println(next(), join("-", "a", "b"))
}

A deferred closure rewriting a named result, and the shared-slice trap of variadics.

Go
import (
    "fmt"
    "strconv"
)

func parse(s string) (n int, err error) {
    defer func() {
        if err != nil {
            err = fmt.Errorf("parse %q: %w", s, err)
        }
    }()
    return strconv.Atoi(s)
}

func zeroFirst(xs ...int) {
    if len(xs) > 0 {
        xs[0] = 0
    }
}

func variadic() {
    nums := []int{1, 2, 3}
    // f(nums...) passes the slice itself, so the callee can modify nums.
    zeroFirst(nums...)
    fmt.Println(nums) // [0 2 3]
    // Passing separate arguments creates a fresh slice instead.
    zeroFirst(1, 2, 3)
}

In practice

  • net/http — `http.HandlerFunc` turns a plain function into an `http.Handler`; middleware is a function that takes and returns a handler, closing over its configuration.
  • sort.Slice / slices.SortFunc — Comparison closures capture the slice or key they sort by; the standard way to sort by a field.
  • sync.Mutex in structs — A struct embedding a mutex must use pointer receivers; `go vet` (copylocks) flags value receivers and by-value copies.
  • Pitfall — Mixing value and pointer receivers makes the method set differ between `T` and `*T`, and a `T` stored in an interface then silently lacks some methods.

Trade-offs

Pros

  • Plain functions, closures and small interfaces compose without class hierarchies.
  • Multiple returns make errors explicit at the call site.
  • Pointer vs value receivers state clearly whether a method mutates.

Cons

  • Bare `return` with named results hurts readability in long functions, and `defer` can silently change what is returned.
  • Closures capture variables, not values: modifying the variable later changes what the closure sees; before Go 1.22 loop closures shared one variable.
  • Value receivers copy the receiver on every call; copying a struct that contains a mutex is a bug.
  • `f(xs...)` aliases the caller's slice, so a variadic function that writes to its parameter mutates the caller's data.

The error interface, sentinel and custom errors, and when to use panic and recover (and how to turn a panic into an error).

The problem

Go treats errors as ordinary return values, not exceptions. That keeps control flow explicit but raises design questions: how callers distinguish failure kinds, what extra data an error carries, and what to do with the rare situation that really is a bug and should `panic`.

How it works

  • `error` is a one-method interface: `Error() string`. `nil` means success. Create simple errors with `errors.New("msg")` or `fmt.Errorf("... %d", n)`.
  • Sentinel errors are package-level values (`var ErrNotFound = errors.New("not found")`) that callers compare with `errors.Is(err, ErrNotFound)`, never with `==` once errors may be wrapped.
  • Custom error types carry data (`type ValidationError struct{ Field string }` with a pointer-receiver `Error`); callers extract them with `errors.As(err, &target)`.
  • Add context with `fmt.Errorf("load config: %w", err)`; `%w` keeps the chain for `Is`/`As`, while `%v` flattens it to text. Do not log and return the same error.
  • Handle each error once: either handle it (retry, default, translate) or return it with context. Check `err != nil` immediately after the call.
  • `panic` unwinds the goroutine, running deferred calls, and crashes the program if nothing recovers. Use it for programmer errors and impossible states, not for expected failures like bad input or I/O.
  • `recover()` returns the panic value only when called directly inside a deferred function; elsewhere it returns `nil`. It does not recover other goroutines, `os.Exit`, or fatal runtime errors (deadlock, concurrent map writes, out of memory).
  • At an API boundary (HTTP handler, worker loop, plugin call) convert a panic into an error or a 500 with a deferred `recover`, log the stack with `debug.Stack()`, and keep the process alive.
  • To re-panic after cleanup, call `panic(r)` again inside the deferred function. Since Go 1.21, `panic(nil)` becomes a `*runtime.PanicNilError`, so `recover() != nil` is reliable.

Go sketch

Go
import (
    "errors"
    "fmt"
    "runtime/debug"
)

var ErrNotFound = errors.New("not found")

type ValidationError struct {
    Field string
    Msg   string
}

func (e *ValidationError) Error() string {
    return e.Field + ": " + e.Msg
}

func find(id int) error {
    if id < 0 {
        return &ValidationError{Field: "id", Msg: "must be >= 0"}
    }
    return fmt.Errorf("find %d: %w", id, ErrNotFound)
}

// safe converts a panic in f into an error (API boundary pattern).
func safe(f func()) (err error) {
    defer func() {
        if r := recover(); r != nil {
            err = fmt.Errorf("panic: %v\n%s", r, debug.Stack())
        }
    }()
    f()
    return nil
}

func check() {
    var ve *ValidationError
    if errors.As(find(-1), &ve) {
        fmt.Println("invalid field:", ve.Field)
    }
    if errors.Is(find(1), ErrNotFound) {
        fmt.Println("missing")
    }
    err := safe(func() {
        var m map[string]int
        m["a"] = 1 // panic: assignment to entry in nil map
    })
    fmt.Println(err != nil)
}

Cleanup then re-panic for unexpected values, recover for a known sentinel.

Go
import (
    "errors"
    "fmt"
)

var errAbort = errors.New("abort")

func run(f func()) (err error) {
    defer func() {
        r := recover()
        if r == nil {
            return
        }
        if e, ok := r.(error); ok && errors.Is(e, errAbort) {
            // Expected, internal use of panic for deep unwinding.
            err = e
            return
        }
        fmt.Println("cleaning up before crash")
        panic(r)
    }()
    f()
    return nil
}

func demo() {
    err := run(func() { panic(errAbort) })
    fmt.Println(errors.Is(err, errAbort))
}

In practice

  • net/http — The server recovers panics per request and logs them, so a bug in one handler does not take down the process; `http.ErrAbortHandler` is the sentinel for deliberately aborting a response.
  • os / io — `io.EOF` and `os.ErrNotExist` are sentinels checked with `errors.Is`; `*fs.PathError` is a custom type extracted with `errors.As`.
  • encoding/json, text/template — Use panic internally for deep unwinding and recover at the package boundary so that the public API still returns plain errors.
  • Pitfall — Comparing `err == ErrX` after wrapping with `%w` is always false; use `errors.Is`. Also never ignore errors from `Close` on written files.

Trade-offs

Pros

  • Errors are ordinary values: explicit, testable, and easy to wrap, inspect and translate.
  • No hidden control flow; every failure point is visible in the code.
  • `errors.Is`/`As` give structured matching without exception hierarchies.

Cons

  • `if err != nil` repetition is verbose, and it is easy to forget a check or silently drop an error with `_`.
  • A typed nil pointer returned as `error` is non-nil; compare with `errors.Is`, not `==`, once wrapping is involved.
  • `recover` only works inside a deferred function in the same goroutine; a panic in a spawned goroutine without its own recover kills the whole program.
  • Overusing `panic` or recovering everything hides real bugs; fatal runtime errors such as concurrent map writes cannot be recovered at all.

Concurrency

Start goroutines with a clear owner, wait for them with WaitGroup, bound their number, and remember that a panic or the end of main takes everything down.

The problem

`go f()` is one keyword, so starting a goroutine is easy and stopping it is not. Every goroutine needs an owner that knows when it ends, how its error or panic is reported, and who waits for it; otherwise you get leaks, lost errors and work that is silently killed when `main` returns.

How it works

  • `go f(x)` evaluates `f` and its arguments in the calling goroutine, then runs the call in a new goroutine. The return value of `f` is discarded, so results and errors must travel through a channel, a shared slot or `errgroup`.
  • When `main` returns the process exits immediately and all other goroutines are killed without running their defers. Something must wait: `sync.WaitGroup`, a channel receive, or `errgroup.Wait`.
  • `sync.WaitGroup`: call `wg.Add(n)` before the `go` statement (never inside the goroutine), `defer wg.Done()` first thing in the goroutine, `wg.Wait()` in the owner. A negative counter panics; a `WaitGroup` must not be copied.
  • Go 1.25 adds `wg.Go(func())`, which does Add, `go` and Done for you. Use it only if your `go.mod` requires 1.25+; the Add/Done form works on every version.
  • An unrecovered panic in any goroutine terminates the whole process, and `recover` only works inside a deferred function of the same goroutine. Long-lived workers that run untrusted callbacks should `defer` a recover that logs and reports the failure.
  • `golang.org/x/sync/errgroup`: `g, ctx := errgroup.WithContext(ctx)`, `g.Go(func() error {...})`, `g.Wait()` returns the first non-nil error and cancels `ctx` for the rest. `g.SetLimit(n)` bounds concurrency.
  • Bound concurrency with a semaphore channel: `sem := make(chan struct{}, n)`; acquire with `sem <- struct{}{}`, release with `<-sem`. An unbounded `go` per item can exhaust memory, file descriptors or a downstream service.
  • `runtime.GOMAXPROCS(0)` returns the number of OS threads that may run Go code at once (default: number of CPUs; since Go 1.25 it also respects the cgroup CPU limit). Goroutines are far more numerous than that; blocked ones cost no thread.
  • Rule of thumb: the function that starts a goroutine decides how it stops (a `context`, a done channel or closing its input channel) and either waits for it or documents who does.

Examples

Go
import (
    "fmt"
    "runtime"
    "sync"
)

// process stands in for real work.
func process(job string) string {
    return "done " + job
}

// runJobs starts one goroutine per job, never runs more than limit at once,
// converts panics into results, and returns only after all goroutines exit.
func runJobs(jobs []string, limit int) []string {
    var wg sync.WaitGroup
    sem := make(chan struct{}, limit)
    results := make([]string, len(jobs))
    for i, job := range jobs {
        // Add before "go", never inside the goroutine.
        wg.Add(1)
        sem <- struct{}{}
        // Go 1.22+: i and job are per-iteration, so capturing them is safe.
        go func() {
            defer wg.Done()
            defer func() { <-sem }()
            defer func() {
                if r := recover(); r != nil {
                    results[i] = fmt.Sprint("panic: ", r)
                }
            }()
            results[i] = process(job)
        }()
    }
    wg.Wait()
    return results
}

// parallelism reports how many goroutines can run Go code simultaneously.
func parallelism() int {
    return runtime.GOMAXPROCS(0)
}

Pin GOMAXPROCS from the environment and pull in errgroup (x/ module, not stdlib).

bash
GOMAXPROCS=4 ./server
go get golang.org/x/sync/errgroup

In practice

  • net/http — The server starts one goroutine per connection and per request; a panic in a handler is recovered by the server, but a panic in a goroutine you start from a handler is not and kills the process.
  • errgroup — Used throughout Kubernetes-style controllers and CLIs to run N fetches with a shared context; the first error cancels the siblings.
  • uber-go/automaxprocs — Before Go 1.25, containers with a CPU quota needed this library (or GOMAXPROCS) so the runtime did not size itself to the host's CPU count and get throttled.
  • Graceful shutdown — Servers keep a WaitGroup of in-flight work and wait for it after cancelling the root context, with a timeout so shutdown cannot hang.

Trade-offs

Pros

  • Goroutines are cheap (small initial stack), so one per task is a normal design
  • WaitGroup and a semaphore channel cover most fork/join needs with the stdlib alone
  • The runtime multiplexes goroutines onto threads; blocking I/O does not cost a thread

Cons

  • No built-in handle: you cannot kill a goroutine from outside, only ask it to stop
  • wg.Add inside the goroutine races with wg.Wait and may let Wait return too early
  • A panic in any goroutine crashes the process; recover works only in that goroutine
  • Unbounded go statements turn a traffic spike into an out-of-memory crash

Buffered and unbuffered channels, close semantics, select, and the standard shapes built on them: pipeline, fan-out/fan-in and worker pool.

The problem

Goroutines need to hand data and ownership to each other and to stop together. Channels do that without shared memory, but only if you know who closes them, what blocks, and how to stop every sender and receiver when the work is abandoned.

How it works

  • Unbuffered `make(chan T)`: a send and a receive rendezvous, so both sides synchronise. Buffered `make(chan T, n)`: a send blocks only when the buffer is full, a receive only when it is empty.
  • Only the sender closes, and only once. Sending on a closed channel and closing a closed channel both panic; closing a nil channel panics too. Receivers never close a channel they do not own.
  • Receiving from a closed channel returns buffered values first, then the zero value immediately with `ok == false`. `v, ok := <-ch` tells them apart; `for v := range ch` loops until the channel is closed and drained.
  • A nil channel blocks forever on send and receive. In `select` that makes a case never ready, so set a channel variable to `nil` to disable that case (for example after it is closed).
  • `select` waits on several operations and picks a ready one at random. `default` makes it non-blocking; `case <-time.After(d)` or a `time.Timer` adds a timeout; `case <-ctx.Done()` adds cancellation.
  • Directional types document intent and are checked by the compiler: `chan<- T` send-only, `<-chan T` receive-only. A bidirectional channel converts to either implicitly; functions should take the narrowest type.
  • Done channel: a `chan struct{}` that is closed to broadcast cancellation to any number of goroutines. In new code prefer `ctx.Done()`, which has the same shape.
  • Pipeline: stages `func(in <-chan A) <-chan B`; each stage closes its output when its input closes. Fan-out: several goroutines read the same channel. Fan-in (merge): several channels are copied to one, closed by a goroutine that waits on a WaitGroup.
  • Worker pool: N goroutines `range` over a jobs channel, results go to another channel, and the owner closes `jobs` after queueing and `results` after the workers finish.

Go sketch

Go
import "sync"

// gen emits nums until done is closed.
func gen(done <-chan struct{}, nums ...int) <-chan int {
    out := make(chan int)
    go func() {
        defer close(out)
        for _, n := range nums {
            select {
            case out <- n:
            case <-done:
                return
            }
        }
    }()
    return out
}

// square is a pipeline stage: it closes out when in is closed or done fires.
func square(done <-chan struct{}, in <-chan int) <-chan int {
    out := make(chan int)
    go func() {
        defer close(out)
        for n := range in {
            select {
            case out <- n * n:
            case <-done:
                return
            }
        }
    }()
    return out
}

// merge fans several channels into one and closes it after all are drained.
func merge(done <-chan struct{}, cs ...<-chan int) <-chan int {
    var wg sync.WaitGroup
    out := make(chan int)
    wg.Add(len(cs))
    for _, c := range cs {
        go func() {
            defer wg.Done()
            for n := range c {
                select {
                case out <- n:
                case <-done:
                    return
                }
            }
        }()
    }
    go func() {
        wg.Wait()
        close(out)
    }()
    return out
}

// sumSquares: one source, two squarers (fan-out), merged back (fan-in).
func sumSquares(nums ...int) int {
    done := make(chan struct{})
    // Closing done releases every stage even if we return early.
    defer close(done)
    src := gen(done, nums...)
    total := 0
    for n := range merge(done, square(done, src), square(done, src)) {
        total += n
    }
    return total
}

Worker pool: the owner closes jobs after queueing and results after the workers exit.

Go
import (
    "slices"
    "sync"
)

func runPool(workers int, inputs []int) []int {
    jobs := make(chan int)
    results := make(chan int)

    var wg sync.WaitGroup
    for range workers {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for n := range jobs {
                results <- n * 2
            }
        }()
    }
    go func() {
        for _, n := range inputs {
            jobs <- n
        }
        close(jobs)
    }()
    go func() {
        wg.Wait()
        close(results)
    }()

    var out []int
    for r := range results {
        out = append(out, r)
    }
    slices.Sort(out)
    return out
}

select: non-blocking receive, timeout, and disabling a closed case with a nil channel.

Go
import (
    "errors"
    "time"
)

func tryRecv(ch <-chan string) (string, bool) {
    select {
    case v := <-ch:
        return v, true
    default:
        return "", false
    }
}

func recvTimeout(ch <-chan string, d time.Duration) (string, error) {
    t := time.NewTimer(d)
    defer t.Stop()
    select {
    case v := <-ch:
        return v, nil
    case <-t.C:
        return "", errors.New("timeout")
    }
}

// drain reads two channels until both are closed. A closed channel is set to
// nil so its case never fires again (a closed channel is always ready).
func drain(a, b <-chan int) int {
    sum := 0
    for a != nil || b != nil {
        select {
        case v, ok := <-a:
            if !ok {
                a = nil
                continue
            }
            sum += v
        case v, ok := <-b:
            if !ok {
                b = nil
                continue
            }
            sum += v
        }
    }
    return sum
}

In practice

  • net/http, os/signal — signal.Notify takes a buffered channel; with an unbuffered one, a signal delivered while you are not receiving is dropped.
  • time.Ticker / Timer — Their C field is a channel you select on, together with ctx.Done(), to build periodic loops that stop cleanly.
  • etcd, Kubernetes watch — Watch APIs return a receive-only channel of events; the producer closes it when the watch ends, so consumers just range over it.
  • Rule of thumb — Use a channel to transfer ownership or signal events; use a mutex to protect state. A struct with a mutex is often simpler than a goroutine that owns the state.

Trade-offs

Pros

  • Ownership transfer and synchronisation in one construct, without explicit locks
  • select composes timeouts, cancellation and multiple sources cleanly
  • Directional types let the compiler enforce who sends and who receives

Cons

  • A send or receive with no counterpart blocks forever and leaks the goroutine
  • Send on a closed channel and double close panic; there is no way to test 'is closed' safely
  • A closed channel is always ready, so a select loop that does not nil it spins at 100% CPU
  • Channels are slower than a mutex or atomic for plain shared state, and harder to reason about when overused

Mutex, RWMutex, Once, sync.Map, Cond and typed atomics: the tools for protecting shared memory when a channel is the wrong shape.

The problem

When several goroutines touch the same memory, at least one write is a data race unless access is synchronised. Channels transfer ownership; the `sync` and `sync/atomic` packages protect state that has to be shared in place: caches, counters, lazily built singletons.

How it works

  • `sync.Mutex`: `Lock`/`Unlock` give mutual exclusion. The idiom is `mu.Lock(); defer mu.Unlock()`, with the mutex as a field right above the data it guards. The zero value is ready to use and not reentrant.
  • `sync.RWMutex`: many `RLock` readers or one `Lock` writer. It pays off only for read-heavy data with non-trivial critical sections; a plain Mutex is often as fast. Never upgrade a read lock to a write lock while holding it: that deadlocks.
  • `sync.WaitGroup`: wait for a set of goroutines (`Add` before `go`, `Done` when finished, `Wait`). See goroutine-lifecycle.
  • `sync.Once`: `once.Do(f)` runs `f` exactly once and later callers wait for it to finish. Since Go 1.21: `OnceFunc`, `OnceValue` and `OnceValues` wrap a function and cache its result (and re-panic with the same value if it panicked).
  • `sync.Map`: a concurrent map for two cases only: keys written once and read many times, or goroutines using disjoint key sets. Otherwise a `map` guarded by a `Mutex`/`RWMutex` is faster, type-safe and easier to extend.
  • `sync/atomic` typed values (Go 1.19): `atomic.Int64`, `Int32`, `Uint64`, `Bool`, `Pointer[T]`, `Value` with `Load`, `Store`, `Add`, `CompareAndSwap`. Prefer them over the `atomic.AddInt64(&x, 1)` functions: they cannot be accessed non-atomically by mistake and are correctly aligned.
  • Atomics make single words safe; they do not make multi-field invariants safe. If two fields must change together, use a mutex or swap an immutable struct through `atomic.Pointer[T]`.
  • `sync.Cond` (`Wait`, `Signal`, `Broadcast`) lets goroutines wait for a condition on state protected by a mutex. Always re-check the condition in a `for` loop around `Wait`. In most programs a channel or `context` is simpler.
  • Never copy a `Mutex`, `WaitGroup`, `Once`, `Cond` or any struct containing one after first use: pass pointers and use pointer receivers. `go vet` (copylocks) catches most copies. Acquire multiple locks in one global order to avoid deadlock, and do not call unknown code while holding a lock.

Go sketch

Go
import (
    "sync"
    "sync/atomic"
)

// kvCache guards data with an RWMutex; the mutex sits above what it protects.
type kvCache struct {
    mu   sync.RWMutex
    data map[string]string
}

func newKVCache() *kvCache {
    return &kvCache{data: make(map[string]string)}
}

func (c *kvCache) Get(k string) (string, bool) {
    c.mu.RLock()
    defer c.mu.RUnlock()
    v, ok := c.data[k]
    return v, ok
}

func (c *kvCache) Set(k, v string) {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.data[k] = v
}

// loadSettings runs the function once (Go 1.21+) and caches the result.
var loadSettings = sync.OnceValue(func() map[string]string {
    return map[string]string{"env": "prod"}
})

// countHits uses a typed atomic: no lock, and no way to read it non-atomically.
func countHits(n int) int64 {
    var hits atomic.Int64
    var wg sync.WaitGroup
    for range n {
        wg.Add(1)
        go func() {
            defer wg.Done()
            hits.Add(1)
        }()
    }
    wg.Wait()
    return hits.Load()
}

sync.Cond: wait in a loop on a condition guarded by the mutex; Broadcast wakes all waiters.

Go
import "sync"

type gate struct {
    mu   sync.Mutex
    cond *sync.Cond
    open bool
}

func newGate() *gate {
    g := &gate{}
    g.cond = sync.NewCond(&g.mu)
    return g
}

func (g *gate) Wait() {
    g.mu.Lock()
    defer g.mu.Unlock()
    for !g.open {
        g.cond.Wait()
    }
}

func (g *gate) Open() {
    g.mu.Lock()
    g.open = true
    g.mu.Unlock()
    g.cond.Broadcast()
}

sync.Map for write-once, read-many keys; copying a lock is the bug go vet reports (kept in a comment).

Go
import "sync"

var registry sync.Map

// register stores v under name only if the name is new.
func register(name string, v int) (int, bool) {
    actual, loaded := registry.LoadOrStore(name, v)
    return actual.(int), loaded
}

type guarded struct {
    mu sync.Mutex
    n  int
}

// Bug: a value receiver, func (g guarded) Inc(), copies the mutex, so each
// call locks its own copy and nothing is protected.
//
// Fix: a pointer receiver shares one mutex.
func (g *guarded) Inc() {
    g.mu.Lock()
    defer g.mu.Unlock()
    g.n++
}

In practice

  • net/http — A handler value is shared by all request goroutines, so any state in it needs a mutex or atomics; a plain map field is a classic race.
  • Prometheus client_golang — Counters and gauges are built on atomic operations so instrumentation in hot paths takes no lock.
  • Lazy init — sync.OnceValue(func() T) replaces the old pattern of a package variable plus a sync.Once and a getter; db handles, compiled regexps and config are typical.
  • Pitfall — Embedding sync.Mutex in an exported struct exposes Lock/Unlock to callers; prefer an unexported named field.

Trade-offs

Pros

  • Mutexes are simple, fast when uncontended, and keep invariants next to the data
  • Typed atomics give lock-free counters and flags that cannot be misused
  • Once/OnceValue make lazy, thread-safe initialisation a one-liner

Cons

  • Forgetting to lock one access path is enough for a race; nothing in the type system enforces it
  • Copying a Mutex or WaitGroup silently breaks it; only go vet notices
  • Inconsistent lock ordering across two mutexes deadlocks under load, not in tests
  • sync.Map is untyped (any) and slower than a locked map for most workloads

Carry cancellation, deadlines and request-scoped values down a call tree so that abandoned work stops and its resources are released.

The problem

A request fans out into goroutines, database queries and HTTP calls. When the client disconnects or a deadline passes, all of that work should stop and release its resources, and request-scoped data such as a trace ID should follow the call tree. `context.Context` is the one standard value that carries cancellation, deadline and request-scoped data through APIs.

How it works

  • Root contexts: `context.Background()` is the top-level, never-cancelled context for `main`, tests and incoming-request setup. `context.TODO()` is the same value but marks a place where the right context is not yet plumbed through.
  • Derived contexts form a tree: `WithCancel(parent)`, `WithTimeout(parent, d)`, `WithDeadline(parent, t)` and `WithValue(parent, key, val)` each return a child. Cancelling a parent cancels all its children, never the reverse.
  • `WithCancel`, `WithTimeout` and `WithDeadline` return `(ctx, cancel)`. Always `defer cancel()`: it releases the timer and the child's registration in the parent, even when the deadline would have fired anyway. `go vet` (lostcancel) flags a dropped cancel.
  • Check cancellation by selecting on `ctx.Done()`: `select { case <-ctx.Done(): return ctx.Err() ... }`. In loops without blocking calls, test `ctx.Err() != nil` periodically.
  • `ctx.Err()` is `nil` until done, then `context.Canceled` (cancel was called or the parent was cancelled) or `context.DeadlineExceeded` (deadline passed). Compare with `errors.Is`; `DeadlineExceeded` also satisfies `net.Error` with `Timeout() == true`.
  • `WithCancelCause` (Go 1.20) lets `cancel(err)` record why, read back with `context.Cause(ctx)`. `WithTimeoutCause`/`WithDeadlineCause` (Go 1.21) attach a cause to expiry.
  • Go 1.21: `context.AfterFunc(ctx, f)` runs `f` in its own goroutine after ctx is done and returns a `stop` func; `context.WithoutCancel(parent)` keeps the values but drops cancellation, for work that must outlive the request (audit log, cleanup).
  • `WithValue` is for request-scoped data crossing API boundaries (trace ID, auth principal), not for optional parameters. Use an unexported key type, such as `type ctxKey struct{}`, wrapped in typed accessor functions.
  • Convention: `ctx context.Context` is the first parameter, named `ctx`, of every function that blocks, does I/O or starts goroutines. Never pass a nil context; use `context.TODO()` if unsure.

Go sketch

Go
import (
    "context"
    "errors"
    "fmt"
    "time"
)

// ctxKey is unexported, so no other package can collide with this key.
type ctxKey struct{}

func WithRequestID(ctx context.Context, id string) context.Context {
    return context.WithValue(ctx, ctxKey{}, id)
}

func RequestID(ctx context.Context) (string, bool) {
    id, ok := ctx.Value(ctxKey{}).(string)
    return id, ok
}

// slowCall waits for d or until ctx is done, whichever comes first.
func slowCall(ctx context.Context, d time.Duration) error {
    t := time.NewTimer(d)
    defer t.Stop()
    select {
    case <-t.C:
        return nil
    case <-ctx.Done():
        return ctx.Err()
    }
}

func callWithTimeout() error {
    // Always defer cancel, even if the timeout would fire anyway.
    ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
    defer cancel()
    err := slowCall(WithRequestID(ctx, "req-42"), time.Second)
    switch {
    case errors.Is(err, context.DeadlineExceeded):
        return fmt.Errorf("too slow: %w", err)
    case errors.Is(err, context.Canceled):
        return fmt.Errorf("caller gave up: %w", err)
    }
    return err
}

Context-aware stdlib APIs: database/sql and net/http take ctx and abort when it is done.

Go
import (
    "context"
    "database/sql"
    "errors"
    "net/http"
    "time"
)

func fetchUser(ctx context.Context, db *sql.DB, id int) (string, error) {
    // A tighter budget for this query; the parent's deadline still applies.
    ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
    defer cancel()
    var name string
    err := db.QueryRowContext(ctx, "SELECT name FROM users WHERE id = $1", id).Scan(&name)
    return name, err
}

func userHandler(db *sql.DB) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        // r.Context() is cancelled when the client disconnects.
        name, err := fetchUser(r.Context(), db, 1)
        if errors.Is(err, context.DeadlineExceeded) {
            http.Error(w, "upstream timeout", http.StatusGatewayTimeout)
            return
        }
        if err != nil {
            http.Error(w, "error", http.StatusInternalServerError)
            return
        }
        _, _ = w.Write([]byte(name))
    }
}

func get(ctx context.Context, url string) (*http.Response, error) {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return nil, err
    }
    return http.DefaultClient.Do(req)
}

Go 1.20/1.21 additions: cancel causes, AfterFunc and WithoutCancel.

Go
import (
    "context"
    "errors"
    "fmt"
)

func causeDemo(parent context.Context) {
    ctx, cancel := context.WithCancelCause(parent)
    defer cancel(nil)

    stop := context.AfterFunc(ctx, func() {
        fmt.Println("cleanup after cancel")
    })
    defer stop()

    cancel(errors.New("shutdown requested"))
    // ctx.Err() is context.Canceled; the reason is in Cause.
    fmt.Println(ctx.Err(), context.Cause(ctx))

    // Keeps parent's values but is never cancelled by it.
    detached := context.WithoutCancel(parent)
    _ = detached
}

In practice

  • net/http — r.Context() is cancelled when the client disconnects or ServeHTTP returns; http.NewRequestWithContext ties an outgoing call to the caller's context.
  • database/sql — QueryContext, ExecContext and BeginTx abort the statement when ctx is done; the non-Context variants cannot be cancelled.
  • gRPC-Go, Kubernetes client-go — Every call takes ctx first; deadlines propagate across the wire (gRPC) and informers and controllers stop when their root ctx is cancelled.
  • OpenTelemetry — The current span and trace ID travel in the ctx via WithValue; passing a fresh Background() breaks the trace.

Trade-offs

Pros

  • One uniform, composable mechanism for cancellation and deadlines across the stdlib and third-party code
  • Cancellation propagates down the tree automatically, with no per-goroutine plumbing
  • Deadlines make timeouts a budget that callees can see and respect

Cons

  • Do not store a Context in a struct: pass it as the first parameter, named ctx, so its lifetime is the call's
  • Always defer cancel(), even if you do not need early cancellation, or the timer and parent registration leak until the deadline
  • Use a custom unexported key type for WithValue; string or int keys collide across packages
  • Values are for request-scoped data, not optional parameters: they are untyped and invisible in signatures
  • A child is cancelled when its parent is, so work that must survive the request needs WithoutCancel or a fresh root
  • Cancellation is cooperative: code that never checks ctx.Done() is never interrupted

Goroutine leaks, data races, loop-variable capture, deadlocks and closed-channel panics: how they look, how to detect them, and how to fix them.

The problem

Concurrency bugs in Go are rarely compile errors. They are leaked goroutines that grow memory for weeks, races that corrupt data once a day, and deadlocks that appear only under load. Knowing the handful of recurring shapes, and the tools that expose them, covers most of the risk.

How it works

  • Goroutine leak: a goroutine blocked forever on a send, receive, lock or missing cancel. Detect with `runtime.NumGoroutine()` trending up, the pprof goroutine profile (`/debug/pprof/goroutine?debug=2`), and `go.uber.org/goleak` in tests. Fix: every goroutine gets an exit path (`ctx.Done()`, closed input, buffered result channel).
  • Data race: two goroutines access the same memory, at least one writes, no synchronisation. Detect with `go test -race` or `go run -race` (it only reports races that actually execute, so exercise concurrent paths). Fix with a mutex, an atomic, or by giving one goroutine ownership via a channel.
  • Loop-variable capture: before Go 1.22, `for i := ...` reused one variable, so closures and goroutines all saw its last value. With `go 1.22` or later in `go.mod` each iteration has its own variable. Older modules still need `i := i`.
  • Deadlock: `fatal error: all goroutines are asleep - deadlock!` is printed only when every goroutine is blocked. A partial deadlock (some goroutines stuck, others alive, e.g. a running HTTP server) is silent and shows up as a hang or a leak.
  • `close` of a closed channel and send on a closed channel panic. Make one goroutine the sole closer, or guard with `sync.Once`. A receive from a closed channel does not panic.
  • `fatal error: concurrent map writes` (or `concurrent map read and map write`) is a runtime check, not a recoverable panic: it kills the process. Guard maps with a mutex or use `sync.Map`. Writing to a nil map is a different bug and panics with `assignment to entry in nil map`.
  • Calling `wg.Add(1)` inside the goroutine races with `wg.Wait()`: Wait may see zero and return before the goroutine has registered. Add before the `go` statement.
  • `time.After` in a loop or select allocates a timer per iteration. Before Go 1.23 an unfired timer is not garbage-collected until it fires; with `go 1.23`+ in `go.mod` unreferenced timers are collected. For hot loops reuse a `time.Timer` (`Reset`) or use `context.WithTimeout`.
  • Unbuffered result channel plus early return is a classic leak: when the caller times out and returns, the worker blocks forever on its send. Make the channel buffered by one (`make(chan T, 1)`) or `select` on `ctx.Done()` when sending.

Examples

Go
import (
    "context"
    "sync"
    "time"
)

// Leak (broken): the producer blocks on ch <- i forever once the consumer
// stops reading.
//
//    func leaky() <-chan int {
//        ch := make(chan int)
//        go func() {
//            for i := 0; ; i++ {
//                ch <- i
//            }
//        }()
//        return ch
//    }

// produce is the fix: every send also watches ctx.Done().
func produce(ctx context.Context) <-chan int {
    ch := make(chan int)
    go func() {
        defer close(ch)
        for i := 0; ; i++ {
            select {
            case ch <- i:
            case <-ctx.Done():
                return
            }
        }
    }()
    return ch
}

// Race (broken): n++ from many goroutines without a lock, and wg.Add inside
// the goroutine so Wait may return early.
//
// Fix below: mutex-protected counter and Add before go.
func countSafely(workers int) int {
    var mu sync.Mutex
    var wg sync.WaitGroup
    n := 0
    for range workers {
        wg.Add(1)
        go func() {
            defer wg.Done()
            mu.Lock()
            n++
            mu.Unlock()
        }()
    }
    wg.Wait()
    return n
}

// recvIdle gives each wait its own timer that is always stopped.
// time.After in a hot loop allocates a timer per iteration.
func recvIdle(ctx context.Context, in <-chan int, idle time.Duration) (int, bool) {
    t := time.NewTimer(idle)
    defer t.Stop()
    select {
    case v, ok := <-in:
        return v, ok
    case <-t.C:
        return 0, false
    case <-ctx.Done():
        return 0, false
    }
}

Find races and leaks: race detector, goroutine dump from a live process, goroutine count in tests via goleak.

bash
go test -race ./...
go run -race .
curl -s 'http://localhost:6060/debug/pprof/goroutine?debug=2' | head -50
go get go.uber.org/goleak

Collect results with a buffered channel so a worker never blocks after the caller returned early.

Go
import (
    "context"
    "errors"
    "time"
)

func slowQuery(d time.Duration) (string, error) {
    time.Sleep(d)
    return "rows", nil
}

// queryWithTimeout would leak the worker if result were unbuffered: after the
// timeout nobody receives, so the send blocks forever. Capacity 1 fixes it.
func queryWithTimeout(ctx context.Context, d time.Duration) (string, error) {
    type result struct {
        val string
        err error
    }
    ch := make(chan result, 1)
    go func() {
        v, err := slowQuery(d)
        ch <- result{v, err}
    }()
    select {
    case r := <-ch:
        return r.val, r.err
    case <-ctx.Done():
        return "", errors.Join(errors.New("query abandoned"), ctx.Err())
    }
}

In practice

  • go test -race — Run it in CI on every package; it slows execution about 2-20x and uses more memory, so it is for tests, not production.
  • pprof — A goroutine profile grouped by stack shows thousands of goroutines parked at the same line: that line is the leak.
  • uber-go/goleak — goleak.VerifyNone(t) or VerifyTestMain fails a test if goroutines started by it are still running at the end.
  • Kubernetes, etcd — Large Go codebases enforce context plumbing and run tests under -race; most real incidents are missing cancellation, not exotic memory-model bugs.

Trade-offs

Pros

  • The race detector is built in, precise (no false positives) and one flag away
  • Go 1.22 per-iteration loop variables removed a whole class of capture bugs
  • A few disciplines (every goroutine has an exit, one closer per channel, locks guard data) prevent most issues

Cons

  • The race detector only sees races that run in that execution, and cannot be used in production builds cheaply
  • Loop-variable semantics depend on the go directive in go.mod, not on the compiler version
  • Leaks and partial deadlocks are silent: nothing crashes, memory just grows
  • concurrent map writes is fatal and cannot be recovered
  • Broken variants compile and often pass tests on a laptop; races show up under load

Standard library

Splitting, trimming and building strings, parsing numbers with strconv, the bytes mirror API, and the byte vs rune distinction.

The problem

Most Go programs spend their time slicing text, parsing numbers and assembling output. The standard library covers all of it, but a handful of semantics trip people up: strings are immutable byte sequences, `TrimLeft` takes a character set rather than a prefix, and every parse function returns a typed error you should inspect instead of string-matching.

How it works

  • A `string` is an immutable sequence of bytes, usually UTF-8. `len(s)` is the byte count, `s[i]` is a `byte`, and `for i, r := range s` decodes runes (invalid bytes yield `U+FFFD`). Use `utf8.RuneCountInString(s)` for the number of characters.
  • `strings.Split` keeps empty fields (`Split("", ",")` is `[""]`), while `strings.Fields` splits on runs of whitespace and drops empties. `strings.Cut(s, sep)` returns `before, after, found` and replaces most `Index`-plus-slicing code.
  • `TrimPrefix`/`TrimSuffix` remove one exact string; `CutPrefix`/`CutSuffix` (Go 1.20+) also report whether it was there. `TrimLeft`/`TrimRight`/`Trim` take a cutset of characters, so `TrimLeft("xaxabc", "xa")` yields `bc`, not `xabc`.
  • `strings.Replace(s, old, new, n)` replaces at most `n` occurrences (`n < 0` means all); `ReplaceAll` is the shorthand. `strings.NewReplacer` does many substitutions in one pass.
  • Build strings with `strings.Builder` (`WriteString`, `WriteByte`, `WriteRune`, `String`, optional `Grow`). Do not copy a Builder after first use: it panics on the next write. Repeated `+=` in a loop is quadratic.
  • `strconv.Atoi`, `ParseInt(s, base, bits)`, `ParseFloat`, `ParseBool` reject surrounding spaces and return `*strconv.NumError` whose `Err` is `ErrSyntax` or `ErrRange`. `ParseInt` base 0 honours `0x`/`0o`/`0b` prefixes and underscores; the `bits` argument range-checks the result.
  • The reverse direction: `Itoa`, `FormatInt(n, base)`, `FormatFloat(f, 'f', prec, 64)`, `Quote`/`Unquote`, `AppendInt` (no allocation). Prefer these over `fmt.Sprintf("%d")` in hot paths.
  • `bytes` mirrors `strings` (`Split`, `Contains`, `Trim*`, `Cut`, `Equal`) on `[]byte`, plus `bytes.Buffer` and `bytes.NewReader`. Use `bytes.Equal` (or `==` on strings), never `==` on slices.
  • `string(b)` and `[]byte(s)` copy the data. The compiler elides the copy in a few cases (`m[string(b)]` lookups, comparisons, `range`), but do not rely on it in design; converting back and forth in a loop is a common hidden allocation.

Go sketch

Go
import (
    "errors"
    "fmt"
    "strconv"
    "strings"
    "unicode/utf8"
)

// parsePort: Atoi/ParseInt always return *strconv.NumError on failure.
func parsePort(s string) (int, error) {
    n, err := strconv.Atoi(s)
    if err != nil {
        var ne *strconv.NumError
        if errors.As(err, &ne) {
            // ne.Func == "Atoi", ne.Num == s, ne.Err is ErrSyntax or ErrRange
            return 0, fmt.Errorf("bad port %q: %w", ne.Num, ne.Err)
        }
        return 0, err
    }
    if n < 1 || n > 65535 {
        return 0, fmt.Errorf("port %d out of range", n)
    }
    return n, nil
}

func demo() {
    // TrimPrefix removes one prefix; TrimLeft treats "xa" as a SET of runes.
    fmt.Println(strings.TrimPrefix("xaxabc", "xa"), strings.TrimLeft("xaxabc", "xa"))
    // Cut splits at the first separator: key="a", val="b=c", ok=true.
    key, val, ok := strings.Cut("a=b=c", "=")
    fmt.Println(key, val, ok)
    // Fields splits on any whitespace run; Split keeps empty fields.
    fmt.Printf("%q %q\n", strings.Fields("  a  b\tc\n"), strings.Split("a,,c", ","))
    // len counts bytes, not characters.
    s := "héllo, 世界"
    fmt.Println(len(s), utf8.RuneCountInString(s))
    // Builder: build once, never copy a non-zero Builder (copy check panics).
    var sb strings.Builder
    for i := range 3 {
        sb.WriteString(strconv.Itoa(i))
        sb.WriteByte(',')
    }
    fmt.Println(sb.String())
    fmt.Println(parsePort("99999"))
    fmt.Println(parsePort("x"))
}

In practice

  • net/http — Query values, headers and path wildcards arrive as strings; `strconv.Atoi` plus a `*NumError` check is the standard way to turn them into typed input and a 400 response.
  • Log and config parsing — `strings.Cut` for `key=value` and `host:port` lines, `strings.Fields` for whitespace-aligned output such as `ps` or `df`.
  • Pitfall: TrimLeft — `strings.TrimLeft(path, "./")` strips every leading `.` and `/` character, so `"../a"` becomes `"a"`. Use `TrimPrefix`/`CutPrefix` for prefixes.
  • Pitfall: len on text — Truncating with `s[:n]` can cut a multi-byte rune in half. Convert to `[]rune`, or walk with `utf8.DecodeRuneInString`, before cutting user-visible text.

Trade-offs

Pros

  • Small, allocation-aware API; `Builder`, `Cut` and `Append*` cover most hot paths
  • Strings are immutable, so they are safe to share across goroutines and use as map keys
  • Parse errors are typed (`*NumError`), so callers can tell bad syntax from overflow

Cons

  • `TrimLeft`/`TrimRight`/`Trim` take a cutset, not a prefix or suffix
  • `len(s)` is bytes; indexing and slicing can split a rune
  • `strings.Builder` must not be copied after use, and `Atoi` rejects surrounding spaces
  • `string(b)` / `[]byte(s)` copy; hidden conversions in loops cost allocations

Durations, the 2006-01-02 reference-time layouts, time zones, the monotonic clock, and Timer/Ticker lifecycle.

The problem

Time code fails in quiet ways: a layout string that is not the reference time, a timestamp parsed in the wrong zone, a wall-clock jump that breaks a timeout, or a ticker that is never stopped. The `time` package has precise answers for each, once you know what it models.

How it works

  • `time.Duration` is an `int64` of nanoseconds. Multiply by constants (`90 * time.Minute`); with a variable you must convert, `time.Duration(n) * time.Second`, because `time.Second * n` does not compile for an `int`. `d.String()` prints `1h30m0s`.
  • Layouts show the reference time `Mon Jan 2 15:04:05 MST 2006`. Read it as `1 2 3 4 5 6 7`: month 1, day 2, hour 3 (15), minute 4, second 5, year 6, zone 7 (`-0700`). `Format("2006-01-02")` works; `Format("YYYY-MM-DD")` just prints the letters.
  • `time.Parse` assumes UTC when the input has no zone. `time.ParseInLocation(layout, s, loc)` uses `loc` instead; `time.LoadLocation("Asia/Shanghai")` needs zoneinfo on the host (or `import _ "time/tzdata"` to embed it).
  • `time.Now()` carries a monotonic reading. `time.Since(t)` and `t2.Sub(t1)` use it, so elapsed-time measurement survives NTP or manual clock changes. `t.Round(0)` strips it; `==` compares it, while `Format` and JSON ignore it.
  • Compare instants with `Equal`, `Before` and `After`. `==` also compares location pointer and monotonic reading, so two equal instants can be `!=` (and `time.Time` as a map key is the same trap).
  • `Truncate(d)` and `Round(d)` operate on absolute time since the zero time, which is fine for `time.Hour`, but day boundaries must be built with `time.Date(y, m, d, 0, 0, 0, 0, loc)`. `AddDate` normalises overflow: Jan 31 plus one month is Mar 3 (or Mar 2 in a leap year).
  • `time.NewTimer`/`NewTicker` hold resources until `Stop`: always `defer t.Stop()`. `time.After` in a `select` inside a loop allocates a timer per iteration; before Go 1.23 each one lived until it fired. Reuse one `Timer` with `Reset`, or use a `context` deadline.
  • Go 1.23 changed timers (only when the main module's `go.mod` says `go 1.23` or later): unreferenced timers and tickers are garbage-collected even if not stopped, and timer channels are unbuffered, so no stale value is received after `Stop` or `Reset`.
  • `time.Time` implements `MarshalJSON`/`UnmarshalJSON` as RFC 3339 (`2024-03-05T14:07:00+08:00`) and `MarshalText` likewise; the zero `Time` encodes as `0001-01-01T00:00:00Z` and `omitempty` does not omit it. Test with `IsZero()`.

Go sketch

Go
import (
    "encoding/json"
    "fmt"
    "time"
)

func demo() error {
    // Reference time: Mon Jan 2 15:04:05 MST 2006
    // = month 1, day 2, hour 3 (15), minute 4, second 5, year 6, zone 7 (-0700)
    const layout = "2006-01-02 15:04"
    loc, err := time.LoadLocation("Asia/Shanghai")
    if err != nil {
        return err
    }
    // Parse without a zone assumes UTC; ParseInLocation uses loc.
    t, err := time.ParseInLocation(layout, "2024-03-05 14:07", loc)
    if err != nil {
        return err
    }
    fmt.Println(t.Format(time.RFC3339))
    fmt.Println(t.Add(90*time.Minute).Sub(t), t.Truncate(time.Hour).Format(time.TimeOnly))
    // AddDate normalizes overflow: Jan 31 + 1 month = "Feb 31" = Mar 3 (2023).
    jan31 := time.Date(2023, time.January, 31, 0, 0, 0, 0, time.UTC)
    fmt.Println(jan31.AddDate(0, 1, 0).Format(time.DateOnly))
    // time.Since uses the monotonic clock: safe against wall-clock jumps.
    start := time.Now()
    elapsed := time.Since(start)
    fmt.Println(elapsed < time.Second)
    // Compare instants with Equal, not ==.
    fmt.Println(t.Equal(t.UTC()), t == t.UTC())
    // Time marshals to RFC 3339 JSON.
    b, err := json.Marshal(struct{ At time.Time }{t})
    fmt.Println(string(b), err)
    // Stop tickers; prefer NewTimer over time.After in loops.
    tick := time.NewTicker(10 * time.Millisecond)
    defer tick.Stop()
    for range 2 {
        <-tick.C
    }
    return nil
}

In practice

  • context deadlines — `context.WithTimeout` is built on `time.AfterFunc`; prefer a context deadline over hand-rolled timers when the operation is cancellable.
  • Prometheus client — Latency histograms are fed with `time.Since(start)`, which relies on the monotonic clock so wall-clock steps do not produce negative durations.
  • Pitfall: time.After in a loop — `case <-time.After(d):` inside a hot `for`/`select` creates a new timer per pass; use `time.NewTimer` and `Reset`.
  • Pitfall: time zones in containers — `LoadLocation` fails on minimal images without `/usr/share/zoneinfo`; embed `time/tzdata` or ship zoneinfo.

Trade-offs

Pros

  • One type covers instants, zones, arithmetic and formatting
  • Monotonic clock readings make duration measurement robust by default
  • RFC 3339 JSON support works out of the box

Cons

  • The reference-time layout is unusual, and a wrong layout often parses to garbage or errors only at run time
  • `Parse` defaults to UTC; forgetting `ParseInLocation` silently shifts times
  • `==` on `time.Time` is almost never what you want; use `Equal`
  • Unstopped `Ticker`s and `time.After` in loops leak (before the Go 1.23 timer changes)

A production-shaped http.Server with timeouts, Go 1.22 ServeMux patterns, middleware, graceful shutdown, and a safe http.Client.

The problem

`net/http` is production-grade out of the box, but its zero values are not: a bare `http.ListenAndServe` has no timeouts and `http.DefaultClient` waits forever. Safe servers and clients are mostly a matter of setting the right fields, closing bodies and shutting down cleanly.

How it works

  • A handler is anything with `ServeHTTP(http.ResponseWriter, *http.Request)`; `http.HandlerFunc` adapts a plain function. Write headers and status before the body: the first `Write` sends `200` implicitly, and `WriteHeader` afterwards is ignored.
  • Go 1.22 `ServeMux` patterns include the method and wildcards: `mux.HandleFunc("GET /items/{id}", ...)`, read with `r.PathValue("id")`. `{name...}` matches the rest of the path, `{$}` matches only the exact path; `GET` also matches `HEAD`. Conflicting patterns panic at registration.
  • Middleware is `func(http.Handler) http.Handler`: wrap `next`, do work before and after `next.ServeHTTP`. Compose by nesting, and wrap the `ResponseWriter` if you need the status code.
  • Always set server timeouts on `http.Server`: `ReadHeaderTimeout` (slowloris), `ReadTimeout`, `WriteTimeout`, `IdleTimeout`. Streaming handlers may need `http.ResponseController` to extend deadlines per request.
  • Graceful shutdown: run `ListenAndServe` in a goroutine, wait for a signal (`signal.NotifyContext`), then `srv.Shutdown(ctx)`. It closes listeners and waits for in-flight requests, but not for hijacked connections (WebSocket); `ListenAndServe` returns `http.ErrServerClosed` right away.
  • Create one shared `http.Client{Timeout: ...}`. `DefaultClient` has no timeout, and a new client per request defeats connection pooling in its `Transport`. `Timeout` covers the whole exchange including reading the body.
  • Build requests with `http.NewRequestWithContext(ctx, ...)` so callers can cancel. `client.Do` returns a non-nil `resp` only when `err == nil`; then you must `Close` the body.
  • Connection reuse needs the body read to EOF and closed. On early exits, drain a bounded amount (`io.Copy(io.Discard, io.LimitReader(resp.Body, n))`) before closing, and cap what you read from untrusted peers with `io.LimitReader` or `http.MaxBytesReader` on the server side.
  • `httptest.NewRecorder` plus `httptest.NewRequest` tests a handler with no network; `httptest.NewServer` starts a real loopback server for client code. Both work with `net/http` types unchanged.

Go sketch

Go
import (
    "context"
    "fmt"
    "log"
    "net/http"
    "os/signal"
    "syscall"
    "time"
)

// Middleware is func(http.Handler) http.Handler.
func logging(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        next.ServeHTTP(w, r)
        log.Printf("%s %s %v", r.Method, r.URL.Path, time.Since(start))
    })
}

func newServer() *http.Server {
    mux := http.NewServeMux()
    // Go 1.22+: method and wildcard patterns.
    mux.HandleFunc("GET /items/{id}", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "item %s\n", r.PathValue("id"))
    })
    return &http.Server{
        Addr:              ":8080",
        Handler:           logging(mux),
        ReadHeaderTimeout: 5 * time.Second,
        ReadTimeout:       10 * time.Second,
        WriteTimeout:      10 * time.Second,
        IdleTimeout:       60 * time.Second,
    }
}

func run() error {
    ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
    defer stop()
    srv := newServer()
    errc := make(chan error, 1)
    go func() { errc <- srv.ListenAndServe() }()
    select {
    case err := <-errc:
        return err
    case <-ctx.Done():
    }
    // Shutdown stops accepting, then waits for in-flight requests.
    shutCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()
    return srv.Shutdown(shutCtx)
}

A client that cannot hang, leak connections, or read unbounded bodies.

Go
import (
    "context"
    "fmt"
    "io"
    "net/http"
    "time"
)

// One shared client: it pools connections. DefaultClient has no timeout.
var client = &http.Client{Timeout: 10 * time.Second}

func fetch(ctx context.Context, url string) ([]byte, error) {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return nil, err
    }
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    // Close always; resp is non-nil whenever err is nil.
    defer resp.Body.Close()
    if resp.StatusCode != http.StatusOK {
        // Drain a bounded amount so the connection can be reused.
        io.Copy(io.Discard, io.LimitReader(resp.Body, 4<<10))
        return nil, fmt.Errorf("GET %s: %s", url, resp.Status)
    }
    return io.ReadAll(io.LimitReader(resp.Body, 1<<20))
}

Testing a mux with httptest: recorder for handlers, NewServer for clients.

Go
import (
    "fmt"
    "net/http"
    "net/http/httptest"
)

func check() error {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /items/{id}", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprint(w, r.PathValue("id"))
    })
    // Handler test: no network, no port.
    rec := httptest.NewRecorder()
    mux.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/items/42", nil))
    if rec.Code != http.StatusOK || rec.Body.String() != "42" {
        return fmt.Errorf("got %d %q", rec.Code, rec.Body.String())
    }
    // Client test against a real loopback server.
    srv := httptest.NewServer(mux)
    defer srv.Close()
    resp, err := http.Get(srv.URL + "/items/7")
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    return nil
}

In practice

  • Kubernetes — The API server, kubelet and most controllers are built on `net/http` handlers plus the standard `http.Client`/`Transport`.
  • Prometheus — Metrics are exposed by mounting `promhttp.Handler()`, an ordinary `http.Handler`, on a `ServeMux`.
  • Plumego — Plumego is a stdlib-first Go web framework by the same author: handlers stay plain `http.Handler`/`http.HandlerFunc`, routes are registered explicitly (`app.Get("/ping", ...)`, `router.New()` with `r.Use(middleware...)`), and responses go through `contract.WriteResponse`. See birdor.com/products/plumego.
  • Pitfall: leaked bodies — Forgetting `resp.Body.Close()` (or not reading it) leaks connections and goroutines in the `Transport`; this is the most common production `net/http` bug.

Trade-offs

Pros

  • Complete, battle-tested HTTP/1.1 and HTTP/2 server and client in the standard library
  • Handlers are plain interfaces, so middleware and testing need no framework
  • Go 1.22 patterns remove most reasons to add a third-party router

Cons

  • Zero-value `Server` and `DefaultClient` have no timeouts
  • `resp.Body` must be closed and drained, or connections leak
  • `WriteHeader` after the first `Write` is silently ignored, and a panicking handler is recovered by the server per connection, not per app
  • The 1.22 mux semantics apply only if `go.mod` says `go 1.22` or later (`GODEBUG=httpmuxgo121=1` restores the old behaviour)

Marshal/Unmarshal rules: struct tags, exported fields, streaming Decoder, RawMessage, custom marshalers and the classic nil-slice and float64 surprises.

The problem

`encoding/json` maps Go values to JSON through reflection and struct tags. It is convenient and strict about types, but its defaults surprise people: unexported fields vanish, unknown keys are ignored, big integers become `float64` in `any`, and a nil slice is `null`, not `[]`.

How it works

  • Only exported fields are encoded or decoded. The tag `json:"name,omitempty"` renames the key; `json:"-"` skips the field; `json:",string"` encodes a number or bool as a JSON string. Decoding matches keys case-insensitively and ignores unknown keys.
  • `omitempty` drops false, 0, nil pointers/interfaces and empty slices, maps and strings, but never a struct value, including `time.Time`. `omitzero` (Go 1.24+) omits any zero value, using `IsZero()` when available.
  • A nil slice or map marshals to `null`; an empty non-nil one marshals to `[]` / `{}`. Make slices with `make([]T, 0)` (or `[]T{}`) when clients expect an array.
  • `[]byte` is encoded as a base64 string, not an array of numbers. `time.Time` is RFC 3339. Map keys must be strings, integers or `encoding.TextMarshaler`s, and are emitted in sorted order.
  • Decoding into `any` yields `map[string]any`, `[]any`, `string`, `bool`, `nil` and always `float64` for numbers, so integers above 2^53 lose precision. Use a typed struct, or `Decoder.UseNumber()` to get `json.Number`.
  • `json.Unmarshal` needs a pointer, and a `null` input leaves a non-pointer target unchanged. Type mismatches return `*json.UnmarshalTypeError` after decoding the rest, so check the error, not just the result.
  • `json.NewDecoder(r)` streams values from an `io.Reader` and `NewEncoder(w)` writes one per `Encode` call (with a trailing newline). `Decoder.DisallowUnknownFields()` rejects unknown keys; `Decoder.More()` and `Token()` iterate large arrays without loading them.
  • `json.RawMessage` defers decoding of a subtree (polymorphic payloads, passthrough). Implement `MarshalJSON`/`UnmarshalJSON` (or `MarshalText`/`UnmarshalText`) for custom formats; use a pointer receiver for `UnmarshalJSON`, and beware infinite recursion when calling `json.Marshal` on the same type.
  • `json.Valid(b)` checks syntax without decoding. `Marshal` escapes `<`, `>`, `&` as `\u003c` etc.; disable this with `Encoder.SetEscapeHTML(false)`. `Unmarshal` rejects trailing data after the first value; `Decoder.Decode` does not read past it.

Go sketch

Go
import (
    "encoding/json"
    "fmt"
    "strings"
    "time"
)

type Item struct {
    ID      int             `json:"id"`
    Name    string          `json:"name,omitempty"`
    Price   int64           `json:"price,string"`
    Secret  string          `json:"-"`
    Tags    []string        `json:"tags"`
    Blob    []byte          `json:"blob"`
    Meta    json.RawMessage `json:"meta,omitempty"`
    Created time.Time       `json:"created"`
    note    string
}

type Level int

func (l Level) MarshalJSON() ([]byte, error) {
    return json.Marshal([]string{"low", "high"}[l])
}

func (l *Level) UnmarshalJSON(b []byte) error {
    var s string
    if err := json.Unmarshal(b, &s); err != nil {
        return err
    }
    switch s {
    case "low":
        *l = 0
    case "high":
        *l = 1
    default:
        return fmt.Errorf("unknown level %q", s)
    }
    return nil
}

func demo() error {
    it := Item{ID: 1, Price: 250, Blob: []byte("hi"), Created: time.Unix(0, 0).UTC()}
    b, err := json.Marshal(it)
    fmt.Println(string(b), err)
    dec := json.NewDecoder(strings.NewReader(`{"id": 12345678901234567890, "x": [1]}`))
    dec.UseNumber()
    var m map[string]any
    fmt.Println(dec.Decode(&m), m)
    var got Item
    d2 := json.NewDecoder(strings.NewReader(`{"id": 1, "typo": 2}`))
    d2.DisallowUnknownFields()
    fmt.Println(d2.Decode(&got))
    lb, _ := json.Marshal(map[string]Level{"a": 1})
    fmt.Println(string(lb), json.Valid([]byte(`{"a":`)))
    return nil
}

In practice

  • net/http APIs — Decode request bodies with `json.NewDecoder(http.MaxBytesReader(w, r.Body, n))` plus `DisallowUnknownFields`, so a typo in a client field is a 400, not silent data loss.
  • Kubernetes — API objects carry `json` tags and use `json.RawMessage`-style raw extensions for unstructured payloads; custom `MarshalJSON` types such as `metav1.Time` keep wire formats stable.
  • Pitfall: numbers in any — Decoding IDs or int64 values into `map[string]any` rounds them through `float64`; a 19-digit ID comes back altered. Decode into a struct or use `UseNumber`.
  • Pitfall: nil slices — Returning a nil slice from a handler sends `null`, which breaks JS clients calling `.map`; initialise to an empty slice.

Trade-offs

Pros

  • Zero dependencies and tag-driven; works with any struct
  • Streaming `Decoder`/`Encoder` handle large or concatenated documents
  • `RawMessage` and custom marshalers cover polymorphic and legacy formats

Cons

  • Reflection makes it slower and more allocation-heavy than generated or hand-written codecs
  • Defaults hide errors: unknown keys ignored, case-insensitive matching, `null` for nil slices
  • Numbers in `any` become `float64`; `omitempty` does not apply to structs or `time.Time`
  • `omitzero` needs Go 1.24, so libraries on older toolchains cannot rely on it

Reading and writing files, paths, environment and args, and the io.Reader/Writer toolbox including bufio.Scanner limits.

The problem

Files, paths, environment and streams are where programs meet the outside world, and where small mistakes lose data: an ignored `Close` error on a written file, a path built with `+`, a scanner that silently stops at a long line, or a `defer` skipped by `os.Exit`. The `io.Reader`/`io.Writer` pair gives one composable model for all of it.

How it works

  • `os.ReadFile(path)` and `os.WriteFile(path, data, 0o644)` handle small files in one call. The permission applies only when the file is created and is reduced by the umask; `WriteFile` truncates an existing file, so a crash mid-write can leave it empty. Write to a temp file and `os.Rename` for atomic replacement.
  • `os.Open` (read-only) and `os.Create` (create or truncate, mode 0o666 before umask) return `*os.File`; `defer f.Close()` right after the error check. For files you wrote, check the `Close` error, which can report a delayed write failure.
  • Test for missing files with `errors.Is(err, fs.ErrNotExist)`, not by comparing strings; `*fs.PathError` carries `Op`, `Path` and `Err`. Likewise `fs.ErrExist` and `fs.ErrPermission`.
  • `os.Args[0]` is the program, `os.Args[1:]` the arguments (use `flag` for parsing). `os.Getenv` cannot tell unset from empty; `os.LookupEnv` returns `(value, ok)`. `os.Exit(n)` terminates immediately: deferred calls do not run, and `log.Fatal` calls it.
  • `filepath` operates on OS paths (`Join` cleans and inserts the separator, `Base`, `Dir`, `Ext`, `Abs`, `Rel`, `Glob`); `path` always uses `/` and is for URLs and `io/fs` names. `filepath.Glob` has no `**`. Never build paths with string concatenation.
  • `filepath.WalkDir` (Go 1.16+) is faster than `Walk` because it avoids a `Stat` per entry; return `filepath.SkipDir` to prune. Symbolic links are not followed. `os.ReadDir` lists one directory, sorted by name.
  • `io.Reader`/`io.Writer` compose: `io.Copy` (uses `WriterTo`/`ReaderFrom` shortcuts), `io.ReadAll`, `io.TeeReader` (copy what is read), `io.MultiWriter` (fan out), `io.LimitReader` (cap untrusted input), `io.Pipe` (in-memory sync pipe between goroutines), `io.Discard`.
  • `bufio.Scanner` splits lines but fails on a token over 64 KiB (`bufio.MaxScanTokenSize`): `Scan` returns false and `Err()` is `bufio.ErrTooLong`. Raise the cap with `sc.Buffer(buf, max)`, always check `sc.Err()`, or use `bufio.Reader.ReadString`/`ReadLine` for unbounded lines.
  • `os.MkdirTemp`/`os.CreateTemp` make unique temp entries (pattern `demo-*`); tests should prefer `t.TempDir()`. `io/fs.FS` abstracts read-only trees, and `//go:embed` places files into the binary as a `string`, `[]byte` or `embed.FS`.

Go sketch

Go
import (
    "errors"
    "fmt"
    "io"
    "io/fs"
    "os"
    "path/filepath"
)

// readOrDefault treats a missing file as "use defaults".
func readOrDefault(path string, def []byte) ([]byte, error) {
    b, err := os.ReadFile(path)
    if errors.Is(err, fs.ErrNotExist) {
        return def, nil
    }
    return b, err
}

func copyFile(dst, src string) (err error) {
    in, err := os.Open(src)
    if err != nil {
        return err
    }
    defer in.Close()
    out, err := os.Create(dst)
    if err != nil {
        return err
    }
    // Close error on a written file can mean lost data: do not ignore it.
    defer func() {
        if cerr := out.Close(); err == nil {
            err = cerr
        }
    }()
    _, err = io.Copy(out, in)
    return err
}

func demo() error {
    dir, err := os.MkdirTemp("", "demo-*")
    if err != nil {
        return err
    }
    defer os.RemoveAll(dir)
    src := filepath.Join(dir, "a.txt")
    if err := os.WriteFile(src, []byte("hello\n"), 0o644); err != nil {
        return err
    }
    if err := copyFile(filepath.Join(dir, "b.txt"), src); err != nil {
        return err
    }
    b, err := readOrDefault(filepath.Join(dir, "missing"), []byte("default"))
    fmt.Println(string(b), err, filepath.Base(src), filepath.Ext(src))
    return nil
}

Scanner with a raised limit, pruned WalkDir, and a Tee/MultiWriter/LimitReader pipeline.

Go
import (
    "bufio"
    "io"
    "io/fs"
    "os"
    "path/filepath"
    "strings"
)

// countLines raises Scanner's 64 KiB per-token limit to 1 MiB.
func countLines(r io.Reader) (int, error) {
    sc := bufio.NewScanner(r)
    sc.Buffer(make([]byte, 0, 64*1024), 1<<20)
    n := 0
    for sc.Scan() {
        n++
    }
    // Without this check a too-long line silently ends the loop.
    return n, sc.Err()
}

func goFiles(root string) ([]string, error) {
    var out []string
    err := filepath.WalkDir(root, func(p string, d fs.DirEntry, err error) error {
        if err != nil {
            return err
        }
        if d.IsDir() && d.Name() == ".git" {
            return filepath.SkipDir
        }
        if !d.IsDir() && filepath.Ext(p) == ".go" {
            out = append(out, p)
        }
        return nil
    })
    return out, err
}

func pipeline(w io.Writer) (int64, error) {
    var log strings.Builder
    // TeeReader copies what is read; MultiWriter fans a write out.
    src := io.TeeReader(io.LimitReader(strings.NewReader("hello world"), 5), &log)
    return io.Copy(io.MultiWriter(w, os.Stdout), src)
}

In practice

  • Docker / containerd — Image layers and logs move through `io.Reader` pipelines (`io.Copy`, `TeeReader` to compute digests while streaming, `LimitReader` for untrusted input).
  • go command — `go build` and `go test` walk module trees with `filepath.WalkDir` and write outputs to temp files that are renamed into place.
  • Pitfall: os.Exit and defer — `os.Exit` and `log.Fatal` skip deferred cleanup. Return an error from `run()` and call `os.Exit` only in `main`.
  • Pitfall: Scanner limit — A log line over 64 KiB makes `bufio.Scanner` stop with `ErrTooLong`; if you never read `sc.Err()`, the rest of the file is silently skipped.

Trade-offs

Pros

  • Tiny interfaces (`Reader`, `Writer`, `fs.FS`) compose across files, sockets, buffers and tests
  • Streaming by default keeps memory flat for large inputs
  • `errors.Is` with `fs.Err*` gives portable error classification

Cons

  • `os.Exit` skips defers; `log.Fatal` does too
  • Ignoring `Close` on written files can lose data; `WriteFile` is not atomic
  • `bufio.Scanner` stops at 64 KiB per token unless you call `Buffer`, and you must check `Err()`
  • `path` vs `filepath` mix-ups break on Windows; `Glob` has no `**`; `Getenv` cannot tell unset from empty

Idioms

Configure a constructor with variadic `func(*T)` options so defaults stay implicit and new settings never break callers.

The problem

Go has no default arguments or overloading, so a constructor with many optional settings turns into a long positional parameter list or a struct whose zero values are ambiguous. Functional options keep the common call short, make defaults explicit in one place, and let you add settings later without breaking any caller.

How it works

  • Define `type Option func(*Server)`; each setting is a constructor like `WithTimeout(d)` that returns a closure capturing `d` and mutating the target.
  • The constructor takes required values as plain parameters and the rest as `opts ...Option`: `NewServer(addr string, opts ...Option)`. Zero options is a valid call.
  • Build the object with defaults first, then loop over `opts` and apply each one. Later options override earlier ones, so order is meaningful.
  • Validate after applying (or in the option itself) so the constructor can reject impossible combinations; return `(*Server, error)` when options can fail.
  • Error-returning variant: `type Option func(*Server) error`, and `NewServer` returns the first error. Use it when an option can be invalid (negative timeout, nil dependency).
  • Adding a new `WithXxx` is source-compatible for every existing caller; with a plain config struct you must also keep zero values meaning 'use default', which breaks for `false` and `0`.
  • Alternatives: a config struct (`Config{Addr: ...}`) is simpler and better for flat, mostly-required settings or when the config is loaded from a file; a builder (`b.Timeout(d).Build()`) is rarer in Go because chaining hides errors.
  • Use it for public library constructors with several optional, evolving settings. For internal types with two or three fields, a struct literal is clearer.

Go sketch

Go
import "time"

type Server struct {
    addr    string
    timeout time.Duration
    maxConn int
}

// Option mutates a Server while it is being constructed.
type Option func(*Server)

func WithTimeout(d time.Duration) Option {
    return func(s *Server) { s.timeout = d }
}

func WithMaxConn(n int) Option {
    return func(s *Server) { s.maxConn = n }
}

// NewServer: required args are plain parameters, the rest are options.
func NewServer(addr string, opts ...Option) *Server {
    s := &Server{addr: addr, timeout: 30 * time.Second, maxConn: 100} // defaults
    for _, opt := range opts {
        opt(s) // later options win
    }
    return s
}

func example() *Server {
    // Adding WithTLS later does not touch any of these call sites.
    return NewServer(":8080", WithTimeout(5*time.Second), WithMaxConn(10))
}

Error-returning variant: options validate themselves and NewServer stops at the first failure.

Go
import (
    "errors"
    "fmt"
    "time"
)

type Client struct {
    timeout time.Duration
    retries int
}

type Option func(*Client) error

func WithTimeout(d time.Duration) Option {
    return func(c *Client) error {
        if d <= 0 {
            return errors.New("timeout must be positive")
        }
        c.timeout = d
        return nil
    }
}

func WithRetries(n int) Option {
    return func(c *Client) error {
        if n < 0 {
            return fmt.Errorf("retries must be >= 0, got %d", n)
        }
        c.retries = n
        return nil
    }
}

func New(opts ...Option) (*Client, error) {
    c := &Client{timeout: 10 * time.Second, retries: 3}
    for _, opt := range opts {
        if err := opt(c); err != nil {
            return nil, fmt.Errorf("new client: %w", err)
        }
    }
    return c, nil
}

In practice

  • grpc-go — `grpc.NewServer(opts ...ServerOption)` and `grpc.NewClient(target, opts ...DialOption)` take `grpc.WithTransportCredentials(...)`, `grpc.WithUnaryInterceptor(...)` and similar.
  • zap — `zap.New(core, opts ...Option)` accepts `zap.AddCaller()`, `zap.Fields(...)` and `zap.WithCaller(...)`.
  • Origin — Popularised by Rob Pike's 'Self-referential functions and the design of options' (2014) and Dave Cheney's 'Functional options for friendly APIs'.
  • Counter-example — `net/http.Server` is a plain config struct whose zero values mean 'use default'; the standard library prefers this style for flat settings.

Trade-offs

Pros

  • Source-compatible API growth: new options never break callers.
  • Defaults live in one place and the common call stays short.
  • Options are self-documenting at the call site (`WithTimeout(5*time.Second)`) and can validate themselves.

Cons

  • More code than a struct: one function per setting plus the `Option` type, and godoc lists them as unrelated functions.
  • Order-dependent: two options touching the same field silently override each other.
  • A nil `Option` in the list panics when applied; the plain variant cannot report errors, so validation is easy to forget.
  • Overkill for internal types; a config struct is easier to load from JSON/YAML and to compare in tests.

Keep interfaces small, define them at the consumer, accept interfaces and return concrete types, and avoid the nil-pointer-in-interface trap.

The problem

Go interfaces are satisfied implicitly, so the language rewards small contracts defined where they are used. Declaring big interfaces up front next to the implementation (Java style) couples packages, blocks reuse and makes mocks painful.

How it works

  • Prefer one- or two-method interfaces: `io.Reader` (`Read`), `io.Writer` (`Write`), `fmt.Stringer` (`String`), `error` (`Error`). 'The bigger the interface, the weaker the abstraction.'
  • Accept interfaces, return structs: parameters take the narrowest interface the function needs; constructors return the concrete type so callers can use all its methods and you can add methods without breaking anyone.
  • Define the interface at the consumer, not the producer. The consumer declares only the methods it calls, and any type with those methods satisfies it without importing anything.
  • Compose interfaces by embedding: `io.ReadWriter` is `Reader` plus `Writer`; `io.ReadWriteCloser` adds `Closer`.
  • Do not introduce an interface until there are at least two implementations or a test needs a seam; a premature interface is just indirection.
  • Compile-time assertion `var _ Store = (*MemStore)(nil)` fails the build if `*MemStore` stops satisfying `Store`. Use it for types that are only used via an interface elsewhere.
  • Nil trap: an interface value is (type, value). Returning a nil `*MyErr` as `error` yields a non-nil interface, so `err != nil` is true. Return a literal `nil` on the success path.
  • Method sets matter: a value of type `T` has only value-receiver methods; `*T` has both. A `T` that has pointer-receiver methods does not satisfy the interface.
  • Mocking: give the code under test a small interface and write a tiny fake struct in the `_test.go` file; no mocking framework is needed.

Go sketch

Go
import (
    "fmt"
    "io"
    "strings"
)

// Defined by the consumer: only the one method it needs.
type Getter interface {
    Get(key string) (string, error)
}

type MemStore struct{ m map[string]string }

// Compile-time check that *MemStore satisfies Getter.
var _ Getter = (*MemStore)(nil)

// Return the concrete type; callers pick the interface they need.
func NewMemStore(m map[string]string) *MemStore { return &MemStore{m: m} }

func (s *MemStore) Get(key string) (string, error) {
    v, ok := s.m[key]
    if !ok {
        return "", fmt.Errorf("key %q not found", key)
    }
    return v, nil
}

// Accept an interface: works for files, buffers, HTTP bodies, ...
func CountLines(r io.Reader) (int, error) {
    b, err := io.ReadAll(r)
    if err != nil {
        return 0, err
    }
    return strings.Count(string(b), "\n"), nil
}

type MyErr struct{}

func (*MyErr) Error() string { return "my error" }

func mayFail(fail bool) error {
    // BUG if written as: var e *MyErr; return e  -> non-nil error holding nil.
    if fail {
        return &MyErr{}
    }
    return nil
}

A hand-written fake behind a small interface, plus interface composition.

Go
import (
    "io"
    "testing"
)

type Mailer interface {
    Send(to, body string) error
}

type fakeMailer struct{ sent []string }

func (f *fakeMailer) Send(to, body string) error {
    f.sent = append(f.sent, to)
    return nil
}

func Welcome(m Mailer, user string) error {
    return m.Send(user, "welcome")
}

func TestWelcome(t *testing.T) {
    f := &fakeMailer{}
    if err := Welcome(f, "ann@example.com"); err != nil {
        t.Fatal(err)
    }
    if len(f.sent) != 1 {
        t.Fatalf("sent = %v, want 1 message", f.sent)
    }
}

// Composition: a Pipe is anything that reads, writes and closes.
type Pipe interface {
    io.Reader
    io.Writer
    io.Closer
}

In practice

  • io — `io.Reader`/`io.Writer` let `io.Copy`, `bufio`, `gzip`, `http.Request.Body` and `os.File` interoperate with no shared base type.
  • database/sql — `driver.Driver`, `driver.Conn` and friends are small interfaces defined by the consumer (`database/sql`) and implemented by third-party drivers.
  • net/http — `http.Handler` is a single-method interface; `http.HandlerFunc` adapts a plain function to it, and `httptest.ResponseRecorder` fakes the writer in tests.
  • Pitfall — `*os.PathError`-style typed nil returned as `error` is a classic bug; `go vet` does not catch it, so keep the success path `return nil`.

Trade-offs

Pros

  • Small consumer-side interfaces decouple packages and make fakes trivial.
  • Implicit satisfaction means you can adapt types you do not own.
  • Returning concrete types keeps APIs discoverable and extensible.

Cons

  • Interface holding a nil pointer is non-nil: `var p *T; var i I = p; i != nil` is true.
  • Interface values cost an indirection and usually make the underlying value escape to the heap.
  • Implicit satisfaction hides mistakes (wrong receiver, wrong signature) until use; add `var _ I = (*T)(nil)`.
  • Interface bloat and one-implementation interfaces ('mockery everywhere') add indirection with no benefit.
  • Adding a method to a published interface breaks every implementer outside your module.

Add context with `%w`, then inspect the chain with `errors.Is`, `errors.As` and `errors.Join` instead of comparing strings or types directly.

The problem

A bare `return err` loses where and why something failed, while formatting it into a string with `%v` destroys the ability to test for a specific cause. Wrapping with `%w` keeps both the human-readable context and a machine-inspectable chain.

How it works

  • `fmt.Errorf("load user %d: %w", id, err)` returns an error whose `Unwrap()` yields `err`. With `%v` or `%s` the text is the same but the chain is cut.
  • `errors.Is(err, target)` walks the chain comparing with `==` (or a custom `Is(error) bool` method); use it for sentinels like `io.EOF` or `fs.ErrNotExist`. Never compare with `==` once errors are wrapped.
  • `errors.As(err, &target)` finds the first error in the chain assignable to the target's type; `target` must be a non-nil pointer to a type implementing `error` (or an interface type).
  • `errors.Unwrap(err)` returns one level only (nil if none). Prefer `Is`/`As`, which walk the whole chain.
  • Go 1.20: `fmt.Errorf` accepts multiple `%w` verbs and `errors.Join(errs...)` returns an error wrapping all non-nil inputs (messages separated by newlines); `Is`/`As` search all of them via `Unwrap() []error`.
  • Sentinel errors (`var ErrNotFound = errors.New(...)`) are for 'which condition'; typed errors (a struct with fields and `Error()`) are for 'which condition plus details'. Both survive wrapping.
  • Wrap once per layer with the operation's context, not the callee's name again; messages read like a stack: `load user 7: query users: connection refused`. Do not start with 'failed to' repeatedly.
  • Handle an error once: either log it or return it, not both. Logging and returning produces duplicate lines at every layer.
  • At API boundaries you may deliberately break the chain (`%v`, or convert to your own type) so callers cannot depend on internals such as a driver's error type.

Go sketch

Go
import (
    "errors"
    "fmt"
    "io/fs"
    "os"
)

var ErrNotFound = errors.New("not found") // sentinel

// QueryError is a typed error carrying details.
type QueryError struct {
    Query string
    Err   error
}

func (e *QueryError) Error() string { return "query " + e.Query + ": " + e.Err.Error() }
func (e *QueryError) Unwrap() error { return e.Err }

func find(id int) error {
    if id == 0 {
        return &QueryError{Query: "users", Err: ErrNotFound}
    }
    return nil
}

func loadUser(id int) error {
    if err := find(id); err != nil {
        return fmt.Errorf("load user %d: %w", id, err) // wrap once, with context
    }
    return nil
}

func classify(id int) string {
    err := loadUser(id)
    var qe *QueryError
    switch {
    case err == nil:
        return "ok"
    case errors.As(err, &qe) && errors.Is(err, ErrNotFound):
        return "missing in " + qe.Query
    case errors.Is(err, fs.ErrNotExist):
        return "file missing"
    default:
        return err.Error()
    }
}

func openConfig() error {
    _, err := os.Open("/no/such/file")
    return err // *fs.PathError; errors.Is(err, fs.ErrNotExist) is true
}

Go 1.20+: multiple %w, errors.Join, and a custom Is method.

Go
import (
    "errors"
    "fmt"
)

var (
    ErrTimeout   = errors.New("timeout")
    ErrTemporary = errors.New("temporary")
)

// StatusError matches any error with the same code via a custom Is.
type StatusError struct{ Code int }

func (e StatusError) Error() string { return fmt.Sprintf("status %d", e.Code) }

func (e StatusError) Is(target error) bool {
    t, ok := target.(StatusError)
    return ok && t.Code == e.Code
}

func demo() []bool {
    // Two causes in one error: both Is checks succeed.
    both := fmt.Errorf("fetch: %w and %w", ErrTimeout, ErrTemporary)

    // Join: collect independent failures, e.g. closing several resources.
    joined := errors.Join(errors.New("close a"), nil, ErrTimeout)

    // %v keeps the text but cuts the chain.
    cut := fmt.Errorf("fetch: %v", ErrTimeout)

    wrapped := fmt.Errorf("call: %w", StatusError{Code: 503})
    return []bool{
        errors.Is(both, ErrTemporary),              // true
        errors.Is(joined, ErrTimeout),              // true
        errors.Is(cut, ErrTimeout),                 // false
        errors.Is(wrapped, StatusError{Code: 503}), // true via custom Is
    }
}

In practice

  • os / io/fs — `os.Open` returns `*fs.PathError`; test with `errors.Is(err, fs.ErrNotExist)` rather than the older `os.IsNotExist`, which does not unwrap `%w`.
  • net/url, os/exec — `*url.Error`, `*net.OpError` and `*exec.ExitError` implement `Unwrap`/typed fields, so `errors.As` extracts exit codes or timeouts from deep inside.
  • Kubernetes — `k8s.io/apimachinery/pkg/api/errors` provides predicates like `apierrors.IsNotFound(err)` instead of exposing status structs to callers.
  • Logging — Log once at the top of the request or `main`, with the full wrapped message; lower layers only wrap and return.

Trade-offs

Pros

  • Context for humans and an inspectable chain for programs from one `%w`.
  • `Is`/`As` keep working when intermediate layers add or reorder wrapping.
  • Sentinels and typed errors are plain values: no exceptions or special syntax.

Cons

  • `%v`/`%s` instead of `%w` silently breaks `errors.Is`/`As` for all callers.
  • Wrapping makes the underlying error part of your API: callers may start depending on it. Break the chain at boundaries on purpose.
  • `errors.As` panics if the target is not a non-nil pointer to an error type or interface; `go vet` checks this.
  • Logging and returning at every layer duplicates log lines; wrapping on every line of a function builds noisy messages.
  • Comparing with `==` or `err.Error() == "..."` fails as soon as someone adds context.

Express test cases as a slice of structs run through `t.Run` subtests, with helpers, cleanup, temp dirs, fuzzing and benchmarks around them.

The problem

Repeating almost-identical test code for each input is noisy, and adding a case means copying a block. A table of cases plus one loop makes cases cheap to add, each case individually nameable, runnable and reportable.

How it works

  • Declare `tests := []struct{ name string; in string; want int; wantErr bool }{...}` and loop with `for _, tt := range tests`.
  • Wrap each case in `t.Run(tt.name, func(t *testing.T) {...})`. Subtests can be selected with `go test -run 'TestX/case_name'`, and failures name the case.
  • Use `t.Errorf` to keep checking after a failure and `t.Fatalf` when later checks would panic or be meaningless; include input, got and want in the message.
  • `t.Parallel()` inside the subtest runs cases concurrently. Since Go 1.22 (module `go` line >= 1.22) each iteration has its own `tt`; before that you needed `tt := tt`.
  • `t.Helper()` as the first line of an assertion helper makes failures report the caller's line. `t.Cleanup(fn)` runs LIFO after the test and its subtests; `t.TempDir()` gives a per-test directory removed automatically.
  • Compare structured results with `reflect.DeepEqual` or, with better diffs, `github.com/google/go-cmp/cmp` (`cmp.Diff(want, got)`); both are stricter about unexported fields than you may expect.
  • Golden files: store expected output in `testdata/` and compare; add an `-update` flag to regenerate. `testdata` is ignored by the go tool.
  • Fuzzing (Go 1.18+): `func FuzzXxx(f *testing.F)` with `f.Add` seeds and `f.Fuzz`; run with `go test -fuzz=FuzzXxx`. Benchmarks: `func BenchmarkXxx(b *testing.B)` looping `b.N` times (Go 1.24 adds `b.Loop()`).

Examples

Go
import (
    "errors"
    "strconv"
    "testing"
)

func parsePort(s string) (int, error) {
    n, err := strconv.Atoi(s)
    if err != nil {
        return 0, err
    }
    if n < 1 || n > 65535 {
        return 0, errors.New("port out of range")
    }
    return n, nil
}

func TestParsePort(t *testing.T) {
    tests := []struct {
        name    string
        in      string
        want    int
        wantErr bool
    }{
        {name: "ok", in: "8080", want: 8080},
        {name: "max", in: "65535", want: 65535},
        {name: "zero", in: "0", wantErr: true},
        {name: "not a number", in: "http", wantErr: true},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            t.Parallel() // safe: tt is per-iteration since Go 1.22
            got, err := parsePort(tt.in)
            if (err != nil) != tt.wantErr {
                t.Fatalf("parsePort(%q) error = %v, wantErr %v", tt.in, err, tt.wantErr)
            }
            if got != tt.want {
                t.Errorf("parsePort(%q) = %d, want %d", tt.in, got, tt.want)
            }
        })
    }
}

Helper, Cleanup, TempDir, plus fuzz and benchmark skeletons.

Go
import (
    "os"
    "path/filepath"
    "strconv"
    "strings"
    "testing"
)

func parsePort(s string) (int, error) { return strconv.Atoi(s) }

func writeFile(t *testing.T, dir, name, body string) string {
    t.Helper() // failures point at the caller, not here
    p := filepath.Join(dir, name)
    if err := os.WriteFile(p, []byte(body), 0o644); err != nil {
        t.Fatal(err)
    }
    return p
}

func TestReadConfig(t *testing.T) {
    dir := t.TempDir() // removed automatically
    p := writeFile(t, dir, "app.conf", "mode=dev")
    t.Cleanup(func() { t.Logf("finished with %s", p) }) // LIFO, runs last
    b, err := os.ReadFile(p)
    if err != nil {
        t.Fatal(err)
    }
    if got := strings.TrimPrefix(string(b), "mode="); got != "dev" {
        t.Errorf("mode = %q, want dev", got)
    }
}

func FuzzParsePort(f *testing.F) {
    f.Add("8080") // seed corpus
    f.Fuzz(func(t *testing.T, s string) {
        if n, err := parsePort(s); err == nil && (n < 1 || n > 65535) {
            t.Errorf("parsePort(%q) = %d: out of range without error", s, n)
        }
    })
}

func BenchmarkParsePort(b *testing.B) {
    for range b.N {
        _, _ = parsePort("8080")
    }
}

Running one subtest, the race detector, and a short fuzz session.

bash
go test -run 'TestParsePort/zero' -v ./...
go test -race -count=1 ./...
go test -fuzz=FuzzParsePort -fuzztime=10s
go test -bench=. -benchmem -run '^$'

In practice

  • Go standard library — Packages such as `strings`, `strconv` and `net/url` test almost everything with tables; Go's wiki 'TableDrivenTests' and the Go Code Review Comments document the style.
  • Kubernetes — Unit tests across the repo are table-driven with named cases, often with `go-cmp` for diffs.
  • net/http/httptest — Combine a table with `httptest.NewRecorder()` or `httptest.NewServer` to test handlers per case without opening real ports by hand.
  • gotests / IDEs — `gotests` and GoLand/VS Code generate the table skeleton from a function signature.

Trade-offs

Pros

  • Adding a case is one line; failures name the exact case and input.
  • Subtests give selective runs (`-run`), per-case parallelism and clean `t.Cleanup` scopes.
  • Plain Go, no assertion framework needed.

Cons

  • Before Go 1.22 (or with an older `go` line in go.mod) `t.Parallel()` in a loop shares one `tt`: every subtest sees the last case. Add `tt := tt`.
  • Parallel subtests that share state (maps, files, env vars) race; `t.Setenv` cannot be used with `t.Parallel`.
  • Giant tables with many optional fields become unreadable; split by behaviour or use setup functions.
  • Empty or duplicate `name` values make reports confusing (duplicates get `#01` suffixes); names with spaces become underscores in `-run`.
  • `reflect.DeepEqual` treats nil and empty slices/maps as different and is poor at diffs; consider `go-cmp`.

Struct and interface embedding promotes fields and methods for composition; it is not inheritance and has sharp edges around shadowing, mutexes and JSON.

The problem

Go has no inheritance, but you often want to reuse behaviour or wrap a type while overriding one method. Embedding promotes the embedded type's fields and methods to the outer type, giving composition with less boilerplate, but with promotion rules that surprise people expecting subclassing.

How it works

  • A field with only a type (`Base`, `*Base`, `io.Reader`) is embedded. Its exported fields and methods are promoted: `u.ID` means `u.Base.ID`, and `u.Describe()` calls `u.Base.Describe()` with the embedded value as receiver.
  • It is not inheritance: the embedded method sees only the embedded value, never the outer one, so there is no virtual dispatch. If `Base.Describe` calls `b.Name()`, an outer `Name` override is not used.
  • The outer type can shadow a promoted name by declaring its own field or method; the embedded one is still reachable as `u.Base.Describe()`.
  • Two embedded types at the same depth with the same name make the selector ambiguous. It is a compile error only when you use it (`c.Hello()`), unless the outer type declares its own.
  • Embedding an interface in a struct (`struct{ Store }`) satisfies that interface automatically; override just the methods you care about. Calling an unset embedded interface method panics with nil dereference. This is the standard partial-mock trick.
  • Embedding `sync.Mutex` promotes `Lock`/`Unlock` into your public API (`c.Lock()` becomes callable by anyone). Prefer a named unexported field `mu sync.Mutex` unless the type is intentionally a lock.
  • Embedding pointers (`*bufio.Reader`) shares the underlying value and may be nil; embedding values copies it with the outer struct (copying a struct containing a mutex is a `go vet` copylocks error).
  • Method sets: embedding `T` promotes `T`'s value methods to both `S` and `*S` and pointer methods only to `*S`; embedding `*T` promotes both to `S` and `*S`.
  • JSON: `encoding/json` flattens exported fields of an embedded struct into the outer object. If an embedded type has a `MarshalJSON` (e.g. `time.Time`), it is promoted and hijacks the whole outer struct's marshalling.

Go sketch

Go
import (
    "encoding/json"
    "fmt"
    "io"
    "sync"
)

type Base struct {
    ID int `json:"id"`
}

func (b Base) Describe() string { return fmt.Sprintf("base %d", b.ID) }

// User embeds Base: u.ID and u.Describe are promoted.
type User struct {
    Base
    Name string `json:"name"`
}

// Shadows Base.Describe; the original is still u.Base.Describe().
func (u User) Describe() string { return "user " + u.Base.Describe() }

// Prefer a named field over embedding sync.Mutex, which would export
// Lock and Unlock as part of Counter's API.
type Counter struct {
    mu sync.Mutex
    n  int
}

func (c *Counter) Inc() {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.n++
}

// Wrap a reader, overriding one method and delegating the rest.
type countingReader struct {
    io.Reader
    n int
}

func (c *countingReader) Read(p []byte) (int, error) {
    n, err := c.Reader.Read(p)
    c.n += n
    return n, err
}

func marshal() ([]byte, error) {
    return json.Marshal(User{Base: Base{ID: 1}, Name: "ann"}) // {"id":1,"name":"ann"}
}

Ambiguous selectors and embedding an interface to fake only part of it.

Go
import "fmt"

type A struct{}

func (A) Hello() string { return "a" }

type B struct{}

func (B) Hello() string { return "b" }

// C embeds A and B, which both have Hello at the same depth.
// Calling c.Hello() would be a compile error: ambiguous selector c.Hello.
// Declaring Hello on C resolves it.
type C struct {
    A
    B
}

func (c C) Hello() string { return c.A.Hello() + c.B.Hello() }

type Store interface {
    Get(key string) (string, error)
    Put(key, val string) error
}

// fakeStore only overrides Get. Calling Put on it would panic because the
// embedded Store is nil, which is fine if the test never reaches it.
type fakeStore struct {
    Store
    data map[string]string
}

func (f fakeStore) Get(key string) (string, error) {
    v, ok := f.data[key]
    if !ok {
        return "", fmt.Errorf("missing %q", key)
    }
    return v, nil
}

In practice

  • sort.Reverse — Returns a struct that embeds `sort.Interface` and overrides only `Less`, reusing `Len` and `Swap`.
  • bufio / io — `bufio.ReadWriter` embeds `*Reader` and `*Writer`; `io.ReadWriteCloser` embeds `Reader`, `Writer` and `Closer` interfaces.
  • http middleware — A wrapper struct embedding `http.ResponseWriter` and overriding `WriteHeader` to capture the status code; beware it hides optional interfaces such as `http.Flusher` and `http.Hijacker` unless you forward them.
  • testing — `testing.T` embeds an unexported `common` struct that supplies `Log`, `Error`, `Fatal` and friends.

Trade-offs

Pros

  • Reuses behaviour and delegates the rest without writing forwarding methods.
  • Embedded interfaces make wrappers, decorators and partial fakes short.
  • Compositional: no fragile base class, and no hidden virtual dispatch.

Cons

  • Not inheritance: an embedded method cannot call the outer type's override.
  • Promotion leaks API: embedding `sync.Mutex`, `*bytes.Buffer` or a large struct exports all its methods, and adding a method to the embedded type can change or break the outer type.
  • Ambiguous selectors surface only at the use site; shadowing a promoted name can silently change which method is called.
  • A promoted `MarshalJSON`/`String`/`Error` method takes over the outer type's encoding or formatting, a common surprise with embedded `time.Time`.
  • Embedded nil pointers or nil interfaces compile fine and panic at call time; copying a struct with an embedded `sync.Mutex` is flagged by `go vet`.

Performance

The compiler decides per value whether it lives on the stack or the heap; `-gcflags=-m` shows why, and `-benchmem` shows what it costs.

The problem

Every heap allocation costs allocator time and later GC work, while stack allocation is nearly free and needs no collection. Go has no `new`-versus-stack keyword: the compiler's escape analysis decides, so you need to know how to read its verdict before you can reason about allocations.

How it works

  • A value stays on the stack only if the compiler can prove it is not referenced after its function returns. Otherwise it "escapes" and is allocated on the heap; `new(T)` and `&T{}` do not decide this, usage does.
  • Typical escapes: returning a pointer to a local, sending a pointer on a channel, storing it in a heap object or global, capturing a variable by reference in a closure that outlives the frame, and passing a value to a callee whose parameter itself escapes.
  • Converting a non-pointer value to an interface (`any`, as in `fmt.Println(n)` arguments) usually heap-allocates a copy; the compiler avoids it only for small cases such as constants and single-byte values.
  • Size matters too: `make([]T, n)` with a non-constant `n`, a slice that `append` regrows, or a value larger than the compiler's stack limits (about 64 KB for implicit `new`/`make`/`&T{}`, about 10 MB for declared variables) goes to the heap.
  • `go build -gcflags=-m` prints decisions per package on the command line (use `-gcflags='all=-m'` for dependencies). `-m -m` adds the flow that caused each escape and the inlining cost.
  • Read the lines: `moved to heap: x` means variable `x` was heap-allocated; `x escapes to heap` means a value is converted or stored such that it outlives the frame; `does not escape` means the callee keeps no reference, so the caller may stack-allocate.
  • Inlining feeds escape analysis: `can inline f` and `inlining call to f` show that a small function body is copied into its caller, which often lets a returned pointer stay on the stack. A budget of 80 nodes decides eligibility (`with cost N` under `-m -m`).
  • Measure the effect with `go test -bench . -benchmem`: `allocs/op` and `B/op` are what escape analysis changes. Do not contort code from `-m` output alone; fix only hot paths that a benchmark or profile points at.
  • Escape analysis is a compiler implementation detail: results differ across Go versions and with inlining, so treat `-m` output as a diagnostic, not a contract.

Examples

Go
import "testing"

type point struct{ x, y int }

var (
    sinkPtr *point
    sinkVal point
)

// The pointer outlives this frame, so p is "moved to heap" (unless the caller
// inlines newPtr and keeps the result local).
func newPtr() *point {
    p := point{1, 2}
    return &p
}

// Returned by value: copied to the caller, no allocation needed.
func newVal() point {
    return point{1, 2}
}

func BenchmarkPtr(b *testing.B) {
    b.ReportAllocs()
    for range b.N {
        sinkPtr = newPtr() // stored in a global: forces the heap
    }
}

func BenchmarkVal(b *testing.B) {
    b.ReportAllocs()
    for range b.N {
        sinkVal = newVal()
    }
}

// go test -bench . -benchmem   (expect 1 allocs/op for Ptr, 0 for Val)

Inspect the compiler's decisions. The comment lines are real output from Go 1.24 for a file with a function returning &p, a closure that captures a counter and a fmt.Println(n) call.

bash
go build -gcflags=-m ./...
# ./ea.go:7:6: can inline newPoint
# ./ea.go:20:13: inlining call to fmt.Println
# ./ea.go:8:2: moved to heap: p
# ./ea.go:20:13: ... argument does not escape
# ./ea.go:20:14: n escapes to heap
# ./ea.go:24:2: moved to heap: c
# ./ea.go:25:9: func literal escapes to heap

# add the flow that caused each escape plus inline costs
go build -gcflags='-m -m' ./... 2>&1 | grep -A4 'p escapes'

# include dependencies, then allocation counts from a benchmark
go build -gcflags='all=-m' ./... 2>&1 | grep 'moved to heap'
go test -bench . -benchmem

In practice

  • fmt.Println — Its variadic `...any` arguments make non-constant values escape to heap (`n escapes to heap` above); in hot loops use `strconv.Append*` or a `bufio.Writer` instead.
  • Reference: Go GC guide — go.dev/doc/gc-guide explains why reducing heap allocations lowers GC CPU cost and how GOGC and the memory limit interact with live heap size.
  • Pointer-returning constructors — `NewT() *T` is idiomatic and fine; if a profile shows it allocating in a hot path, a by-value constructor or an `Init(*T)` method lets the caller own the memory.

Trade-offs

Pros

  • Stack allocation is nearly free and creates no GC work, so fewer escapes directly lowers latency and GC CPU.
  • `-gcflags=-m` and `-benchmem` are built in, need no extra tools and give an exact answer for a specific build.

Cons

  • Passing pointers "for speed" often causes escapes; copying a small struct is usually cheaper than a heap allocation.
  • `-m` output is per build and per Go version; code tuned to it can regress after a compiler upgrade.
  • `-gcflags=-m` only covers the packages named on the command line unless you use `all=`; the missing lines are easy to misread as "no escape".
  • Micro-optimizing away allocations without a benchmark makes code harder to read for no measurable win.

A per-P cache of temporary objects that cuts allocation of short-lived buffers, which the GC may drop at any time.

The problem

Code that allocates many short-lived, similarly sized objects (encoder buffers, scratch slices) puts steady pressure on the allocator and the GC. `sync.Pool` lets goroutines reuse such objects instead of allocating a fresh one each time, with no manual lifetime management and with the GC free to reclaim idle ones.

How it works

  • `sync.Pool{New: func() any {...}}` is a set of temporary items. `Get` returns a pooled item or calls `New` (nil if `New` is unset); `Put` returns an item. It is safe for concurrent use and must not be copied after first use.
  • Internally each P (scheduler processor) has a private slot and a shared queue, so `Get`/`Put` mostly avoid contention; items can also be stolen from other Ps.
  • Items may be removed at any time without notice. In current Go versions a GC moves the pool to a victim cache and drops that on the next GC, so an idle item survives one to two cycles. Never rely on an item still being there.
  • Pooled items must be reset: call `Reset()` or truncate a slice (`b = b[:0]`) before use or before `Put`, otherwise stale data leaks to the next user.
  • Never use an item after `Put`, and never `Put` one that is still referenced elsewhere (for example the `Bytes()` slice of a `bytes.Buffer` handed to a caller): the next `Get` would alias live data.
  • Store pointers (`*bytes.Buffer`, `*[]byte`), not slices or structs by value: putting a slice into `any` allocates its header on each `Put`, which defeats the point (staticcheck SA6002).
  • Cap the retained size: if a buffer grew past a threshold (for example 64 KB), drop it instead of `Put`, or one rare huge request pins that memory in every P's cache.
  • It helps when objects are allocated frequently, are short-lived and similar in size; the standard library uses it inside `fmt` (printer state) and `encoding/json` (encode state). It is not a connection or worker pool: it has no size limit, no cleanup hook and no blocking `Get`.
  • Benchmark with `-benchmem` first. For small objects or low allocation rates, a pool adds code and sometimes lowers speed, because the allocator and GC are already fast.

Go sketch

Go
import (
    "bytes"
    "sync"
)

const maxPooled = 64 << 10 // do not keep buffers bigger than 64 KB

var bufPool = sync.Pool{
    New: func() any { return new(bytes.Buffer) }, // pointer: no boxing alloc
}

// render returns a string, so the pooled buffer is never aliased by the caller.
func render(name string) string {
    buf := bufPool.Get().(*bytes.Buffer)
    buf.Reset() // clear data left by the previous user
    defer func() {
        if buf.Cap() <= maxPooled {
            bufPool.Put(buf)
        } // else: drop it and let the GC reclaim the huge buffer
    }()

    buf.WriteString("hello, ")
    buf.WriteString(name)
    return buf.String() // String copies; buf.Bytes() would alias pooled memory
}

// Failure modes (kept out of live code):
//   bufPool.Put(buf); buf.WriteString("x")  // use after Put: data race
//   return buf.Bytes()                      // then Put: caller aliases the pool
//   pool.Put(someSlice)                     // boxes the slice header: SA6002

Pooling a byte slice: store *[]byte and write the grown slice back so the capacity is kept.

Go
import "sync"

var slicePool = sync.Pool{
    New: func() any {
        b := make([]byte, 0, 4096)
        return &b
    },
}

func process(data []byte) int {
    bp := slicePool.Get().(*[]byte)
    b := (*bp)[:0]

    b = append(b, data...)
    b = append(b, '\n')
    n := len(b)

    *bp = b // remember the grown capacity for the next user
    slicePool.Put(bp)
    return n
}

In practice

  • fmt and encoding/json — The standard library keeps printer and encoder state in `sync.Pool`s, which is why `fmt.Sprintf` allocates little beyond its result.
  • Servers with per-request buffers — HTTP handlers that serialize responses commonly pool `*bytes.Buffer`; verify the gain with `-benchmem`, since many handlers are dominated by I/O instead.
  • staticcheck SA6002 — The linter warns when a non-pointer value is passed to `Pool.Put`, because converting it to `any` allocates and cancels the saving.

Trade-offs

Pros

  • Cuts allocations and GC work for hot, short-lived objects with a few lines of code.
  • Scales across cores thanks to per-P caches, and the GC can still shrink it when memory is tight.

Cons

  • Forgetting `Reset()` leaks the previous request's data into the next one, which is a correctness and security bug.
  • Use after `Put`, or returning `Bytes()` from a pooled buffer, creates aliasing bugs and data races.
  • One oversized buffer returned to the pool stays resident; always cap the size before `Put`.
  • Contents can vanish after any GC, so the pool cannot hold state, connections or anything needing `Close`.
  • For cheap or rarely allocated objects a pool is slower and more complex than plain allocation.

Avoid quadratic `+=` string building: use `strings.Builder`, `bytes.Buffer`, `strings.Join`, append-style APIs and preallocated slices.

The problem

Strings are immutable, so `s += x` in a loop copies the whole string every iteration: O(n²) bytes copied and one allocation per step. Building output efficiently means choosing a type that grows a single backing array, and sizing it up front when the size is known.

How it works

  • `a + b + c` in one expression is a single allocation. The quadratic cost appears when a string is grown across loop iterations (`s += part`).
  • `strings.Builder` appends into an internal `[]byte`. `Grow(n)` reserves capacity, `WriteString`/`WriteByte`/`WriteRune` append, and `String()` returns the bytes as a string without copying.
  • A `strings.Builder` must not be copied after first use: a copied non-zero Builder panics on the next write ("illegal use of non-zero Builder copied by value"). Pass `*strings.Builder` or use it as a local variable.
  • `bytes.Buffer` is a read/write buffer: it implements `io.Reader`, `io.Writer`, `io.ByteScanner` and `io.WriterTo`, so it can feed `io.Copy` or `json.NewDecoder`. `Reset()` reuses its memory.
  • `Buffer.Bytes()` aliases the internal slice and is valid only until the next modification; `Buffer.String()` copies. `bytes.NewBuffer(b)` takes ownership of `b`.
  • Choose by need: `strings.Builder` when the result is a string and you only write; `bytes.Buffer` when you also read, need `[]byte` output, or must reuse/pool the buffer; a plain `[]byte` with `append` when you need maximal control.
  • `strings.Join(parts, sep)` computes the total length first and allocates once, so prefer it when you already hold a slice of pieces. `fmt.Fprintf(&sb, ...)` writes formatted data straight into a Builder, avoiding a temporary string from `Sprintf`.
  • Append-style APIs (`strconv.AppendInt`, `time.Time.AppendFormat`, `fmt.Appendf` since Go 1.19) write into your slice and avoid per-number temporary strings.
  • Preallocate slices with `make([]T, 0, n)` when `n` is known; growth by `append` is amortized O(1) but copies and allocates repeatedly. Measure with `-benchmem` before and after.

Go sketch

Go
import (
    "fmt"
    "strings"
    "testing"
)

// O(n²): every += allocates a new string and copies all previous bytes.
func joinConcat(parts []string) string {
    s := ""
    for _, p := range parts {
        s += p + ","
    }
    return s
}

// One growing buffer; Grow avoids re-allocation when the size is predictable.
func joinBuilder(parts []string) string {
    var sb strings.Builder
    sb.Grow(len(parts) * 8)
    for i, p := range parts {
        if i > 0 {
            sb.WriteByte(',')
        }
        sb.WriteString(p)
        fmt.Fprintf(&sb, "#%d", i)
    }
    return sb.String() // no copy
}

func BenchmarkConcat(b *testing.B) {
    parts := strings.Split(strings.Repeat("item,", 1000), ",")
    b.ReportAllocs()
    for range b.N {
        _ = joinConcat(parts)
    }
}

// Compare: go test -bench Concat -benchmem  (then swap in joinBuilder)

Append-style APIs, a preallocated slice and bytes.Buffer used as an io.Writer source.

Go
import (
    "bytes"
    "io"
    "strconv"
)

// AppendInt writes into buf: no temporary string per number.
func formatIDs(ids []int) []byte {
    buf := make([]byte, 0, len(ids)*8)
    for _, id := range ids {
        buf = strconv.AppendInt(buf, int64(id), 10)
        buf = append(buf, ' ')
    }
    return buf
}

func writeIDs(w io.Writer, ids []int) error {
    var b bytes.Buffer
    b.Write(formatIDs(ids))
    _, err := b.WriteTo(w) // drains the buffer into w
    return err
}

func squares(n int) []int {
    out := make([]int, 0, n) // length 0, capacity n: no regrowth
    for i := range n {
        out = append(out, i*i)
    }
    return out
}

// var a strings.Builder; a.WriteString("x"); b := a; b.WriteString("y")
// panics: copying a non-zero Builder is illegal.

In practice

  • Standard library — `strings.Join`, `strings.Repeat` and `strings.Map` use `strings.Builder` internally, and `strings.Replace` builds into one pre-sized buffer.
  • Logging and encoding libraries — Structured loggers and encoders typically use `append`-style APIs onto a pooled `[]byte`, giving zero allocations per log line.
  • Pitfall: Bytes() aliasing — Keeping `buf.Bytes()` after `buf.Reset()` or a later write can show changed data; copy it or use `String()` if the result must outlive the buffer.

Trade-offs

Pros

  • Linear time and a handful of allocations instead of one per iteration, often orders of magnitude faster on large outputs.
  • `Grow`, `make([]T, 0, n)` and `Append*` give precise control over allocations when the size is known.

Cons

  • `s += x` is fine for a few pieces; rewriting trivial code to a Builder adds noise without a measurable gain.
  • Copying a non-zero `strings.Builder` panics; storing one in a struct that is copied by value is a trap.
  • `bytes.Buffer.Bytes()` aliases internal memory and `String()` copies, so mixing them up causes either bugs or hidden allocations.
  • Over-sizing `Grow`/`make` capacity wastes memory; use it with real size estimates.

Collect CPU, heap, goroutine, block and mutex profiles with `runtime/pprof` or `net/http/pprof`, and read them with `go tool pprof` and `go tool trace`.

The problem

Guessing where a Go program spends CPU or memory is usually wrong. The runtime has built-in sampling profilers that attribute time, allocations, blocked goroutines and lock contention to call stacks, with low enough overhead to use in production.

How it works

  • Profile types: `cpu` (sampled about 100 times per second while running), `heap`/`allocs` (sampled allocations, with `inuse_*` and `alloc_*` views), `goroutine` (all stacks now), `block` (time blocked on sync/channels) and `mutex` (contention on locks).
  • Long-running servers: `import _ "net/http/pprof"` registers `/debug/pprof/*` on `http.DefaultServeMux`. Serve it on a loopback or internal-only listener; never on the public port, since it exposes stacks, memory contents and can start expensive profiles.
  • CLIs and batch jobs: `pprof.StartCPUProfile(f)` with a deferred `StopCPUProfile`, and `pprof.WriteHeapProfile(f)` (call `runtime.GC()` first for up-to-date heap statistics).
  • Tests and benchmarks: `go test -bench . -cpuprofile cpu.out -memprofile mem.out` writes profiles and a test binary you can analyze offline.
  • `go tool pprof cpu.out` opens an interactive shell: `top` (flat vs cumulative), `list FuncName` (per-line costs), `web` (call graph in the browser), `peek`. `go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30` profiles a live process.
  • `go tool pprof -http=:8080 cpu.out` starts the web UI with a flame graph (View > Flame Graph), graph, source and top views. Heap views: `-sample_index=inuse_space` (live memory) vs `alloc_space` (total allocated, for GC pressure) and the `_objects` variants.
  • Compare runs with `go tool pprof -base old.out new.out` (or `-diff_base`): positive numbers are regressions, negative ones improvements.
  • Block and mutex profiles are off by default: enable with `runtime.SetBlockProfileRate(1)` (record every event; larger values are in nanoseconds) and `runtime.SetMutexProfileFraction(5)` (sample 1 in 5 contention events).
  • `go tool trace trace.out` shows a timeline of goroutine scheduling, GC and syscalls (collect with `runtime/trace` or `/debug/pprof/trace?seconds=5`). `GODEBUG=gctrace=1` prints one line per GC cycle with heap sizes and pause times.

Examples

Go
import (
    "net/http"
    _ "net/http/pprof" // registers /debug/pprof/* on http.DefaultServeMux
    "os"
    "runtime"
    "runtime/pprof"
)

// Debug listener on loopback only. Never expose pprof on a public port.
func startDebugServer() {
    go func() {
        _ = http.ListenAndServe("127.0.0.1:6060", nil)
    }()
}

// CPU profile of a CLI run.
func profileCPU(path string, work func()) error {
    f, err := os.Create(path)
    if err != nil {
        return err
    }
    defer f.Close()
    if err := pprof.StartCPUProfile(f); err != nil {
        return err
    }
    defer pprof.StopCPUProfile()
    work()
    return nil
}

func writeHeap(path string) error {
    f, err := os.Create(path)
    if err != nil {
        return err
    }
    defer f.Close()
    runtime.GC() // get up-to-date live-heap statistics
    return pprof.WriteHeapProfile(f)
}

// Off by default; turn on only while investigating.
func enableContentionProfiles() {
    runtime.SetBlockProfileRate(1)
    runtime.SetMutexProfileFraction(5)
}

Collect and read profiles: from tests, from a live service, as a diff, plus trace and GC logging.

bash
# benchmarks -> files
go test -bench . -benchmem -cpuprofile cpu.out -memprofile mem.out

# interactive shell: top, list Func, web, peek Func
go tool pprof cpu.out

# web UI with flame graph on :8080
go tool pprof -http=:8080 cpu.out

# live service (debug listener on loopback)
go tool pprof -http=:8080 'http://127.0.0.1:6060/debug/pprof/profile?seconds=30'
go tool pprof -sample_index=alloc_space -http=:8080 'http://127.0.0.1:6060/debug/pprof/heap'
curl -s 'http://127.0.0.1:6060/debug/pprof/goroutine?debug=2' | head -50

# compare before and after
go tool pprof -http=:8080 -base before.out after.out

# execution trace and GC log
curl -so trace.out 'http://127.0.0.1:6060/debug/pprof/trace?seconds=5'
go tool trace trace.out
GODEBUG=gctrace=1 ./myservice 2> gc.log

In practice

  • Go diagnostics docs — go.dev/doc/diagnostics and go.dev/blog/pprof describe the profilers and typical workflows; the web UI of `go tool pprof` is the same one used by Google's pprof project.
  • Profile-guided optimization — Since Go 1.21 a CPU profile saved as `default.pgo` in the main package directory is picked up by `go build` (`-pgo=auto`) and can improve inlining and layout in hot code.
  • Security note — A blank import in any dependency can register pprof on `DefaultServeMux`; if your public server uses the default mux, those endpoints go live with it. Use a dedicated mux for public traffic.
  • Goroutine leaks — A steadily growing count at `/debug/pprof/goroutine?debug=1` (grouped stacks) is the standard way to find leaked goroutines.

Trade-offs

Pros

  • Sampling profilers are cheap enough to leave endpoints available in production and capture real traffic.
  • One toolchain covers CPU, memory, contention and scheduling, with flame graph and diff views built in.

Cons

  • Exposing `/debug/pprof` publicly leaks internals and allows cheap denial of service; bind to loopback or authenticate.
  • CPU profiles show only on-CPU time; waiting on I/O or locks needs the block/mutex profiles or `go tool trace`.
  • Heap profiles are sampled (by default about one sample per 512 KB allocated) and reflect the last completed GC, so small or very recent allocations can be missing.
  • Block and mutex profiling add overhead at rate 1; enable them temporarily, not by default.
  • Profiling a debug or `-race` build, or a benchmark with too short a run, gives misleading hot spots.

Toolchain

Go modules: go.mod and go.sum, minimal version selection, go get / go mod tidy, replace, vendoring, proxies and workspaces.

The problem

Reproducible builds need every dependency pinned to an exact version, fetched from a verifiable source, without a GOPATH layout. Go modules put that in `go.mod` (what you require) and `go.sum` (hashes of what you got), and resolve versions with a deterministic algorithm instead of a solver.

How it works

  • `go.mod` directives: `module` (path), `go` (minimum language version; a hard requirement since 1.21), `toolchain` (Go 1.21+, suggested toolchain), `require`, `replace`, `exclude`, `retract`. Since Go 1.24 a `tool` directive tracks executable dependencies (`go get -tool`, run with `go tool name`).
  • Minimal version selection (MVS): the chosen version of a module is the highest of the minimums required anywhere in the graph, never 'the latest'. Upgrades happen only when you ask (`go get`), so builds stay stable without a lock file.
  • `go get pkg@v1.2.3`, `@latest`, `@master` (branch or commit) change the requirement; `@none` removes it. `go get -u ./...` upgrades dependencies; `go list -m -u all` shows available updates without changing anything.
  • `go mod tidy` adds missing and drops unused requirements (it considers tests and all build tags); `-diff` (Go 1.23+) only prints what it would change, useful in CI. `go mod why -m mod` explains why a module is needed; `go mod graph` prints the requirement edges.
  • `go.sum` holds hashes of module zips and `go.mod` files. Commit it. `go mod verify` re-checks the module cache against it; a mismatch means a changed or tampered download.
  • Major versions v2+ are different import paths: `module example.com/m/v2` and `import "example.com/m/v2/pkg"`. v0/v1 carry no suffix, and v0 makes no compatibility promise.
  • `replace old => ../local` (or another fork/version) redirects a module; it only applies in the main module's `go.mod`, so libraries cannot impose it on consumers. `retract [v1.0.1, v1.0.3]` marks published versions as bad.
  • Workspaces: `go work init ./a ./b`, `go work use ./c`, `go work sync` create `go.work` (do not commit it unless the repo is a deliberate multi-module mono-repo), letting several local modules resolve each other without `replace`. `GOWORK=off` ignores it.
  • Fetching: `GOPROXY` (default `https://proxy.golang.org,direct`) serves modules; `GOSUMDB` verifies hashes against the public checksum DB; `GOPRIVATE=corp.com/*` skips both proxy and sumdb for matching paths (it sets the defaults of `GONOPROXY` and `GONOSUMDB`). `go mod vendor` copies sources into `vendor/`, which `-mod=vendor` uses (the default when `vendor/` exists and `go` is 1.14+); `GOFLAGS=-mod=mod` lets commands edit `go.mod` on the fly.

Examples

Everyday module workflow. The go.mod shape is in the comments (a module path, go 1.22, a toolchain line, require/replace/retract blocks).

bash
# go.mod looks like:
#   module github.com/acme/app
#   go 1.22
#   toolchain go1.24.1
#   require github.com/google/uuid v1.6.0
#   replace github.com/acme/lib => ../lib
go mod init github.com/acme/app
go get github.com/google/uuid@v1.6.0   # pin a version
go get github.com/google/uuid@latest   # move to the newest release
go get github.com/old/dep@none         # drop a requirement
go mod tidy                            # sync go.mod/go.sum with the imports
go mod tidy -diff                      # CI: fail if tidy would change anything
go list -m -u all                      # which dependencies have updates?
go mod why -m golang.org/x/text        # who pulls this in?
go mod graph | head
go mod verify

Private modules, vendoring and a local workspace.

bash
go env -w GOPRIVATE='github.com/acme/*'     # no proxy, no sumdb for these
go env GOPROXY GOSUMDB GOFLAGS
go mod vendor && go build -mod=vendor ./...
go mod edit -replace=github.com/acme/lib=../lib
go mod edit -json | head                      # machine-readable go.mod

go work init ./app ./lib   # creates go.work next to them
go work use ./tools
go work sync
GOWORK=off go build ./...  # ignore the workspace (what CI should see)

In practice

  • CI hygiene — Run `go mod tidy -diff` (or tidy and `git diff --exit-code go.mod go.sum`) so a missing or stale requirement fails the build instead of someone's laptop.
  • Private repos — Set `GOPRIVATE` and configure git credentials (`git config url.<ssh>.insteadOf`); otherwise `go get` asks the public proxy and sumdb about paths they cannot see.
  • Tool pinning — Before Go 1.24 teams pinned dev tools with a `tools.go` file using blank imports under a build tag; the `tool` directive replaces that trick.
  • Multi-module repos — A sub-module is tagged with its directory prefix (`lib/v1.2.0` for `lib/`); `go.work` is for local development, CI should also build with `GOWORK=off`.

Trade-offs

Pros

  • Deterministic builds with no lock file: MVS never silently picks a newer version.
  • Hash verification through `go.sum` and the checksum DB protects against tampered or swapped releases.
  • The module proxy keeps builds working when an upstream repo disappears.

Cons

  • Forgetting the `/v2` suffix: tagging v2.0.0 without changing the module path leaves consumers on a broken or incompatible state.
  • `replace` in a library's `go.mod` is ignored by its consumers, so it cannot fix their builds.
  • A committed `go.work` hides version conflicts: it builds locally and fails in CI or for consumers.
  • `go get -u` upgrades indirect dependencies too and can pull in breaking minor releases of v0 modules; prefer upgrading one module at a time.
  • Retracting does not remove a version: it stays fetchable and pinned users keep it until they upgrade.

The go test flags you use daily: -run, -count=1, -race, -cover, -bench, -short, -shuffle, -fuzz, profiling, and how test caching works.

The problem

`go test` runs far more than 'all tests': it caches results, runs packages in parallel, and has flags for races, coverage, benchmarks, fuzzing and profiling. Not knowing them means slow feedback loops, stale cached passes, and flaky tests that only show up in CI.

How it works

  • `-run regexp` selects tests; it is unanchored, so use `-run '^TestX$'`. Subtests are matched level by level split on `/`: `-run 'TestX/case_name'` (spaces in names become `_`). `-skip regexp` (Go 1.20+) does the inverse.
  • `-v` prints each test; `-json` emits a `test2json` event stream for CI tooling; `-failfast` stops after the first failure; `-count=n` repeats tests, and `-count=1` is the idiomatic way to bypass the cache.
  • Caching: in package-list mode (`go test ./...`, not bare `go test`) a passing result is cached while the test binary, its input files and env vars it reads are unchanged, and only 'cacheable' flags are used (`-run`, `-short`, `-v`, `-timeout`, `-parallel`, `-cpu`, `-failfast`, `-benchtime`, `-list`). Files outside the module or unseen state (network, time) are not tracked.
  • `-race` builds with the race detector (needs cgo on most platforms; roughly 5-10x memory and 2-20x CPU). `-shuffle=on` (or a seed) randomizes test order and prints the seed, to expose order dependence.
  • `-short` sets `testing.Short()` so slow tests can `t.Skip`; `-timeout 30s` bounds the whole test binary (default 10m) and panics with goroutine dumps on expiry; `-parallel n` caps `t.Parallel()` tests (default `GOMAXPROCS`).
  • Coverage: `-cover` prints a percent, `-coverprofile=c.out` writes it, `go tool cover -html=c.out` renders it; `-coverpkg=./...` counts coverage of other packages caused by this test.
  • Benchmarks: `-bench .` (regexp), `-benchmem` adds allocs, `-benchtime 2s` or `100x`; tests run too unless you add `-run '^$'`. `-cpuprofile`/`-memprofile` write pprof files (one package at a time) for `go tool pprof`.
  • Fuzzing (Go 1.18+): `-fuzz FuzzName -fuzztime 30s` (or `1000x`) targets exactly one fuzz function in one package; failures are saved under `testdata/fuzz/` and then run as ordinary regression tests.
  • `-tags integration` enables files with `//go:build integration`; `TestMain(m *testing.M)` wraps a package's tests for setup and teardown and must call `os.Exit(m.Run())` (or return, Go 1.15+). `go vet` runs automatically with a small subset of checks during `go test`; `-vet=off` disables it.

Examples

Go
import (
    "fmt"
    "os"
    "testing"
)

// TestMain runs once per package: shared setup, then m.Run, then teardown.
func TestMain(m *testing.M) {
    if err := setup(); err != nil {
        fmt.Fprintln(os.Stderr, "setup:", err)
        os.Exit(1)
    }
    code := m.Run()
    teardown()
    os.Exit(code) // without this the exit status is lost on older Go versions
}

func setup() error { return nil }

func teardown() {}

// Run it with: go test -short ./...   (skips)  or  go test ./...  (runs)
func TestSlowIntegration(t *testing.T) {
    if testing.Short() {
        t.Skip("skipping slow test in -short mode")
    }
    // ... talk to a real database ...
}

Daily commands: focused runs, race and coverage, benchmarks, fuzzing and profiles.

bash
go test ./...                                  # everything, cached
go test -count=1 ./internal/store              # bypass the cache
go test -run '^TestParse$' -v ./pkg/parser
go test -run 'TestParse/empty_input' ./pkg/parser   # one subtest
go test -skip 'Integration' ./...              # Go 1.20+
go test -race -shuffle=on -failfast ./...
go test -short -timeout 30s ./...
go test -coverprofile=c.out ./... && go tool cover -html=c.out
go test -run '^$' -bench . -benchmem -benchtime 2s ./pkg/codec
go test -run '^$' -bench BenchmarkEncode -cpuprofile cpu.out ./pkg/codec
go tool pprof -top cpu.out
go test -fuzz FuzzParse -fuzztime 30s ./pkg/parser
go test -tags integration -json ./... > result.json
go vet ./...

In practice

  • CI — Typical CI line: `go test -race -count=1 -shuffle=on ./...`, with `-count=1` so a cached pass never hides an environment change.
  • Flaky tests — Reproduce with `go test -run '^TestX$' -count=200 -race`; a printed `-test.shuffle` seed lets you replay an order-dependent failure.
  • Pitfall: -run — `-run TestUser` also matches `TestUserDelete`; anchor it. `-bench` and `-run` are independent: `-bench .` still runs every unit test first.
  • Pitfall: cache — A test that reads a file outside the module or a remote service can keep showing `(cached)`; the cache keys on files opened via the `os` package and env vars, not on external state.

Trade-offs

Pros

  • Race detector, coverage, fuzzing and profiling are built in: no extra dependencies.
  • The result cache makes re-runs of unchanged packages instant.
  • `-json` and `-shuffle` make CI output machine-readable and order-independent by default.

Cons

  • `-race` only reports races that actually happen during the run; it slows tests and needs cgo.
  • `-cover` instruments code, so coverage runs can behave and perform differently from normal ones.
  • `-fuzz` accepts a single target and a single package; it does not run as part of `./...`.
  • `-cpuprofile`/`-memprofile` leave a test binary on disk and refuse multiple packages.
  • A `TestMain` that forgets `os.Exit(m.Run())` (before Go 1.15) or does heavy setup slows every test in the package.

go build / install / run, stripping with -s -w, injecting versions with -X, -trimpath, GOOS/GOARCH cross-compilation, build constraints, embed and PGO.

The problem

Shipping a Go program means producing the right binary for the right platform, with a version baked in, no leaked build paths and a small size. The toolchain does all of this with a handful of flags, but they are easy to misapply: `-X` silently does nothing on the wrong variable, and a cgo default can break a 'static' scratch image.

How it works

  • `go build` compiles (writes a binary for `main` packages, discards the result otherwise); `go install` builds and puts the binary in `$GOBIN` (default `$GOPATH/bin`), and `go install pkg@version` installs a tool without touching `go.mod`; `go run .` builds to a temp file and runs it. `-o path` sets the output.
  • `-ldflags '-s -w'` omits the symbol table and DWARF debug info: a noticeably smaller binary, but no useful `gdb`/`dlv` symbols, though stack traces still work. `-ldflags` applies to the main package only by default; use `-ldflags='pkg=...'` to target another.
  • `-ldflags '-X path.name=value'` sets a string variable at link time. The path is the full import path (`github.com/acme/app/internal/version.Version`, or `main.version`), and the variable must be a package-level `string` that is uninitialized or initialized to a constant string; it silently does nothing for ints, consts or computed values.
  • `-trimpath` strips local file system paths from the binary (and from stack traces), improving reproducibility and avoiding leaking `/home/ci/...`. `-tags a,b` enables build tags; `-race` builds with the race detector.
  • Cross-compiling needs no extra toolchain: `GOOS=linux GOARCH=arm64 go build`. List valid pairs with `go tool dist list`, inspect settings with `go env` (`go env -w` persists one). `CGO_ENABLED=0` forces a pure-Go, statically linked binary; with cgo on and no C toolchain for the target, cross-builds fail.
  • Build constraints: a `//go:build linux && amd64` line (before `package`, followed by a blank line) or a filename suffix (`_linux.go`, `_windows_amd64.go`, `_test.go`) controls which files compile. `//go:embed` (`import _ "embed"`) embeds files into a `string`, `[]byte` or `embed.FS`; patterns cannot leave the module, and dotfiles need `all:`.
  • Version info: `go build` stamps the main module version and VCS data (`vcs.revision`, `vcs.time`, `vcs.modified`) by default (`-buildvcs=auto`); read it with `runtime/debug.ReadBuildInfo()` or `go version -m ./bin`. Use `-buildvcs=false` when there is no `.git` (docker context, source tarball).
  • PGO (Go 1.21+): put a CPU profile at `default.pgo` in the main package directory (or pass `-pgo=file`; `-pgo=auto` is the default, `-pgo=off` disables it) and the compiler inlines and devirtualizes hot paths. Go's docs cite single-digit to low-double-digit percentage gains in typical services.
  • Reproducible builds: same Go version, same source and dependencies, `-trimpath`, `CGO_ENABLED=0`, and no changing `-X` values (like timestamps) give the same bytes. A static binary runs in a `FROM scratch` image, which then needs CA certificates (`/etc/ssl/certs/ca-certificates.crt`) and, if you use `time.LoadLocation`, `time/tzdata` or a zoneinfo copy.

Examples

Go
import (
    "fmt"
    "runtime/debug"
)

// Set at link time: go build -ldflags "-X main.version=v1.4.2"
var version = "dev"

// buildVersion combines the injected version with VCS data stamped by go build.
func buildVersion() string {
    bi, ok := debug.ReadBuildInfo()
    if !ok {
        return version
    }
    var rev string
    dirty := false
    for _, s := range bi.Settings {
        switch s.Key {
        case "vcs.revision":
            rev = s.Value
        case "vcs.modified":
            dirty = s.Value == "true"
        }
    }
    if len(rev) > 7 {
        rev = rev[:7]
    }
    if dirty {
        rev += "-dirty"
    }
    return fmt.Sprintf("%s (%s, %s)", version, rev, bi.GoVersion)
}

A release build: stripped, path-free, versioned, static, for another platform.

bash
VERSION=$(git describe --tags --always --dirty)
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build \
  -trimpath \
  -ldflags "-s -w -X main.version=$VERSION" \
  -o bin/app-linux-arm64 ./cmd/app

go version -m bin/app-linux-arm64   # embedded module and VCS info
go tool dist list | grep linux      # valid GOOS/GOARCH pairs
go env GOOS GOARCH CGO_ENABLED GOFLAGS
go install golang.org/x/tools/cmd/stringer@latest

Build constraints, PGO and a scratch image. The Go-side lines are shown as comments.

bash
# file: fsnotify_linux.go (suffix) or any file starting with:
#   //go:build linux && (amd64 || arm64)
#
#   package watch
go build -tags integration ./...        # enables //go:build integration files

# PGO: collect a CPU profile from production, commit it as default.pgo
curl -o cmd/app/default.pgo 'http://localhost:6060/debug/pprof/profile?seconds=30'
go build -pgo=auto ./cmd/app            # auto is the default in Go 1.21+

# Dockerfile tail: FROM scratch, COPY --from=build /out/app /app
CGO_ENABLED=0 go build -trimpath -buildvcs=false -o /tmp/app ./cmd/app

In practice

  • goreleaser — By default injects `main.version`, `main.commit` and `main.date` with `-ldflags -X`; matching `var version, commit, date string` in `main` is the convention.
  • Kubernetes — Builds stamp version info into `k8s.io/component-base/version` through `-ldflags -X`, which is why the variable path must be the full import path.
  • Pitfall: -X — `-X main.version=1` is ignored if `version` lives in another package, is a `const`, or is an `int`. Check with `go version -m` or by printing the value, and quote values containing spaces.
  • Pitfall: cgo — On Linux, `net` and `os/user` use cgo by default; a 'static' binary built without `CGO_ENABLED=0` can fail to start in `scratch` or Alpine with 'not found'.

Trade-offs

Pros

  • One toolchain cross-compiles to every supported platform with two environment variables.
  • Static, self-contained binaries make deployment as simple as copying a file.
  • Build info (VCS revision, module versions) is embedded by default, so any binary can say what it was built from.

Cons

  • `-s -w` removes debugger symbols; keep an unstripped build for post-mortems.
  • `-X` fails silently on non-string or initialized-by-function variables, and a typo in the path is not an error.
  • `CGO_ENABLED=0` swaps in the pure-Go DNS resolver and user lookup, which can behave differently from libc.
  • `-trimpath` changes the paths shown in stack traces and breaks tooling that maps them back to local files.
  • Stamping timestamps with `-X` makes builds non-reproducible; prefer the commit time.

A fast, cached runner for many Go linters: v2 .golangci.yml layout, recommended linters, //nolint rules and a CI step.

The problem

Running staticcheck, errcheck, govet, gosec and a dozen others by hand means different flags, config files and run times per tool. golangci-lint runs them in parallel over one shared type-checked load of your code, caches results, and reads one config, so the whole team and CI see the same findings.

How it works

  • Install the binary (releases, `brew install golangci-lint`, or the install script pinned to a version); the project recommends against `go install` because it can build with a different Go version and dependencies. Run `golangci-lint run ./...`; `golangci-lint linters` lists what is enabled; `golangci-lint config verify` validates the config against the schema.
  • v2 config (Mar 2025) starts with `version: "2"`. `linters.default` is `standard` (errcheck, govet, ineffassign, staticcheck, unused), `all`, `none` or `fast`; `linters.enable` / `linters.disable` adjust it; per-linter options go in `linters.settings`.
  • In v2 formatters (gofmt, gofumpt, goimports, gci, golines, swaggo) moved from linters to a top-level `formatters:` section; `golangci-lint fmt` applies them. v1 `gosimple` and `stylecheck` are merged into `staticcheck`; v1 `issues.exclude-*` and `exclude-rules` became `linters.exclusions` (`presets`, `rules`, `paths`, `generated`).
  • Migrating from v1: `golangci-lint migrate` rewrites the config (a backup is kept; comments are not preserved). Use a version-pinned install in CI so a new linter release does not break the pipeline.
  • `--fix` applies auto-fixes where a linter supports them. `--new-from-rev=HEAD~1` (or `--new-from-merge-base=origin/main`) reports only issues in changed lines, which lets you adopt strict rules on a legacy codebase without fixing everything first.
  • Suppress a finding on one line or node with `//nolint:errcheck // best-effort cleanup`. Name the linter and give a reason; enable `nolintlint` with `require-explanation: true` and `require-specific: true` so a bare `//nolint` fails the lint.
  • Recommended additions to the standard set: `gosec` (security), `revive` (style), `errorlint` (errors.Is/As and `%w`), `bodyclose` (HTTP response bodies), `contextcheck` (context propagation), `gocritic` (misc. bugs and style), `misspell` and `nolintlint`. Enable more gradually; every linter has false positives.
  • In CI, use the official `golangci/golangci-lint-action` after `actions/setup-go`, pin the golangci-lint `version`, and let the action handle caching; for repos with several modules run it once per module (`working-directory`).

Examples

A v2 .golangci.yml: the standard set plus extras, settings, exclusions and formatters.

yaml
version: "2"
run:
  timeout: 5m
linters:
  default: standard        # errcheck, govet, ineffassign, staticcheck, unused
  enable:
    - bodyclose
    - contextcheck
    - errorlint
    - gocritic
    - gosec
    - misspell
    - nolintlint
    - revive
  settings:
    errcheck:
      check-type-assertions: true
    nolintlint:
      require-explanation: true
      require-specific: true
  exclusions:
    generated: lax
    presets:
      - comments
      - std-error-handling
    rules:
      - path: _test\.go
        linters:
          - gosec
formatters:
  enable:
    - gofmt
    - goimports

Everyday commands, including adopting the linter on an existing codebase.

bash
golangci-lint run ./...
golangci-lint run --fix ./...
golangci-lint run --new-from-rev=HEAD~1 ./...          # only newly introduced issues
golangci-lint run --new-from-merge-base=origin/main ./...
golangci-lint run --enable-only=errcheck ./...         # try one linter
golangci-lint linters                                  # what is on/off
golangci-lint config verify
golangci-lint migrate                                  # v1 config -> v2
golangci-lint fmt ./...                                # run the configured formatters
# in code: _ = f.Close() or  defer f.Close() //nolint:errcheck // read-only file

GitHub Actions job using the official action (check the action's README for the current major).

yaml
name: lint
on:
  pull_request:
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  golangci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
      - uses: golangci/golangci-lint-action@v9
        with:
          version: v2.5

In practice

  • Open-source projects — Prometheus keeps a `.golangci.yml` in the repo root and runs golangci-lint in CI, as do many large Go projects, so contributors get the same results locally.
  • Legacy adoption — Turn on a strict set with `--new-from-rev` so only new code is judged, then burn down old findings in separate PRs.
  • Pitfall: v1 config — A v1-format file under golangci-lint v2 is rejected (missing `version: "2"`); run `golangci-lint migrate` instead of hand-editing, and note `golangci-lint-action` v7+ is needed for v2.
  • Pitfall: nolint — A bare `//nolint` silences every linter on that line; use `//nolint:errcheck // reason` and enforce it with `nolintlint`.

Trade-offs

Pros

  • One command, one config and one cache for dozens of analyzers; results are consistent between laptops and CI.
  • Incremental adoption (`--new-from-rev`) makes strict linting possible on large legacy code.
  • Auto-fix (`--fix`) and formatters (`golangci-lint fmt`) remove a class of review nits.

Cons

  • Enabling `all` pulls in conflicting and noisy linters, and new releases add linters that change results; pin the version and pick a set.
  • Each linter has false positives, and heavy suppression with `//nolint` erodes the value.
  • The v1 to v2 config change is breaking: `migrate` drops comments and some options need manual review.
  • Memory and time grow on big monorepos, since all linters share one type-checked load of all packages.