Go Expert
Clear is better than clever. Handle every error explicitly, make the zero value useful, and give every goroutine an owner and an exit. "Share memory by communicating," but a Mutex is fine for protecting state.
When to Use
- Writing or refactoring Go.
- Designing concurrent code (goroutines, channels,
context, select).
- Data races, deadlocks, goroutine leaks, or context propagation bugs.
- Package layout, interfaces, and standard-library usage.
When NOT to Use
- Other languages → the relevant language skill.
- System-level architecture →
software-architect.
Core Principles
1. Errors are explicit values
- Check immediately:
if err != nil { return fmt.Errorf("doing X: %w", err) }. Wrap with %w to preserve the chain; inspect with errors.Is (sentinel) / errors.As (typed).
- Add context at each layer ("opening config: …") but don't double-log the same error. Return errors up; log once at the boundary.
- Panic only for truly unrecoverable programmer errors, never for normal control flow.
2. Interfaces & types
- Accept interfaces, return concrete types. Keep interfaces small (often one method) and define them in the consumer package, not the producer.
- Make the zero value useful (
sync.Mutex, bytes.Buffer work unboxed). Use defer for cleanup (close/unlock) right after acquisition.
3. Concurrency with ownership
- Every goroutine needs a clear lifetime and exit path — leaks are silent. Use
sync.WaitGroup or errgroup to wait, and bound concurrency (errgroup.SetLimit, worker pool, semaphore).
context.Context is the first parameter for anything cancelable/IO-bound; honor ctx.Done(). Never store a Context in a struct.
- Channels for handoff/signaling;
Mutex for protecting shared state. Close a channel from the sender, once. Prefer select with ctx for cancelable waits.
4. Tooling & structure
gofmt (non-negotiable), go vet, golangci-lint. Always test concurrent code with -race.
- Organize by capability; keep private code under
internal/. Avoid premature interfaces and needless abstraction.
Common Mistakes
- Loop variable capture in goroutines/closures — historically
for i, v := range needed i, v := i, v; fixed in Go 1.22+, but know your version.
- Ignoring errors (
_ = f()) or only logging without returning.
- Goroutine leak: a goroutine blocked on a channel/
ctx that never fires — always provide cancellation.
WaitGroup.Add inside the goroutine → race; call Add before go.
- Mutating a map concurrently → fatal race; guard with
Mutex or use sync.Map for the right pattern.
- Returning an interface holding a nil pointer →
err != nil is true unexpectedly (typed-nil trap).
- Unbounded goroutine spawning per request → resource exhaustion.
Examples
Bounded concurrency with errgroup + context
func fetchAll(ctx context.Context, urls []string) ([]string, error) {
g, ctx := errgroup.WithContext(ctx)
g.SetLimit(10) // cap concurrency
out := make([]string, len(urls))
for i, u := range urls { // Go 1.22+: no manual capture needed
i, u := i, u
g.Go(func() error {
req, _ := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
resp, err := http.DefaultClient.Do(req)
if err != nil {
return fmt.Errorf("get %s: %w", u, err)
}
defer resp.Body.Close()
b, err := io.ReadAll(resp.Body)
out[i] = string(b)
return err
})
}
return out, g.Wait() // first error cancels the rest via ctx
}
Sentinel error inspection
if errors.Is(err, sql.ErrNoRows) { return nil, ErrNotFound }
See Also
performance-expert — pprof, escape analysis, allocation reduction.
testing-expert — table-driven tests and -race.
docker-expert — tiny static images (FROM scratch/distroless).
rust-expert — alternative ownership-based concurrency model.
1---2name: go-expert3description: "Expert idiomatic Go: concurrency, interfaces, error handling, and the standard library. Trigger keywords: Go, golang, goroutine, channel, context, select, interface, error wrapping, errors.Is, defer, sync, Mutex, WaitGroup, errgroup, race, pprof. Use for writing/refactoring Go, designing concurrency, or fixing races, leaks, and deadlocks."4metadata:5 source: https://skillmd.com/skills/miaoge-ge/go-expert6---78# Go Expert910> Clear is better than clever. Handle every error explicitly, make the zero value useful, and give every goroutine an owner and an exit. "Share memory by communicating," but a `Mutex` is fine for protecting state.1112## When to Use13- Writing or refactoring Go.14- Designing concurrent code (goroutines, channels, `context`, `select`).15- Data races, deadlocks, goroutine leaks, or context propagation bugs.16- Package layout, interfaces, and standard-library usage.1718## When NOT to Use19- Other languages → the relevant language skill.20- System-level architecture → `software-architect`.2122## Core Principles2324### 1. Errors are explicit values25- Check immediately: `if err != nil { return fmt.Errorf("doing X: %w", err) }`. Wrap with `%w` to preserve the chain; inspect with `errors.Is` (sentinel) / `errors.As` (typed).26- Add context at each layer ("opening config: …") but don't double-log the same error. Return errors up; log once at the boundary.27- Panic only for truly unrecoverable programmer errors, never for normal control flow.2829### 2. Interfaces & types30- **Accept interfaces, return concrete types.** Keep interfaces small (often one method) and define them in the **consumer** package, not the producer.31- Make the **zero value useful** (`sync.Mutex`, `bytes.Buffer` work unboxed). Use `defer` for cleanup (close/unlock) right after acquisition.3233### 3. Concurrency with ownership34- Every goroutine needs a clear lifetime and exit path — leaks are silent. Use `sync.WaitGroup` or `errgroup` to wait, and **bound** concurrency (`errgroup.SetLimit`, worker pool, semaphore).35- `context.Context` is the first parameter for anything cancelable/IO-bound; honor `ctx.Done()`. Never store a Context in a struct.36- Channels for handoff/signaling; `Mutex` for protecting shared state. Close a channel from the **sender**, once. Prefer `select` with `ctx` for cancelable waits.3738### 4. Tooling & structure39- `gofmt` (non-negotiable), `go vet`, `golangci-lint`. **Always test concurrent code with `-race`.**40- Organize by capability; keep private code under `internal/`. Avoid premature interfaces and needless abstraction.4142## Common Mistakes43- **Loop variable capture** in goroutines/closures — historically `for i, v := range` needed `i, v := i, v`; fixed in Go 1.22+, but know your version.44- **Ignoring errors** (`_ = f()`) or only logging without returning.45- **Goroutine leak**: a goroutine blocked on a channel/`ctx` that never fires — always provide cancellation.46- **`WaitGroup.Add` inside the goroutine** → race; call `Add` before `go`.47- **Mutating a map concurrently** → fatal race; guard with `Mutex` or use `sync.Map` for the right pattern.48- **Returning an interface holding a nil pointer** → `err != nil` is true unexpectedly (typed-nil trap).49- **Unbounded goroutine spawning** per request → resource exhaustion.5051## Examples5253**Bounded concurrency with errgroup + context**54```go55func fetchAll(ctx context.Context, urls []string) ([]string, error) {56 g, ctx := errgroup.WithContext(ctx)57 g.SetLimit(10) // cap concurrency58 out := make([]string, len(urls))59 for i, u := range urls { // Go 1.22+: no manual capture needed60 i, u := i, u61 g.Go(func() error {62 req, _ := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)63 resp, err := http.DefaultClient.Do(req)64 if err != nil {65 return fmt.Errorf("get %s: %w", u, err)66 }67 defer resp.Body.Close()68 b, err := io.ReadAll(resp.Body)69 out[i] = string(b)70 return err71 })72 }73 return out, g.Wait() // first error cancels the rest via ctx74}75```7677**Sentinel error inspection**78```go79if errors.Is(err, sql.ErrNoRows) { return nil, ErrNotFound }80```8182## See Also83- `performance-expert` — `pprof`, escape analysis, allocation reduction.84- `testing-expert` — table-driven tests and `-race`.85- `docker-expert` — tiny static images (`FROM scratch`/distroless).86- `rust-expert` — alternative ownership-based concurrency model.