Go

if err != nil {
    return fmt.Errorf("fetch user %d: %w", id, err)   // %w keeps the wrapped error in the chain
}

var pathErr *fs.PathError
if errors.As(err, &pathErr) { /* inspect pathErr.Path */ }
if errors.Is(err, context.DeadlineExceeded) { /* the request timed out */ }

// A sentinel for a condition callers must branch on
var ErrNotFound = errors.New("not found")

defer func() {
    if cerr := f.Close(); cerr != nil && retErr == nil {
        retErr = fmt.Errorf("close: %w", cerr)
    }
}()

ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()                                    // release resources even on the success path

req, _ := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)

select {
case <-ctx.Done():
    return ctx.Err()                              // Canceled or DeadlineExceeded
case res := <-ch:
    return res, nil
}

g, ctx := errgroup.WithContext(ctx)
for _, id := range ids {
    g.Go(func() error {
        return process(ctx, id)                   // loop variable is per-iteration since Go 1.22
    })
}
if err := g.Wait(); err != nil { return err }     // first non-nil error cancels the group's context

sem := make(chan struct{}, 8)                     // at most 8 in flight
for _, job := range jobs {
    sem <- struct{}{}
    go func(j Job) { defer func() { <-sem }(); work(j) }(job)
}

// In the consumer package
type UserStore interface {
    Get(ctx context.Context, id int64) (*User, error)
}

func NewHandler(s UserStore) *Handler { return &Handler{store: s} }

var p *MyError            // a nil pointer
var err error = p         // an interface value holding a nil *MyError, so it is non-nil
fmt.Println(err == nil)   // false

s := make([]int, 0, 100)        // length 0, capacity 100: 100 appends without reallocating
b := s[1:3]                     // shares the backing array; a write to b changes s
c := slices.Clone(s)            // an independent copy
s = slices.Delete(s, 1, 2)      // removes index 1, shifting the tail down in place
clear(m)                        // empty a map without reallocating (Go 1.21+)

for i, r := range "héllo" {     // i is a byte offset, r is a rune
    _ = r
}
len("héllo")                    // 6 bytes
utf8.RuneCountInString("héllo") // 5 runes

var b strings.Builder
for _, s := range parts { b.WriteString(s) }
result := b.String()

srv := &http.Server{
    Addr:              ":8080",
    Handler:           mux,
    ReadHeaderTimeout: 5 * time.Second,     // time to read request headers; blocks Slowloris
    ReadTimeout:       15 * time.Second,    // time to read the entire request
    WriteTimeout:      30 * time.Second,    // time to write the response
    IdleTimeout:       60 * time.Second,    // keep-alive idle period
}

go func() {
    if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
        log.Error("server", "err", err)     // ErrServerClosed is the normal shutdown signal
    }
}()

<-ctx.Done()
shutdownCtx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
defer cancel()
_ = srv.Shutdown(shutdownCtx)               // stop accepting, drain in-flight requests

client := &http.Client{
    Timeout: 10 * time.Second,              // covers connect, redirects and reading the body
    Transport: &http.Transport{
        MaxIdleConnsPerHost: 100,
        IdleConnTimeout:     90 * time.Second,
    },
}
// per request:
defer resp.Body.Close()
io.Copy(io.Discard, resp.Body)              // drain remaining bytes so the connection can be reused

func TestParse(t *testing.T) {
    tests := []struct {
        name string
        in   string
        want Config
        err  error
    }{
        {name: "empty", in: "", err: ErrEmpty},
        {name: "valid", in: "a=1", want: Config{A: 1}},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            t.Parallel()
            got, err := Parse(tt.in)
            if !errors.Is(err, tt.err) {
                t.Fatalf("err = %v, want %v", err, tt.err)
            }
            if diff := cmp.Diff(tt.want, got); diff != "" {
                t.Errorf("mismatch (-want +got):\n%s", diff)
            }
        })
    }
}

func BenchmarkParse(b *testing.B) {
    b.ReportAllocs()
    for b.Loop() {
        _, _ = Parse(input)
    }
}

go mod init example.com/api
go get example.com/pkg@latest                  # add or upgrade a dependency
go mod tidy                                     # add missing imports, remove unused ones
go mod vendor                                   # vendor deps into ./vendor for an offline build
go list -m -u all                               # show available upgrades for every module
go build -ldflags="-X main.version=$(git describe --tags)" ./cmd/api   # stamp the version
GOFLAGS=-mod=readonly go build ./...            # fail the build if go.mod would change

import _ "net/http/pprof"                        // registers handlers on the default mux
go func() { log.Println(http.ListenAndServe("localhost:6060", nil)) }()

go tool pprof -http=:8080 http://localhost:6060/debug/pprof/heap        # heap, interactive
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30      # 30s CPU profile
curl -o trace.out 'http://localhost:6060/debug/pprof/trace?seconds=5' && go tool trace trace.out
GODEBUG=gctrace=1 ./api                          # GC pauses and heap growth on stderr, no code change

func Map[T, U any](in []T, f func(T) U) []U {
    out := make([]U, 0, len(in))
    for _, v := range in { out = append(out, f(v)) }
    return out
}

func Max[T cmp.Ordered](a, b T) T {            // cmp.Ordered: integers, floats, strings
    if a > b { return a }
    return b
}

type Number interface{ ~int | ~int64 | ~float64 }   // ~ admits named types whose underlying type matches

type Cache[K comparable, V any] struct {       // a generic type; methods cannot add their own type parameters
    mu sync.Mutex
    m  map[K]V
}
func (c *Cache[K, V]) Get(k K) (V, bool) { c.mu.Lock(); defer c.mu.Unlock(); v, ok := c.m[k]; return v, ok }

func pool(ctx context.Context, jobs <-chan Job, workers int) <-chan Result {
    results := make(chan Result)
    var wg sync.WaitGroup
    for i := 0; i < workers; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for j := range jobs {                       // exits when jobs is closed
                select {
                case results <- work(ctx, j):
                case <-ctx.Done():
                    return
                }
            }
        }()
    }
    go func() { wg.Wait(); close(results) }()           // exactly one closer, after all senders finish
    return results
}

go test ./...                                    # every package; results are cached per package
go test -count=1 ./...                           # bypass the test cache
go test -run 'TestParse/valid' ./pkg             # regex on Test name, then on subtest name, separated by /
go test -skip 'TestSlow' ./...                   # Go 1.20+: inverse of -run
go test -short ./...                             # tests call testing.Short() to skip long paths
go test -timeout 2m ./...                        # panic with a goroutine dump when the package exceeds it (default 10m)
go test -shuffle=on ./...                        # randomise test order to expose ordering dependencies
go test -failfast ./...                          # stop after the first failing test
go test -v -json ./... | go tool test2json        # machine-readable events for CI dashboards
go test -fuzz=FuzzParse -fuzztime=30s ./pkg      # run a fuzz target; failing inputs land in testdata/fuzz/
go test -cover -coverpkg=./... ./...             # coverage of all packages, not just the one under test
go test -bench=. -benchtime=5s -count=6 ./pkg | tee new.txt && benchstat old.txt new.txt   # statistically compare

go work init ./api ./lib            # creates go.work listing both modules
go work use ./tools                 # add a module
go work sync                        # push the workspace's chosen versions back into each go.mod
GOWORK=off go build ./...           # build as CI would, ignoring the workspace

//go:build linux && !integration

package store

go test -tags=integration ./...     # compile files constrained by //go:build integration
go vet -tags=integration ./...      # vet the same set; untagged runs never see those files

import "embed"

//go:embed migrations/*.sql
var migrations embed.FS               // read with fs.ReadFile(migrations, "migrations/001_init.sql")

//go:embed VERSION
var version string                    // a single file may embed straight into a string or []byte

//go:embed all:static
var static embed.FS                   // include dotfiles under static/
http.Handle("/static/", http.FileServerFS(static))   // Go 1.22+: serve an fs.FS directly

# .golangci.yml
version: "2"
run:
  timeout: 5m
  tests: true
linters:
  default: standard                # errcheck, govet, ineffassign, staticcheck, unused
  enable:
    - bodyclose                    # HTTP response bodies left open
    - contextcheck                 # functions that drop the incoming ctx
    - errorlint                    # == on errors, %v where %w is needed
    - gosec
    - nilerr                       # returns nil after checking err != nil
    - sqlclosecheck
  settings:
    errcheck:
      check-type-assertions: true
  exclusions:
    paths:
      - third_party$
formatters:
  enable:
    - gofumpt
    - goimports

golangci-lint run ./...                  # lint; exit 1 on findings
golangci-lint run --new-from-rev=origin/main   # only issues introduced on this branch
golangci-lint fmt                        # apply the configured formatters
golangci-lint migrate                    # convert a v1 config to v2
golangci-lint linters                    # which linters are enabled with the current config

# Every exported symbol in a package
go doc -all ./pkg/store | grep -E '^func|^type'

# Which packages pull in a module and why
go mod why -m golang.org/x/net

# Build every main package in the repository
go build ./... && go list -f '{{if eq .Name "main"}}{{.ImportPath}}{{end}}' ./...

# Find heap escapes in hot code
go build -gcflags='-m -m' ./pkg/hot 2>&1 | grep 'escapes to heap'

# Test only packages that changed against main
go test $(git diff --name-only origin/main | grep '\.go$' | xargs -r -n1 dirname | sort -u | sed 's|^|./|')

# Fail the build on unformatted files
test -z "$(gofmt -l .)" || { gofmt -l .; exit 1; }

# Race-test a single package repeatedly to catch flakes
go test -race -count=50 -run TestConcurrent ./pkg/queue

# Binary size by symbol
go tool nm -size -sort size ./api | head -20

# What the compiler inlined
go build -gcflags='-m' ./... 2>&1 | grep 'can inline'

# Module versions embedded in a built binary
go version -m ./api | grep dep

# Regenerate code and fail if the result is not committed
go generate ./... && git diff --exit-code

# Every test in the module that is not run in parallel
grep -rL 't.Parallel()' --include='*_test.go' .

# Which of my dependencies have a newer minor or patch release
go list -m -u -f '{{if .Update}}{{.Path}} {{.Version}} -> {{.Update.Version}}{{end}}' all

# Build once, then run the same binary under several inputs
go build -o ./bin/api ./cmd/api && ./bin/api -config dev.yaml

func retry(ctx context.Context, attempts int, fn func() error) error {
    var err error
    for i := 0; i < attempts; i++ {
        if err = fn(); err == nil || errors.Is(err, errPermanent) {
            return err
        }
        delay := time.Duration(1<<i)*200*time.Millisecond + time.Duration(rand.IntN(100))*time.Millisecond
        select {
        case <-time.After(delay):
        case <-ctx.Done():
            return fmt.Errorf("retry: %w (last: %v)", ctx.Err(), err)
        }
    }
    return fmt.Errorf("after %d attempts: %w", attempts, err)
}

g, ctx := errgroup.WithContext(ctx)
g.SetLimit(16)
for _, u := range urls {
    g.Go(func() error { return fetch(ctx, u) })
}
err := g.Wait()

ctx, cancel := context.WithTimeoutCause(ctx, 2*time.Second, errors.New("db lookup budget"))   // Go 1.21+
defer cancel()
row, err := db.QueryRowContext(ctx, q, id)
if err != nil && context.Cause(ctx) != nil {
    return fmt.Errorf("lookup: %w", context.Cause(ctx))   // "db lookup budget" instead of a bare deadline error
}

type Config struct {
    Addr    string
    DBURL   string
    Timeout time.Duration
}

func Load() (Config, error) {
    c := Config{Addr: envOr("ADDR", ":8080"), DBURL: os.Getenv("DATABASE_URL")}
    d, err := time.ParseDuration(envOr("TIMEOUT", "5s"))
    if err != nil { return c, fmt.Errorf("TIMEOUT: %w", err) }
    c.Timeout = d
    if c.DBURL == "" { return c, errors.New("DATABASE_URL is required") }
    return c, nil
}

func envOr(k, def string) string { if v := os.Getenv(k); v != "" { return v }; return def }

client := &http.Client{
    Timeout: 30 * time.Second,
    Transport: &http.Transport{
        DialContext:           (&net.Dialer{Timeout: 3 * time.Second}).DialContext,
        TLSHandshakeTimeout:   5 * time.Second,
        ResponseHeaderTimeout: 10 * time.Second,     // time to first byte of the response
        MaxIdleConnsPerHost:   50,
        IdleConnTimeout:       90 * time.Second,
    },
}

dec := json.NewDecoder(io.LimitReader(resp.Body, 1<<20))   // refuse bodies over 1 MiB
dec.DisallowUnknownFields()
var out Payload
if err := dec.Decode(&out); err != nil {
    return fmt.Errorf("decode %s: %w", resp.Request.URL, err)
}

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()

go func() { _ = srv.ListenAndServe() }()
<-ctx.Done()
stop()                                                     // restore default signal handling: a second Ctrl-C kills
shutdownCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
defer cancel()
if err := srv.Shutdown(shutdownCtx); err != nil {
    log.Error("shutdown", "err", err)                     // in-flight requests exceeded the deadline
}

logger := slog.New(slog.NewJSONHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelInfo, AddSource: true}))
slog.SetDefault(logger)

reqLog := logger.With("request_id", id, "path", r.URL.Path)
reqLog.InfoContext(ctx, "handled", "status", status, "duration", time.Since(start))
reqLog.Error("upstream", "err", err)                      // err renders as its message; wrap in slog.Any for the type

func logging(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        defer func() {
            if p := recover(); p != nil {
                slog.Error("panic", "err", p, "stack", string(debug.Stack()))
                http.Error(w, "internal error", http.StatusInternalServerError)
            }
        }()
        next.ServeHTTP(w, r)
        slog.Info("request", "method", r.Method, "path", r.URL.Path, "ms", time.Since(start).Milliseconds())
    })
}

mux := http.NewServeMux()
mux.HandleFunc("GET /users/{id}", func(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")
    _ = id
})
mux.HandleFunc("POST /users", createUser)
mux.Handle("GET /static/", http.StripPrefix("/static/", http.FileServerFS(static)))

t := time.NewTicker(time.Minute)
defer t.Stop()
for {
    select {
    case <-ctx.Done():
        return
    case <-t.C:
        if err := sweep(ctx); err != nil { slog.Warn("sweep", "err", err) }   // runs serially; a slow sweep skips ticks
    }
}

type fakeStore struct{ users map[int64]*User }

func (f fakeStore) Get(_ context.Context, id int64) (*User, error) {
    u, ok := f.users[id]
    if !ok { return nil, ErrNotFound }
    return u, nil
}

func TestHandler(t *testing.T) {
    h := NewHandler(fakeStore{users: map[int64]*User{1: {Name: "ann"}}})
    for _, tt := range []struct{ path string; want int }{{"/users/1", 200}, {"/users/9", 404}} {
        t.Run(tt.path, func(t *testing.T) {
            req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, tt.path, nil)
            rec := httptest.NewRecorder()
            h.ServeHTTP(rec, req)
            if rec.Code != tt.want { t.Errorf("status = %d, want %d", rec.Code, tt.want) }
        })
    }
}

var update = flag.Bool("update", false, "rewrite golden files")

func TestRender(t *testing.T) {
    got := Render(input)
    golden := filepath.Join("testdata", t.Name()+".golden")
    if *update { os.WriteFile(golden, got, 0o644) }
    want, err := os.ReadFile(golden)
    if err != nil { t.Fatal(err) }
    if !bytes.Equal(got, want) { t.Errorf("output differs from %s; run with -update to accept", golden) }
}

sc := bufio.NewScanner(f)
sc.Buffer(make([]byte, 0, 1024*1024), 1024*1024)   // default token limit is 64 KiB
for sc.Scan() {
    line := sc.Text()
    _ = line
}
if err := sc.Err(); err != nil { return err }       // bufio.ErrTooLong when a line exceeds the buffer

func writeAtomic(path string, data []byte) error {
    tmp, err := os.CreateTemp(filepath.Dir(path), ".tmp-*")
    if err != nil { return err }
    defer os.Remove(tmp.Name())                        // no-op after a successful rename
    if _, err := tmp.Write(data); err != nil { tmp.Close(); return err }
    if err := tmp.Sync(); err != nil { tmp.Close(); return err }
    if err := tmp.Close(); err != nil { return err }
    return os.Rename(tmp.Name(), path)
}

ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
defer cancel()
cmd := exec.CommandContext(ctx, "pg_dump", "--format=custom", dbURL)
cmd.WaitDelay = 5 * time.Second                    // Go 1.20+: grace period before SIGKILL after ctx ends
var stdout, stderr bytes.Buffer
cmd.Stdout, cmd.Stderr = &stdout, &stderr
if err := cmd.Run(); err != nil {
    return fmt.Errorf("pg_dump: %w: %s", err, strings.TrimSpace(stderr.String()))
}

type HTTPError struct {
    Status int
    Err    error
}

func (e *HTTPError) Error() string { return fmt.Sprintf("http %d: %v", e.Status, e.Err) }
func (e *HTTPError) Unwrap() error { return e.Err }

// caller
var he *HTTPError
if errors.As(err, &he) && he.Status == http.StatusTooManyRequests { backoff() }