DEV Community: Prasad Ekke

Profiling a Go Service in Production: pprof in 10 Minutes

Prasad Ekke — Tue, 30 Jun 2026 15:09:51 +0000

Go ships with a profiler built in. No third-party tools, no agents to install, no instrumentation to add upfront. If your service imports net/http/pprof, you can profile it live in production right now — CPU usage, memory allocations, goroutine counts, blocking operations. The data is available over HTTP, readable with standard Go tooling.

Most engineers know pprof exists. Fewer have actually used it under pressure, on a real service, to find a real problem. This post walks through the mechanics — how to enable it, how to collect a profile, how to read a flame graph — and then shows the three classes of problems it catches most often.

Enabling pprof

For an HTTP service, one import is all it takes:

import (
    "log"
    "net/http"

    _ "net/http/pprof" // registers handlers on DefaultServeMux
)

func main() {
    // Your service setup...

    // pprof endpoints are now available on DefaultServeMux
    go func() {
        log.Println(http.ListenAndServe("localhost:6060", nil))
    }()

    // ... rest of main
}

The blank import registers the pprof HTTP handlers automatically. They’re available at:

GET /debug/pprof/ — index of available profiles
GET /debug/pprof/goroutine — all current goroutines
GET /debug/pprof/heap — memory allocations
GET /debug/pprof/profile?seconds=30 — CPU profile (30-second sample)
GET /debug/pprof/block — goroutine blocking events
GET /debug/pprof/mutex — mutex contention

Security note: bind pprof to localhost only, or a private interface. Never expose it on your public port. If your service runs in Kubernetes, use kubectl port-forward to reach it.

For services not using DefaultServeMux, register the handlers explicitly:

mux := http.NewServeMux()
mux.HandleFunc("/debug/pprof/", pprof.Index)
mux.HandleFunc("/debug/pprof/cmdline", pprof.Cmdline)
mux.HandleFunc("/debug/pprof/profile", pprof.Profile)
mux.HandleFunc("/debug/pprof/symbol", pprof.Symbol)
mux.HandleFunc("/debug/pprof/trace", pprof.Trace)

Collecting a CPU profile

With the service running under load (profiling a quiet service tells you nothing useful), collect a 30-second CPU sample:

go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30

This downloads the profile and drops you into an interactive shell. Or skip the shell and go straight to a flame graph:

# Collect the profile to a file
curl -o cpu.prof "http://localhost:6060/debug/pprof/profile?seconds=30"

# Open the flame graph in a browser
go tool pprof -http=:8080 cpu.prof

The -http flag serves a web UI with multiple views. The flame graph is the most useful starting point.

Reading a flame graph

A flame graph shows where your program spends time. Each horizontal bar is a function. Width represents time — wider means more CPU. The vertical axis is the call stack — functions lower down called the ones above them.

|          processJob          |     |  encode  |
|       fetchFromDB      |other|
|         sql.Query            |
|          net.Read            |

You’re looking for wide bars near the top — those are the functions consuming the most CPU. If json.Marshal is unexpectedly wide, you’re spending a lot of time serializing. If runtime.mallocgc is wide, you’re allocating heavily. If sync.Mutex.Lock is wide, you have lock contention.

The three most common findings in worker pool services:

Problem 1: Excessive allocations

Symptom: runtime.mallocgc is prominent in the CPU profile. Heap profile shows high allocation rate with short-lived objects.

# Collect a heap profile
curl -o heap.prof "http://localhost:6060/debug/pprof/heap"
go tool pprof -http=:8080 heap.prof

In the heap profile, switch to “alloc_objects” or “alloc_space” view (not “inuse” — that shows what’s live, not what’s being allocated). Look for hot allocation sites.

Common cause in worker pools: allocating a new buffer or slice on every job iteration.

// ❌ Allocates a new byte slice for every job
func processJob(ctx context.Context, job Job) error {
    buf := make([]byte, 4096)
    // use buf...
    return nil
}

// ✅ Reuse buffers with sync.Pool
var bufPool = sync.Pool{
    New: func() interface{} {
        b := make([]byte, 4096)
        return &b
    },
}

func processJob(ctx context.Context, job Job) error {
    bufPtr := bufPool.Get().(*[]byte)
    defer bufPool.Put(bufPtr)
    buf := *bufPtr
    // use buf...
    return nil
}

sync.Pool maintains a pool of reusable objects. Objects not retrieved before the next GC cycle are collected, so it doesn’t prevent garbage collection — it reduces the rate of allocation, which reduces GC pressure.

Problem 2: Goroutine leak

Symptom: goroutine count grows over time and never decreases.

# Check current goroutine count
curl "http://localhost:6060/debug/pprof/goroutine?debug=1"

The debug=1 parameter returns a text listing of all goroutines with stack traces. Look for hundreds or thousands of goroutines all blocked at the same location — that’s your leak.

goroutine 1042 [chan receive, 3 minutes]:
main.worker()
    /app/worker.go:45 +0x68
created by main.startWorkers
    /app/pool.go:23 +0x4c

goroutine 1043 [chan receive, 3 minutes]:
...
(997 more like this)

A thousand goroutines blocked on chan receive for 3 minutes means the jobs channel was never closed. The fix is covered in the concurrency mistakes post in this series — the producer must own close(jobs) via defer.

You can also check the goroutine count programmatically:

// In your health check endpoint
func healthHandler(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintf(w, "goroutines: %d\n", runtime.NumGoroutine())
}

If that number grows continuously over hours of runtime and never stabilizes, you have a leak.

Problem 3: Lock contention

Symptom: throughput is lower than CPU utilization suggests it should be. Workers are running but not making progress.

Mutex profiling is off by default because it has overhead. Enable it from inside the process only while investigating contention:

import "runtime"

runtime.SetMutexProfileFraction(1)
defer runtime.SetMutexProfileFraction(0)

Then collect the mutex profile:

curl -o mutex.prof "http://localhost:6060/debug/pprof/mutex"
go tool pprof -http=:8080 mutex.prof

Common cause in worker pools: a shared results map protected by a single mutex, written to by all workers simultaneously.

// ❌ All workers contend on one mutex
type ResultCollector struct {
    mu      sync.Mutex
    results map[string]Result
}

func (c *ResultCollector) Add(id string, result Result) {
    c.mu.Lock()
    c.results[id] = result
    c.mu.Unlock()
}

Solutions, in order of preference:

// ✅ Option 1: Use a results channel instead of shared state
results := make(chan Result, 1000)

// Workers send to channel (no lock)
go func() {
    for job := range jobs {
        result := processJob(ctx, job)
        results <- result
    }
}()

// Single collector goroutine reads from channel (no contention)
go func() {
    for result := range results {
        collected[result.ID] = result
    }
}()

// ✅ Option 2: sync.Map for concurrent read-heavy workloads
var results sync.Map
results.Store(id, result)
val, ok := results.Load(id)

The channel approach is idiomatic Go — share memory by communicating rather than communicating by sharing memory. The sync.Map approach is better when you need random access to results across goroutines.

A quick reference for which profile to use

High CPU, unclear where — CPU profile: pprof .../profile?seconds=30.

Memory growing over time — heap profile (inuse_space): pprof .../heap.

High GC pressure — heap profile (alloc_objects): pprof .../heap.

Goroutine count growing — goroutine profile: pprof .../goroutine?debug=1.

Low throughput despite low CPU — mutex or block profile: pprof .../mutex or .../block. Enable mutex profiling with runtime.SetMutexProfileFraction; enable block profiling with runtime.SetBlockProfileRate.

One workflow for production incidents

When something is wrong and you need to understand it quickly:

# 1. Check goroutine count (cheap, immediate)
curl localhost:6060/debug/pprof/goroutine?debug=2 | head -50

# 2. If CPU is high, get a 30s CPU profile
curl -o cpu.prof localhost:6060/debug/pprof/profile?seconds=30

# 3. If memory is growing, get a heap snapshot
curl -o heap.prof localhost:6060/debug/pprof/heap

# 4. Open whichever profile is relevant
go tool pprof -http=:8080 cpu.prof

The whole process takes under 5 minutes. You don’t need to reproduce the problem locally, you don’t need to redeploy with extra instrumentation, and you don’t need to restart the service. The profiler runs against the live process.

Summary

pprof is built into Go’s standard library and available with a single import. The three problems it catches most reliably in worker pool services are excessive allocations (fix: sync.Pool), goroutine leaks (fix: close channels, use context), and mutex contention (fix: channel-based result collection or sync.Map). The flame graph view in go tool pprof -http is the fastest path from profile to finding.

The only prerequisite is running the service under realistic load when you collect the profile. A profile from a quiet service tells you where your code could spend time, not where it does.

Previous in this series: context.Context Is Not Optional
Next: Container-aware resource management in Go.

context.Context Is Not Optional: A Practical Guide to Cancellation in Go Services

Prasad Ekke — Tue, 23 Jun 2026 12:47:35 +0000

Every Go service that does I/O — database calls, HTTP requests, queue polling, file reads — should be passing a context.Context through every layer. In practice, a large number of codebases treat context.Context as optional plumbing that gets added later, or as something only the HTTP handler layer needs to worry about.

That’s the mistake. By the time you realize you need cancellation deep in a worker pool, retrofitting it is painful. This post shows what context propagation looks like in a real worker pool, what the failure modes are when you skip it, and how to do it correctly from the start.

What context.Context actually does

A context.Context carries three things:

A cancellation signal — a channel that’s closed when the work should stop
A deadline or timeout — an absolute time after which the context is automatically cancelled
Key-value pairs — request-scoped values like trace IDs (use sparingly)

When a context is cancelled, any blocking operation that’s watching that context should stop and return an error. The context propagates down the call stack — a parent context cancelled cancels all children. It never propagates up.

The critical point: the context has to be passed all the way down to the code that actually blocks. Holding it at the HTTP handler layer and never passing it to your database call means cancellation never reaches the work.

What happens without context

Here is a worker pool that ignores context:

func runWorkers(jobs <-chan Job) {
    var wg sync.WaitGroup
    for i := 0; i < 10; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for job := range jobs {
                processJob(job) // no context
            }
        }()
    }
    wg.Wait()
}

func processJob(job Job) error {
    result, err := fetchFromDatabase(job.ID) // no context
    if err != nil {
        return err
    }
    return sendToDownstream(result) // no context
}

Now consider what happens when:

The calling service shuts down
A client disconnects
A deadline passes
An operator sends SIGTERM

The workers keep running. fetchFromDatabase keeps waiting. sendToDownstream keeps trying. The process can’t exit cleanly because goroutines are blocked on operations that have no way of knowing they should stop.

In the best case, the process takes 30 seconds to shut down waiting for goroutines to unblock naturally. In the worst case, it never terminates and has to be killed, potentially leaving in-flight work in an inconsistent state.

The correct structure: context flows in, errors flow out

The pattern is simple. Every function that does I/O or blocks takes a context as its first parameter:

func runWorkers(ctx context.Context, jobs <-chan Job) error {
    var wg sync.WaitGroup
    errs := make(chan error, 10)

    for i := 0; i < 10; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for {
                select {
                case <-ctx.Done():
                    return // context cancelled, stop cleanly
                case job, ok := <-jobs:
                    if !ok {
                        return // channel closed, no more jobs
                    }
                    if err := processJob(ctx, job); err != nil {
                        select {
                        case errs <- err:
                        default:
                        }
                    }
                }
            }
        }()
    }

    wg.Wait()
    close(errs)

    // Return first error if any
    return <-errs
}

func processJob(ctx context.Context, job Job) error {
    result, err := fetchFromDatabase(ctx, job.ID)
    if err != nil {
        return err
    }
    return sendToDownstream(ctx, result)
}

Now when the context is cancelled — whether by timeout, operator signal, or parent cancellation — each worker’s select unblocks on ctx.Done() and returns cleanly. fetchFromDatabase and sendToDownstream propagate the context to their underlying I/O calls (database drivers, HTTP clients), which respect it.

Wiring context to OS signals for clean shutdown

The context that flows into your worker pool should ultimately be rooted at main, wired to OS signals:

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

    jobs := make(chan Job, 100)

    // Producer
    go func() {
        defer close(jobs)
        if err := loadJobs(ctx, jobs); err != nil {
            log.Printf("producer stopped: %v", err)
        }
    }()

    // Workers
    if err := runWorkers(ctx, jobs); err != nil {
        log.Printf("workers stopped with error: %v", err)
        os.Exit(1)
    }

    log.Println("shutdown complete")
}

signal.NotifyContext (added in Go 1.16) returns a context that’s cancelled when SIGINT or SIGTERM arrives. That cancellation propagates through loadJobs and runWorkers automatically. When the signal arrives, the producer stops generating new jobs, in-flight I/O observes cancellation through the propagated context, workers exit, and the process shuts down cleanly.

Timeouts: per-job vs. pool-wide

There are two distinct timeout requirements in a worker pool, and they need separate contexts:

Pool-wide timeout: how long the entire batch is allowed to run. Use context.WithTimeout or context.WithDeadline on the root context.

Per-job timeout: how long a single job is allowed to take. Use a derived context inside the worker loop.

func runWorkers(ctx context.Context, jobs <-chan Job) error {
    // ctx already carries the pool-wide deadline from the caller

    var wg sync.WaitGroup
    for i := 0; i < 10; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for {
                select {
                case <-ctx.Done():
                    return
                case job, ok := <-jobs:
                    if !ok {
                        return
                    }

                    // Per-job timeout: 30 seconds max per job
                    jobCtx, cancel := context.WithTimeout(ctx, 30*time.Second)
                    err := processJob(jobCtx, job)
                    cancel() // always call cancel to release resources

                    if err != nil {
                        log.Printf("job %s failed: %v", job.ID, err)
                    }
                }
            }
        }()
    }

    wg.Wait()
    return ctx.Err()
}

Two things to note. First, jobCtx is derived from ctx — if the pool-wide context is cancelled, the per-job context is also cancelled automatically. The hierarchy works in your favor. Second, cancel() is called immediately after processJob returns, not deferred. Deferring a context cancel inside a loop means you accumulate uncancelled contexts until the goroutine exits. Call cancel immediately after the work is done.

Checking context in CPU-bound work

The ctx.Done() pattern works for I/O that blocks, because the underlying library propagates the context. But what about CPU-bound work — a job that does heavy computation without any I/O?

func processJob(ctx context.Context, job Job) error {
    chunks := split(job.Data)

    for i, chunk := range chunks {
        // Check context periodically in long-running CPU work
        if i%100 == 0 {
            select {
            case <-ctx.Done():
                return ctx.Err()
            default:
            }
        }

        if err := processChunk(chunk); err != nil {
            return err
        }
    }

    return nil
}

The select with a default branch is non-blocking — it checks whether the context is done and moves on immediately if not. Checking every 100 iterations (or every N milliseconds using a ticker) is a reasonable balance between responsiveness and overhead.

The three rules

1. Context is always the first parameter.

func doWork(ctx context.Context, ...) error

Not a struct field, not a global, not injected via closure. First parameter, every time. This is a Go convention strong enough to be in the standard library style guide.

2. Never store context in a struct.

// ❌
type Worker struct {
    ctx context.Context
}

// ✅
func (w *Worker) Process(ctx context.Context, job Job) error

Contexts are request-scoped. A struct outlives any single request. Storing context in a struct means you’re using the wrong context for future requests, or holding a cancelled context longer than you should.

3. Always call cancel.

ctx, cancel := context.WithTimeout(parent, 5*time.Second)
defer cancel() // even if the timeout fires first

If the timeout fires before you call cancel, calling cancel is a no-op. But if the work finishes before the timeout, calling cancel releases the timer resources immediately rather than waiting for the timeout to expire. It costs nothing and prevents a resource leak.

Summary

Clean shutdown on SIGTERM — signal.NotifyContext at main, propagate down.

Stop workers on cancellation — select { case <-ctx.Done(): return } in the worker loop.

Per-job timeout — context.WithTimeout(ctx, duration) inside the loop, cancel immediately after.

CPU-bound work — periodic select { case <-ctx.Done(): return ctx.Err(); default: }.

Function signatures — ctx context.Context is always the first parameter.

Context propagation is not boilerplate. It is the mechanism that lets your service behave correctly under pressure — when deadlines pass, when clients disconnect, when operators need to restart the service without waiting for goroutines to unblock naturally. The cost of adding it from the start is a few extra parameters. The cost of retrofitting it later is much higher.

Previous in this series: Three Go Concurrency Mistakes I See in Almost Every Worker Pool
Next: Profiling a Go service in production with pprof.

Three Go Concurrency Mistakes I See in Almost Every Worker Pool

Prasad Ekke — Tue, 16 Jun 2026 12:42:10 +0000

Go makes concurrency feel easy. Goroutines are cheap, channels are built into the language, and the standard library gives you everything you need to spin up a worker pool in under 30 lines. That ease is genuinely valuable — but it also means bugs sneak in quietly. The program compiles, the tests pass, and the mistake only surfaces under load or after hours of runtime.

After working on high-throughput backend systems in Go, I keep seeing the same three mistakes. None of them are obscure. All of them are fixable in minutes once you know what to look for.

Mistake 1: Goroutine leaks from channels that never close

Here is a worker pool that looks completely reasonable:

func startWorkers(jobs <-chan Job) {
    for i := 0; i < 10; i++ {
        go func() {
            for job := range jobs {
                process(job)
            }
        }()
    }
}

Each worker ranges over the jobs channel and processes whatever comes in. Clean, idiomatic Go. The problem: if jobs is never closed, every one of those goroutines blocks forever.

for range on a channel blocks until the channel is closed or a value arrives. If the producer stops sending but never calls close(jobs), your 10 workers sit there permanently — holding memory, holding stack space, invisible to your metrics unless you’re explicitly tracking goroutine count.

In a long-running service, this compounds. Every time you restart the worker pool (say, on a config reload or a new batch) without draining the old one, you accumulate leaked goroutines.

The fix: always close the jobs channel when the producer is done, and own that responsibility clearly.

func runBatch(jobList []Job) {
    jobs := make(chan Job, len(jobList))

    // Producer owns the channel and closes it when done
    go func() {
        defer close(jobs) // guaranteed even if we panic
        for _, job := range jobList {
            jobs <- job
        }
    }()

    var wg sync.WaitGroup
    for i := 0; i < 10; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for job := range jobs {
                process(job)
            }
        }()
    }

    wg.Wait()
}

Two things worth noting here. First, defer close(jobs) in the producer goroutine means the channel closes even if the producer exits early or panics while sending jobs. Second, the sync.WaitGroup gives us a clean join point — wg.Wait() blocks until every worker has finished draining.

Quick diagnostic: add runtime.NumGoroutine() to your health endpoint. If that number grows over the lifetime of your service and never comes back down, you have a leak.

Mistake 2: WaitGroup counter manipulation in the wrong place

sync.WaitGroup has one sharp edge: wg.Add must be called before the goroutine starts, not inside it.

This version has a race condition:

var wg sync.WaitGroup

for _, job := range jobs {
    go func(j Job) {
        wg.Add(1)        // ❌ too late
        defer wg.Done()
        process(j)
    }(job)
}

wg.Wait()

If the loop spawns goroutines quickly and the scheduler runs slowly, wg.Wait() can be reached before any goroutine has called wg.Add(1). The counter is zero, Wait() returns immediately, and your main function exits while workers are still running — silently dropping work.

This is a classic race condition. It won’t always reproduce, which makes it worse.

The fix is simple: call wg.Add in the loop body, before launching the goroutine.

var wg sync.WaitGroup

for _, job := range jobs {
    wg.Add(1) // ✅ happens-before the goroutine starts
    go func(j Job) {
        defer wg.Done()
        process(j)
    }(job)
}

wg.Wait()

Now the counter increment is guaranteed to happen before wg.Wait() could possibly observe a zero. The goroutine carries the Done() responsibility via defer, so it fires even on panic.

A secondary pattern worth knowing: if you know the count upfront (say, you’re launching exactly N workers), call wg.Add(N) once before the loop. That’s even cleaner and harder to get wrong.

const numWorkers = 10
var wg sync.WaitGroup
wg.Add(numWorkers) // add all at once

for i := 0; i < numWorkers; i++ {
    go func() {
        defer wg.Done()
        for job := range jobs {
            process(job)
        }
    }()
}

wg.Wait()

Mistake 3: Unidirectional channel types ignored on function boundaries

Go lets you declare channels as send-only (chan<- Job) or receive-only (<-chan Job). Most codebases I’ve seen don’t use this consistently — functions just accept chan Job everywhere. This is technically fine, but it loses something real: the compiler can no longer tell you when your data flow is wrong.

Here is a worker pool where the direction confusion causes a real bug:

func spawnWorkers(jobs chan Job, results chan Result) {
    for i := 0; i < 10; i++ {
        go func() {
            for job := range jobs {
                result := process(job)
                jobs <- result.nextJob  // ❌ worker feeding back into the input channel
                results <- result
            }
        }()
    }
}

A worker accidentally wrote back into jobs instead of results. With bidirectional channels, this compiles without complaint. With directional types, it fails at compile time:

func spawnWorkers(jobs <-chan Job, results chan<- Result) {
    for i := 0; i < 10; i++ {
        go func() {
            for job := range jobs {
                result := process(job)
                jobs <- result.nextJob  // ✅ compile error: cannot send to receive-only channel
                results <- result
            }
        }()
    }
}

The directional types act as documentation that’s enforced by the compiler. The producer only sees chan<- Job. The consumer only sees <-chan Job. Neither can accidentally do the wrong thing.

A complete worker pool using this pattern correctly:

func produce(jobs chan<- Job, jobList []Job) {
    defer close(jobs)
    for _, job := range jobList {
        jobs <- job
    }
}

func consume(jobs <-chan Job, results chan<- Result, wg *sync.WaitGroup) {
    defer wg.Done()
    for job := range jobs {
        results <- process(job)
    }
}

func run(jobList []Job) []Result {
    jobs := make(chan Job, 100)
    results := make(chan Result, 100)

    var wg sync.WaitGroup
    for i := 0; i < 10; i++ {
        wg.Add(1)
        go consume(jobs, results, &wg)
    }

    go produce(jobs, jobList)

    // Close results once all workers are done
    go func() {
        wg.Wait()
        close(results)
    }()

    var out []Result
    for result := range results {
        out = append(out, result)
    }
    return out
}

Every function now only sees what it’s supposed to see. The compiler enforces the data flow. And the pattern is easy to read: produce feeds in, consume drains, the closer goroutine shuts down results when all workers finish.

Summary

Channel never closed — What goes wrong: goroutines leak, memory grows. Fix: the producer owns close(ch), always via defer.

wg.Add inside the goroutine — What goes wrong: work silently dropped, races at shutdown. Fix: call wg.Add before go func().

Bidirectional channels everywhere — What goes wrong: wrong-direction sends compile silently. Fix: use chan<- and <-chan at function boundaries.

None of these require clever solutions. They require habit. Once you internalize that the producer owns close, that Add precedes launch, and that channel direction is free documentation, they stop appearing.

Go 1.25’s go vet includes a WaitGroup analyzer that flags mistake 2 when Add is called from inside a goroutine. On older Go versions, test the behavior directly by asserting that all launched work completes; go test -race is not reliable for this case because WaitGroup uses internal synchronization. For mistake 1, runtime.NumGoroutine() in a test that runs your pool repeatedly and checks for growth is the simplest approach. Mistake 3 is pure compiler enforcement — no test needed once the types are right.

If this was useful, the next post in this series covers context.Context propagation in worker pools — specifically what happens when you need to cancel in-flight jobs cleanly without leaking the workers themselves.

Go Interfaces: Why Less Is Almost Always More

Prasad Ekke — Mon, 08 Jun 2026 16:28:10 +0000

Go Interfaces: Why Less Is Almost Always More

If you’re coming to Go from Java or C++, interfaces look familiar at first glance. You define a set of methods, types implement them, you write code against the interface. Same idea, right?

Not quite. Go interfaces have one property that changes everything about how you should design them: a type implements an interface implicitly, without declaring it. There’s no implements keyword. If your type has the right methods, it satisfies the interface — whether it knows about the interface or not.

That single property pushes you toward a design philosophy that trips up most engineers coming from other languages: interfaces should be small, and they should be defined by the consumer, not the producer.

What the standard library is trying to tell you

Look at the most-used interfaces in Go’s standard library:

type Reader interface {
    Read(p []byte) (n int, err error)
}

type Writer interface {
    Write(p []byte) (n int, err error)
}

type Closer interface {
    Close() error
}

One method each. That’s not laziness — that’s a deliberate design decision. Because interfaces are satisfied implicitly, a one-method interface can be satisfied by an enormous range of types: files, network connections, buffers, custom types you haven’t written yet. The smaller the interface, the more things satisfy it, the more reusable your code becomes.

io.ReadWriter combines two:

type ReadWriter interface {
    Reader
    Writer
}

And io.ReadWriteCloser combines three. Notice that the standard library builds up complexity by composing small interfaces, not by defining large ones upfront.

This is the pattern worth internalizing.

The fat interface trap

Here is how engineers from Java or C++ backgrounds tend to define interfaces in Go. Say you’re building a job processing system and you want to abstract over different job stores:

// ❌ The fat interface
type JobStore interface {
    AddJob(job Job) error
    GetJob(id string) (Job, error)
    DeleteJob(id string) error
    ListJobs(filter Filter) ([]Job, error)
    UpdateJob(job Job) error
    CountJobs(filter Filter) (int, error)
    MarkComplete(id string) error
    MarkFailed(id string, reason error) error
}

This feels complete. It covers everything the store can do. But now ask: how many types in your codebase will ever implement all 8 methods? Probably one — your real database implementation. And your test mock has to implement all 8 even if the function under test only calls GetJob.

// Every test mock must implement all 8 methods even if irrelevant
type mockStore struct{}

func (m *mockStore) AddJob(job Job) error                         { return nil }
func (m *mockStore) GetJob(id string) (Job, error)               { return Job{}, nil }
func (m *mockStore) DeleteJob(id string) error                   { return nil }
func (m *mockStore) ListJobs(filter Filter) ([]Job, error)       { return nil, nil }
func (m *mockStore) UpdateJob(job Job) error                     { return nil }
func (m *mockStore) CountJobs(filter Filter) (int, error)        { return 0, nil }
func (m *mockStore) MarkComplete(id string) error                { return nil }
func (m *mockStore) MarkFailed(id string, reason error) error    { return nil }

Eight methods of boilerplate for a test that calls one. And if you add a 9th method to the interface, every mock in the entire codebase breaks.

The Go way: consumer-defined, minimal interfaces

Instead of defining one big interface at the store level, define small interfaces at each use site — the function that actually needs the behavior.

// ✅ Each function declares exactly what it needs

type JobGetter interface {
    GetJob(id string) (Job, error)
}

type JobAdder interface {
    AddJob(job Job) error
}

type JobCompleter interface {
    MarkComplete(id string) error
    MarkFailed(id string, reason error) error
}

func processJob(id string, store JobGetter) error {
    job, err := store.GetJob(id)
    if err != nil {
        return err
    }
    // process...
    return nil
}

func submitJob(job Job, store JobAdder) error {
    return store.AddJob(job)
}

Now processJob only depends on JobGetter. Its test mock is one method:

type mockGetter struct {
    job Job
    err error
}

func (m *mockGetter) GetJob(id string) (Job, error) {
    return m.job, m.err
}

Your real PostgresJobStore still implements all 8 methods. It satisfies every one of these small interfaces automatically, without any change, because Go interfaces are implicit. The store doesn’t know or care about JobGetter or JobAdder — it just has the methods, and that’s enough.

Accepting interfaces, returning structs

There’s a corollary rule in Go that follows directly from this: accept interfaces, return concrete types.

// ✅ Accept an interface — flexible, testable
func drainQueue(queue <-chan Job, store JobAdder) error {
    for job := range queue {
        if err := store.AddJob(job); err != nil {
            return err
        }
    }
    return nil
}

// ❌ Return an interface — forces callers to type-assert, hides information
func newJobStore(cfg Config) JobStore {
    return &PostgresJobStore{...}
}

// ✅ Return a concrete type — callers get the full picture
func newJobStore(cfg Config) *PostgresJobStore {
    return &PostgresJobStore{...}
}

When you return a concrete type, callers can always choose to assign it to a narrower interface themselves. When you return a fat interface, you’ve already made that decision for them, and they’re stuck with it.

The one exception: returning error is an interface, and that’s intentional — it lets you return any error type, including custom ones. But error is a one-method interface, so the rule still holds in spirit.

Composing small interfaces when you need more

Sometimes a function genuinely needs multiple behaviors. Rather than reaching for a fat interface, compose:

type JobProcessor interface {
    JobGetter
    JobCompleter
}

func runWorker(id string, store JobProcessor) error {
    job, err := store.GetJob(id)
    if err != nil {
        return err
    }

    if err := doWork(job); err != nil {
        return store.MarkFailed(id, err)
    }

    return store.MarkComplete(id)
}

JobProcessor is defined at the call site, composed from two smaller interfaces, and PostgresJobStore satisfies it without modification. The test mock now only needs three methods.

Summary

Interface size — Avoid: 8-method interfaces defined upfront. Prefer: 1–3 method interfaces defined at the use site.

Where to define — Avoid: the producer side (the package that has the struct). Prefer: the consumer side (the package that calls the function).

What to return — Avoid: interfaces from constructors. Prefer: concrete types from constructors.

Complexity — Avoid: a single large interface. Prefer: composition of small interfaces.

Go’s implicit interface satisfaction is not just a syntactic convenience — it’s the mechanism that makes all of this work without coordination between packages. A type in one package can satisfy an interface defined in a completely different package, written years later, with no coupling between them.

The standard library’s one-method interfaces aren’t minimal because Go is simple. They’re minimal because the designers understood what implicit satisfaction makes possible.

Next in this series: Three Go concurrency mistakes I see in almost every worker pool.