etcd is a distributed key-value store where the server and client communicate over gRPC. But if you’ve only ever used clientv3 and never peeked into the internals, you wouldn’t know that. You call resp, err := client.Put(ctx, "key", "value") and get back a *PutResponse. It feels like a regular Go library. The fact that gRPC and protobuf are involved is an implementation detail that the client wrapper keeps away from you.

I’ve been building a few gRPC services at work lately, and I keep running into the same question: what API do the users of my client library see? The server ships as a binary. The client ships as a Go package that other teams go get. If I hand them the raw generated gRPC stubs, they have to import my protobuf types, manage gRPC connections, configure TLS, and parse codes.NotFound from google.golang.org/grpc/status. That’s a lot of protocol plumbing for someone who just wants to consume my service.

This post walks through wrapping a generated gRPC client behind a higher level Go API, following the same pattern etcd uses. The idea is to give the user a wrapper client that abstracts out the generated client.

I’ll use a small in-memory KV store as the running example.

Layout

kv/
├── api/
│   ├── kv.proto           # service definition
│   ├── kv.pb.go           # generated message types
│   └── kv_grpc.pb.go      # generated client and server stubs
├── client/
│   └── client.go          # the wrapper (what users import)
├── server/
│   └── main.go            # the server binary
└── go.mod

api/ holds the proto and generated code. server/ is a binary you deploy. client/ is the library you ship. Other teams add it to their go.mod and never touch proto types directly.

Defining the service

The KV store has three RPCs: put, get, and delete.

// api/kv.proto
syntax = "proto3";
package kvpb;
option go_package = "example.com/kv/api";

service KV {
  rpc Put(PutRequest) returns (PutResponse);
  rpc Get(GetRequest) returns (GetResponse);
  rpc Delete(DeleteRequest) returns (DeleteResponse);
}

message PutRequest    { string key = 1; bytes value = 2; }
message PutResponse   {}
message GetRequest    { string key = 1; }
message GetResponse   { bytes value = 1; optional bool found = 2; }
message DeleteRequest { string key = 1; }
message DeleteResponse {}

GetResponse uses optional bool found because proto3 normally can’t distinguish “field is zero” from “field was never set.” The optional keyword generates a pointer in Go, which lets callers tell a missing key apart from an empty value.

Running protoc on this generates a client interface and a server stub. The client side looks like this:

// api/kv_grpc.pb.go (generated)
type KVClient interface {
    Put(ctx context.Context, in *PutRequest,
        opts ...grpc.CallOption) (*PutResponse, error)
    Get(ctx context.Context, in *GetRequest,
        opts ...grpc.CallOption) (*GetResponse, error)
    Delete(ctx context.Context, in *DeleteRequest,
        opts ...grpc.CallOption) (*DeleteResponse, error)
}

Every method takes a context.Context, a protobuf request struct, and variadic grpc.CallOptions, and returns a protobuf response plus an error. Anyone calling the service has to import protobuf types, construct request structs like &api.PutRequest{}, and understand gRPC call options, even for a simple “get this key” call.

The server implements the other side with an in-memory map. What we care about for the wrapper is that it returns a gRPC NOT_FOUND status when a key doesn’t exist. The wrapper translates that into a Go sentinel error. Here’s the server code:

// server/main.go
type server struct {
    kvpb.UnimplementedKVServer
    data map[string][]byte
}

func (s *server) Get(
    ctx context.Context, r *kvpb.GetRequest,
) (*kvpb.GetResponse, error) {
    v, ok := s.data[r.Key]
    if !ok {
        return nil, status.Errorf(
            codes.NotFound, "key %q", r.Key)
    }
    return &kvpb.GetResponse{
        Value: v, Found: proto.Bool(true),
    }, nil
}
// Put and Delete follow the same shape.

The server embeds UnimplementedKVServer, the standard gRPC pattern. It provides no-op implementations for all RPCs so the code compiles even before you’ve written the real logic. The Get method checks the map and returns codes.NotFound when the key isn’t there. This is the status code the wrapper will catch and turn into a Go error. I’ve elided Put and Delete since they follow the same structure.

Using the generated client directly

Without a wrapper, callers use the generated KVClient directly. Pay attention to the imports:

// example/main.go (raw usage without wrapper)
import (
    "context"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    "example.com/kv/api"
)

// ...
conn, err := grpc.NewClient("localhost:9090",
    grpc.WithTransportCredentials(insecure.NewCredentials()))
// ...
kv := api.NewKVClient(conn)
_, err = kv.Put(ctx, &api.PutRequest{
    Key: "greeting", Value: []byte("hello"),
})

Three imports just to put a key. The caller manages the gRPC connection, constructs &api.PutRequest{} structs for every call, and has to parse gRPC status codes to check if a key exists. For internal code where everyone knows gRPC, this is fine. For a library you ship to other teams, it’s a lot of ceremony.

Calling the server with the wrapper

This is the API we actually want to give our users. Same sequence as before (put a key, get it back, handle a missing key) but without any gRPC or protobuf leaking through:

// example/main.go (with the wrapper)
import "example.com/kv/client"

// ...

c, err := client.New("localhost:9090")
// ...
defer c.Close()

err = c.Put(ctx, "greeting", []byte("hello"))

val, err := c.Get(ctx, "greeting")

_, err = c.Get(ctx, "missing")
if errors.Is(err, client.ErrNotFound) { ... }

One import instead of three. No gRPC or protobuf packages in sight. Put takes a string and a byte slice. Get returns []byte. Missing keys come back as client.ErrNotFound, checked with errors.Is like any other Go error. The caller doesn’t need to know that gRPC is involved at all.

The rest of this post builds the wrapper that turns the generated KVClient from the previous section into this API.

Building the wrapper

The client/ package is the only thing users import. It hides the generated api.KVClient behind a struct and re-exposes the same operations using plain Go types. The whole wrapper lives in a single file (client/client.go).

The wrapper starts with a sentinel error and a testable interface:

// client/client.go

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

type KV interface {
    Put(ctx context.Context, key string, value []byte) error
    Get(ctx context.Context, key string) ([]byte, error)
    Delete(ctx context.Context, key string) error
}

ErrNotFound replaces the gRPC NOT_FOUND status code. Callers check it with errors.Is and never import google.golang.org/grpc/codes.

Client implements KV, and KV uses only standard Go types instead of protobuf or gRPC types. This is intentionally a producer-side interface: we define it in the same package as Client because we know the full set of operations the service supports and we want to offer a ready-made contract for consumers. Other packages that depend on your client can accept a KV in their function signatures and swap in a simple in-memory fake during tests without spinning up a gRPC server or importing any gRPC packages.

Then the struct and constructor:

type Client struct {
    conn *grpc.ClientConn
    kv   api.KVClient
}

func New(addr string, opts ...grpc.DialOption) (*Client, error) {
    if len(opts) == 0 {
        opts = []grpc.DialOption{
            grpc.WithTransportCredentials(insecure.NewCredentials()),
        }
    }
    conn, err := grpc.NewClient(addr, opts...)
    if err != nil {
        return nil, fmt.Errorf("connecting to %s: %v", addr, err)
    }
    return &Client{conn: conn, kv: api.NewKVClient(conn)}, nil
}

func (c *Client) Close() error { return c.conn.Close() }

Client holds the gRPC connection and the generated api.KVClient as unexported fields. Note that api.KVClient is an interface, not a concrete struct. The gRPC codegen doesn’t expose the actual client struct at all; you get back a KVClient interface from api.NewKVClient(conn). We store it as a regular field rather than embedding it. If you embedded the api.KVClient interface, all its methods like Put(ctx, *PutRequest, ...CallOption) would be promoted onto Client directly, and callers could bypass the wrapper to make raw gRPC calls.

New creates the gRPC connection and builds the generated client from it. The variadic grpc.DialOption lets callers pass custom TLS, keepalive, or interceptor config. If they pass nothing, the default is insecure credentials for local dev. The retries section below shows what a production setup looks like.

With the types in place, we can look at the wrapper methods. Get shows the pattern all three follow:

func (c *Client) Get(ctx context.Context, key string) ([]byte, error) {
    resp, err := c.kv.Get(ctx, &api.GetRequest{Key: key})
    if err != nil {
        if s, ok := status.FromError(err); ok &&
            s.Code() == codes.NotFound {
            return nil, ErrNotFound
        }
        return nil, fmt.Errorf(
            "getting key %s: %v", key, err)
    }
    return resp.Value, nil
}
// Put and Delete follow the same shape.

Each wrapper method follows the same pattern: take the caller’s Go arguments, build the protobuf request internally, call the generated client, and return plain Go types.

Pay attention to the error handling. When the server returns NOT_FOUND, we catch that gRPC status and convert it to our own ErrNotFound sentinel so callers can check it with errors.Is instead of parsing gRPC status codes themselves. For everything else, we wrap with %v instead of %w. If we used %w, callers could unwrap the error with errors.As and reach the underlying gRPC status types, which would re-couple them to gRPC internals and defeat the whole point of having a wrapper. I wrote about this tradeoff in Go errors: to wrap or not to wrap?.

Plugging in retries and metrics

Since the wrapper owns the grpc.NewClient call, it can bake in retries and observability without the caller knowing. gRPC interceptors work like HTTP middleware. They wrap every RPC with extra logic (logging, retries, metrics) without changing the handler code. You register them as dial options when creating the connection:

// client/client.go (production version of New)
func New(addr string, opts ...grpc.DialOption) (*Client, error) {
    defaults := []grpc.DialOption{
        grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})),
        grpc.WithChainUnaryInterceptor(
            grpc_retry.UnaryClientInterceptor(
                grpc_retry.WithMax(3),
                grpc_retry.WithBackoff(
                    grpc_retry.BackoffExponential(100*time.Millisecond),
                ),
            ),
            grpcprom.UnaryClientInterceptor,
        ),
    }
    opts = append(defaults, opts...)
    // ... rest is the same
}

grpc_retry from go-grpc-middleware retries failed RPCs with exponential backoff. grpcprom records latency histograms and error rates. Same client.New, same c.Put, but now with retries and metrics baked in. Callers who need to override the defaults can pass their own dial options. This is useful in tests where you might want insecure credentials or no retries.

Try it yourself

The full code is on GitHub. Install the server and run the example:

go install github.com/rednafi/examples/wrapping-grpc-client/server@latest
server &

go install github.com/rednafi/examples/wrapping-grpc-client/example@latest
example

Running the example will return:

put greeting=hello
get greeting=hello
get missing: not found (expected)
deleted greeting
get greeting after delete: not found (expected)

Or add the client library to your own project:

go get github.com/rednafi/examples/wrapping-grpc-client/client@latest

var (
    mu      sync.Mutex
    counter int
)

mu.Lock()
counter++
mu.Unlock()

This works, but nothing enforces it. The compiler won’t stop you from accessing counter without holding the lock. Forget to lock in one spot and you have a data race. One way to make this safer is to bundle the value and its mutex into a small generic wrapper that only exposes locked access through methods:

type Locked[T any] struct {
    mu sync.Mutex
    v  T
}

func NewLocked[T any](initial T) *Locked[T] {
    return &Locked[T]{v: initial}
}

func (l *Locked[T]) Get() T {
    l.mu.Lock()
    defer l.mu.Unlock()
    return l.v
}

func (l *Locked[T]) Set(v T) {
    l.mu.Lock()
    defer l.mu.Unlock()
    l.v = v
}

You keep mu and v unexported, pass around *Locked[T], and callers use Get to read and Set to write:

counter := NewLocked(0)

counter.Set(42)
fmt.Println(counter.Get()) // 42

Now callers can’t touch the underlying value without going through the lock. This doesn’t prevent misuse within the same package, but it makes unprotected access from other packages impossible.

This works fine when you’re replacing the value wholesale - just call counter.Set(42) and move on. But when your mutation depends on the current value, Get and Set can race against each other.

The problem with Set

Say you want to increment the counter instead of replacing it. You’d have to do:

v := counter.Get()
v++
counter.Set(v)

Each individual call is safe - Get holds the lock while reading, Set holds it while writing. But the three calls together aren’t atomic. Between Get and Set, another goroutine can modify the value, and your increment overwrites theirs. That’s the classic lost-update bug.

It gets worse with compound state. Say the wrapper holds a struct:

type State struct {
    Count int
    Name  string
}

state := NewLocked(State{})

And you want to conditionally update both fields:

s := state.Get()
if s.Count < 10 {
    s.Count++
    s.Name = fmt.Sprintf("item-%d", s.Count)
}
state.Set(s)

Same problem. Get returns a copy, you mutate the copy, then Set writes it back. If another goroutine modified state between those two calls, your write clobbers it.

func TestSetValue(t *testing.T) {
    counter := NewLocked(0)

    var wg sync.WaitGroup
    for range 10 {
        wg.Go(func() {
            for range 1000 {
                v := counter.Get()
                v++
                counter.SetValue(v)
            }
        })
    }

    wg.Wait()

    got := counter.Get()
    if got != 10000 {
        t.Errorf("got %d, want 10000 (lost %d updates)", got, 10000-got)
    }
}

=== RUN   TestSetValue
    locked_test.go:30: got 1855, want 10000 (lost 8145 updates)
--- FAIL: TestSetValue (0.02s)

Take a function instead

Instead of taking a value, have Set take a function:

func (l *Locked[T]) Set(f func(*T)) {
    l.mu.Lock()
    defer l.mu.Unlock()
    f(&l.v)
}

Now the counter increment becomes:

counter.Set(func(v *int) {
    *v++
})

And the compound mutation:

state.Set(func(s *State) {
    if s.Count < 10 {
        s.Count++
        s.Name = fmt.Sprintf("item-%d", s.Count)
    }
})

The lock is held for the entire closure. There’s no gap between reading and writing, so no other goroutine can interfere. Both fields update together or not at all.

The function takes a pointer to T rather than a value of T for two reasons. First, it lets you mutate the state in place instead of working on a copy. Second, if T is a large struct, passing a pointer avoids copying the whole thing into the closure on every call.

The stdlib already does this

Go’s database/sql package has an internal withLock helper that follows the same pattern:

// withLock runs while holding lk.
func withLock(lk sync.Locker, fn func()) {
    lk.Lock()
    defer lk.Unlock() // in case fn panics
    fn()
}

It’s used throughout database/sql to serialize access to the underlying driver connection. For example, when pinging a connection:

if pinger, ok := dc.ci.(driver.Pinger); ok {
    withLock(dc, func() {
        err = pinger.Ping(ctx)
    })
}

Or when preparing a statement:

withLock(dc, func() {
    si, err = ctxDriverPrepare(ctx, dc.ci, query)
})

Or committing a transaction:

withLock(tx.dc, func() {
    err = tx.txi.Commit()
})

There are about 18 call sites in sql.go alone. In those snippets, dc is a *driverConn - the struct that wraps a database driver connection. It embeds sync.Mutex directly, so it satisfies sync.Locker and can be passed straight to withLock.

withLock(rs.closemu.RLocker(), func() {
    doClose, ok = rs.nextLocked()
})

The proposal to add this to sync

In 2021, twmb filed proposal #49563 to add a Mutex.Locked(func()) method to the standard library:

func (m *Mutex) Locked(fn func()) {
    m.Lock()
    defer m.Unlock()
    fn()
}

The idea was that if sync.Mutex had this method natively, you wouldn’t need to write a wrapper at all for simple cases - you’d just call mu.Locked(fn) directly. It also eliminates forgotten unlocks and guards against panics leaving the mutex locked. esote pointed out that database/sql already had an internal version of this - the same withLock helper we saw earlier.

zephyrtronium raised the sync.Locker point:

I think there are advantages to making this a function that takes a Locker rather than a method on Mutex. This would allow using it with either end of an RWMutex, or another custom Locker.

– zephyrtronium on #49563

rsc declined it on philosophical grounds:

In general we try not to have two different ways to do something, and for better or worse we have the current idioms.

– rsc on #49563

The more interesting pushback came from bcmills, who argued the proposal didn’t go far enough. With generics arriving, he wanted something that also prevents unguarded access to the protected data, not just forgotten unlocks:

Now that we have generics on the way, I would rather see us move in a direction that also eliminates unlocked-access bugs, not just incrementally update Mutex for forgotten-defer bugs.

– bcmills on #49563

He sketched out what that could look like:

type Synchronized[T any] struct {
    mu  Mutex
    val T
}

func (s *Synchronized[T]) Do(fn func(*T)) {
    s.mu.Lock()
    defer s.mu.Unlock()
    fn(&s.val)
}

This is essentially the Locked[T] wrapper from the beginning of this post. The proposal was declined, but bcmills’ suggestion is the direction the community ended up going anyway-just outside the standard library.

Tailscale’s MutexValue

Tailscale’s syncs package has a MutexValue[T] type that follows this direction:

type MutexValue[T any] struct {
    mu sync.Mutex
    v  T
}

func (m *MutexValue[T]) WithLock(f func(p *T)) {
    m.mu.Lock()
    defer m.mu.Unlock()
    f(&m.v)
}

func (m *MutexValue[T]) Load() T {
    m.mu.Lock()
    defer m.mu.Unlock()
    return m.v
}

func (m *MutexValue[T]) Store(v T) {
    m.mu.Lock()
    defer m.mu.Unlock()
    m.v = v
}

They provide both Store for simple replacements and WithLock for compound mutations. When you need to read-modify-write, you go through WithLock so the lock covers the whole operation.

When a plain Set is fine

If T is small and you only ever replace the whole value without reading it first, a plain Set works. A boolean flag that gets toggled from one place, a config value that gets swapped wholesale - those are fine.

But most state doesn’t stay that simple. You start with a single integer, it becomes a struct with three fields, and now you need to update two of them based on the third. At that point, Set(func(*T)) is the only safe option.

There are frameworks that generate those kind of fakes, and one of them is called GoMock… they’re fine, but I find that on balance, the handwritten fakes tend to be easier to reason about and clearer to sort of see what’s going on. But I’m not an enterprise Go programmer. Maybe people do need that, so I don’t know, but that’s my advice.

– Andrew Gerrand, Testing Techniques (46:44)

No shade against mocking libraries like gomock or mockery. I use them all the time, both at work and outside. But one thing I’ve noticed is that generating mocks often leads to poorly designed tests and increases onboarding time for a codebase.

Also, since almost no one writes tests by hand anymore and instead generates them with LLMs, the situation gets more dire. These ghosts often pull in all kinds of third-party libraries to mock your code, simply because they were trained on a lot of hastily written examples on the web.

So the idea of this post isn’t to discourage using mocking libraries. Rather, it’s to show that even if your codebase already has a mocking library in the dependency chain, not all of your tests need to depend on it. Below are a few cases where I tend not to use any mocking library and instead leverage the constructs that Go gives us.

This does require some extra song and dance with the language, but in return, we gain more control over our tests and reduce the chance of encountering spooky action at a distance.

Mocking a function

Say you have a function that creates a database handle:

func OpenDB(user, pass, host, dbName string) (*sql.DB, error) {
    dsn := fmt.Sprintf("%s:%s@tcp(%s)/%s", user, pass, host, dbName)
    return sql.Open("mysql", dsn)
}

The problem is that sql.Open hands the DSN directly to the driver. When you call OpenDB("admin", "secret", "db.internal", "orders"), the function formats the DSN string and hands it to the MySQL driver. You can’t intercept that call, you can’t control what it returns, and you probably don’t want unit tests leaning on a real driver (or a real MySQL instance) just to verify DSN formatting.

The fix is to make the database opener injectable:

type SQLOpenFunc func(driver, dsn string) (*sql.DB, error)  // (1)

func OpenDB(
    user, pass, host, dbName string, openFn SQLOpenFunc, // (2)
) (*sql.DB, error) {
    dsn := fmt.Sprintf("%s:%s@tcp(%s)/%s", user, pass, host, dbName)
    return openFn("mysql", dsn)  // (3)
}

Here:

• (1) defines a function type that matches sql.Open’s signature
• (2) accepts an opener function as a parameter
• (3) delegates to that function instead of calling sql.Open directly

In production, pass the real sql.Open:

func main() {
    db, err := OpenDB(
        "admin", "secret", "db.internal", "orders", sql.Open,  // (1)
    )
    // ...
}

Here:

• (1) the real sql.Open is passed as the last argument - no wrapper needed

In tests, pass a fake that captures what was passed or returns canned values:

func TestOpenDB(t *testing.T) {
    var got string
    fakeOpen := func(driver, dsn string) (*sql.DB, error) {
        got = dsn  // (1) capture what was passed
        return nil, nil
    }

    OpenDB(
        "admin", "secret", "db.internal", "orders", fakeOpen,  // (2)
    )

    want := "admin:secret@tcp(db.internal)/orders"
    if got != want {
        t.Errorf("got %q, want %q", got, want)
    }
}

Here:

• (1) the fake captures the DSN for later assertion
• (2) the call site looks the same, just with a different opener

This pattern works for any function dependency - UUID generators, random number sources, file openers. Functions are first-class values in Go, so you can pass them around like any other value.

The downside is that parameter lists can grow quickly. If OpenDB also needed a logger, a metrics client, and a config loader, the signature becomes unwieldy. When you find yourself passing more than two or three function dependencies, consider grouping them into a struct with an interface - see Mocking a method on a type.

Monkey patching

Sometimes you inherit code where refactoring the function signature isn’t practical. Maybe it’s called from dozens of places, or it’s part of a public API you can’t change:

func PublishOrderCreated(
    ctx context.Context, brokers []string, id string) error {
    w := &kafka.Writer{
        Addr: kafka.TCP(brokers...), Topic: "order-events",
    }
    defer w.Close()
    return w.WriteMessages(ctx, kafka.Message{Key: []byte(id)})
}

The Kafka writer is instantiated directly inside the function. There’s no seam to inject a fake without touching every call site. If this function is called from 50 places in your codebase, changing its signature means updating all 50.

One workaround is a package-level variable that points to the constructor:

type kafkaWriter interface {  // (1)
    WriteMessages(context.Context, ...kafka.Message) error
    Close() error
}

var newWriter = func(brokers []string) kafkaWriter {  // (2)
    return &kafka.Writer{
        Addr: kafka.TCP(brokers...), Topic: "order-events",
    }
}

func PublishOrderCreated(
    ctx context.Context, brokers []string, id string,
) error {
    w := newWriter(brokers)  // (3)
    defer w.Close()
    return w.WriteMessages(ctx, kafka.Message{Key: []byte(id)})
}

Here:

• (1) define an interface with only the methods we need from kafka.Writer
• (2) the package variable returns the interface type, not the concrete type
• (3) the function calls it instead of instantiating directly

Production code doesn’t change - it calls PublishOrderCreated exactly as before, and the default newWriter creates real Kafka writers.

Tests swap it out:

type fakeWriter struct {
    key []byte
}

func (f *fakeWriter) WriteMessages(
    _ context.Context, msgs ...kafka.Message) error {
    if len(msgs) > 0 {
        f.key = msgs[0].Key  // (1)
    }
    return nil
}

func (f *fakeWriter) Close() error { return nil }

func TestPublishOrderCreated(t *testing.T) {
    orig := newWriter
    t.Cleanup(func() { newWriter = orig })  // (2) restore after test

    fake := &fakeWriter{}
    newWriter = func([]string) kafkaWriter {  // (3)
        return fake
    }

    PublishOrderCreated(
        t.Context(), []string{"kafka:9092"}, "ord-1",
    )

    if got := string(fake.key); got != "ord-1" {  // (4)
        t.Errorf("got %q, want %q", got, "ord-1")
    }
}

Here:

• (1) the fake captures the message key for later assertion
• (2) t.Cleanup ensures the original is restored even if the test fails
• (3) the replacement factory returns the fake - note it returns kafkaWriter, matching the variable’s type
• (4) assert the captured key matches the expected value

This works, but be aware of the costs. Tests that mutate package state can’t run in parallel - they’d stomp on each other’s fakes. If you’re writing tests from an external package (package events_test), the variable must be exported, which pollutes your public API.

Prefer the function parameter pattern or the interface pattern over monkey patching. Reserve this technique for legacy code where changing signatures would be too disruptive.

Mocking a method on a type

This is a pattern you’ll see all the time in services that integrate with third-party APIs. Here’s a payment service that charges customers through Stripe (this uses the newer stripe.Client API, which is the recommended shape in recent stripe-go versions):

func (s *Service) ChargeCustomer(
    ctx context.Context, custID string, cents int64) (string, error) {
    intent, err := s.client.V1PaymentIntents.Create(ctx,
        &stripe.PaymentIntentCreateParams{
            Amount:   stripe.Int64(cents),
            Currency: stripe.String("usd"),
            Customer: stripe.String(custID),
        },
    )
    if err != nil {
        return "", err
    }
    return intent.ID, nil
}

Testing this hits the real Stripe API. That’s slow, requires live credentials, and in production mode charges actual money. The problem is that s.client is a *stripe.Client from the SDK - there’s no way to swap it for a fake without introducing a seam.

The solution is to introduce an interface that describes what you need:

type PaymentIntentCreator interface {  // (1)
    Create(
        context.Context, *stripe.PaymentIntentCreateParams,
    ) (*stripe.PaymentIntent, error)
}

type Service struct {
    intents PaymentIntentCreator  // (2)
}

func (s *Service) ChargeCustomer(
    ctx context.Context, custID string, cents int64) (string, error) {
    intent, err := s.intents.Create(ctx,  // (3)
        &stripe.PaymentIntentCreateParams{
            Amount:   stripe.Int64(cents),
            Currency: stripe.String("usd"),
            Customer: stripe.String(custID),
        })
    if err != nil {
        return "", err
    }
    return intent.ID, nil
}

Here:

• (1) the interface has one method matching what we need from the SDK
• (2) the service holds the dependency as a field
• (3) calls through the interface instead of the client directly

In production, inject the real Stripe service client:

func main() {
    sc := stripe.NewClient("sk_test_...")
    svc := &Service{intents: sc.V1PaymentIntents}  // (1)
    // ...
}

Here:

• (1) sc.V1PaymentIntents satisfies PaymentIntentCreator (it has a Create method with the right signature)

In tests, you pass a fake that returns canned values:

type fakeIntents struct {
    id string  // (1)
}

func (f *fakeIntents) Create(
    context.Context, *stripe.PaymentIntentCreateParams,
) (*stripe.PaymentIntent, error) {
    return &stripe.PaymentIntent{ID: f.id}, nil  // (2)
}

func TestChargeCustomer(t *testing.T) {
    fake := &fakeIntents{id: "pi_123"}  // (3)
    svc := &Service{intents: fake}
    id, _ := svc.ChargeCustomer(t.Context(), "cus_abc", 5000)
    // assert id == "pi_123"
}

Here:

• (1) the fake struct holds the canned return value
• (2) returns whatever you configured instead of calling Stripe
• (3) configure the fake with the expected payment intent ID

The service doesn’t know or care whether it’s talking to Stripe or a test fake. This is the most common mocking pattern in Go - define an interface for your dependency, accept it in your constructor, and swap implementations at runtime.

But what happens when the SDK surface area is huge and your code only needs one operation? That’s where the next pattern comes in.

Consumer-side interface segregation

The previous pattern works well when you control the interface. But AWS SDK clients have dozens of methods. The DynamoDB client has over 40 operations - GetItem, PutItem, Query, Scan, BatchGetItem, and so on. If you write tests against a dependency that exposes the whole surface area, your fakes become annoying fast.

The solution is to define a minimal interface on the consumer side:

type itemGetter interface {  // (1)
    GetItem(context.Context, *dynamodb.GetItemInput,
        ...func(*dynamodb.Options)) (*dynamodb.GetItemOutput, error)
}

func GetUserByID(
    ctx context.Context, client itemGetter, id string) (*User, error) {
    out, err := client.GetItem(ctx, &dynamodb.GetItemInput{  // (2)
        TableName: aws.String("users"),
        Key: map[string]types.AttributeValue{
            "pk": &types.AttributeValueMemberS{Value: id},
        },
    })
    // ...
}

Here:

• (1) the interface has exactly one method - just what this function needs
• (2) accept the minimal interface and call through it

In production, pass the real DynamoDB client - it satisfies itemGetter because it has a GetItem method. Go interfaces are satisfied implicitly:

func main() {
    client := dynamodb.NewFromConfig(cfg)
    user, err := GetUserByID(ctx, client, "user-123")  // (1)
    // ...
}

Here:

• (1) the real client satisfies itemGetter automatically - no adapter or wrapper needed thanks to implicit interface satisfaction

In tests, you only implement the one method you need:

type fakeItemGetter struct {
    item map[string]types.AttributeValue  // (1)
}

func (f *fakeItemGetter) GetItem(context.Context, *dynamodb.GetItemInput,
    ...func(*dynamodb.Options)) (*dynamodb.GetItemOutput, error) {
    return &dynamodb.GetItemOutput{Item: f.item}, nil  // (2)
}

func TestGetUserByID(t *testing.T) {
    fake := &fakeItemGetter{
        item: map[string]types.AttributeValue{
            "email": &types.AttributeValueMemberS{Value: "a@b.com"},
        },
    }
    user, _ := GetUserByID(t.Context(), fake, "u-1")  // (3)
    // assert user.Email == "a@b.com"
}

Here:

• (1) the fake struct holds the canned response data
• (2) returns the configured item - no network call
• (3) pass the fake to the function under test

This is the Interface Segregation Principle in action - clients shouldn’t be forced to depend on methods they don’t use.

But this approach has limits. If you have 20 functions each using different DynamoDB operations, you’d end up with 20 tiny interfaces. And sometimes you’re stuck with a preexisting interface type that has more methods than you want. That’s where struct embedding helps.

Struct embedding for partial implementation

Sometimes you can’t define your own minimal interface. Maybe a library insists on a specific interface type, and it’s bigger than what your test cares about.

The AWS SDK v2’s S3 upload manager is a good example. manager.NewUploader takes a client interface that supports both single-part uploads and multipart uploads. If your test is exercising the single-part path and you only want to intercept PutObject, implementing the multipart methods just to satisfy the interface is pure busywork.

Go’s struct embedding provides an escape hatch. Here’s the production code:

func UploadReport(
    ctx context.Context, client manager.UploadAPIClient,  // (1)
    bucket, key string, body io.Reader,
) error {
    up := manager.NewUploader(client)
    _, err := up.Upload(ctx, &s3.PutObjectInput{
        Bucket: aws.String(bucket),
        Key:    aws.String(key),
        Body:   body,
    })
    return err
}

Here:

• (1) accepts the SDK’s UploadAPIClient interface - a large interface with many methods

In tests, embed the interface in your fake and override only what you need:

type fakeS3 struct {
    manager.UploadAPIClient  // (1)
    gotKey  string
    gotBody []byte
}

func (f *fakeS3) PutObject(
    _ context.Context, in *s3.PutObjectInput, _ ...func(*s3.Options),
) (*s3.PutObjectOutput, error) {
    if in.Key != nil {
        f.gotKey = *in.Key  // (2)
    }
    if in.Body != nil {
        f.gotBody, _ = io.ReadAll(in.Body)
    }
    return &s3.PutObjectOutput{}, nil
}

func TestUploadReport(t *testing.T) {
    fake := &fakeS3{}
    err := UploadReport(
        t.Context(),
        fake,  // (3)
        "my-bucket",
        "reports/q1.csv",
        bytes.NewReader([]byte("hi")),  // (4)
    )
    if err != nil {
        t.Fatal(err)
    }
    if fake.gotKey != "reports/q1.csv" {
        t.Errorf("got %q, want %q", fake.gotKey, "reports/q1.csv")
    }
}

Here:

• (1) embedding the interface satisfies the full interface at compile time
• (2) capture what you care about - only implement what this test needs
• (3) pass the fake to code that expects the full UploadAPIClient interface
• (4) use a small body so the upload manager takes the single PutObject path

The embedded interface value is nil, so any method you don’t override will panic if called. This is a feature, not a bug. If your code accidentally triggers multipart and calls CreateMultipartUpload, the test crashes immediately, and you learn that your test setup (or your assumptions) are wrong.

Function type as interface

For interfaces with a single method, there’s an even more compact approach. Say you have middleware that validates authentication tokens:

type ctxKey string

const userIDKey ctxKey = "userID"

type TokenValidator interface {  // (1)
    Validate(token string) (userID string, err error)
}

func RequireAuth(v TokenValidator, next http.Handler) http.Handler {  // (2)
    fn := func(w http.ResponseWriter, r *http.Request) {
        userID, err := v.Validate(r.Header.Get("Authorization"))
        if err != nil {
            http.Error(w, "unauthorized", 401)
            return
        }
        ctx := context.WithValue(r.Context(), userIDKey, userID)
        next.ServeHTTP(w, r.WithContext(ctx))
    }
    return http.HandlerFunc(fn)
}

Here:

• (1) a single-method interface - the perfect candidate for a function type adapter
• (2) the middleware accepts the interface as a dependency

You could write a fake struct with a Validate method, but Go lets you define a function type that satisfies the interface:

type TokenValidatorFunc func(string) (string, error)  // (1)

func (f TokenValidatorFunc) Validate(token string) (string, error) {
    return f(token)  // (2)
}

Here:

• (1) define a function type with the right signature
• (2) add a method that just calls the function itself

This is the same pattern the standard library uses with http.HandlerFunc. Now tests can pass inline functions:

func TestRequireAuth(t *testing.T) {
    v := TokenValidatorFunc(func(token string) (string, error) {
        if token == "Bearer valid" {
            return "user-123", nil  // (1)
        }
        return "", errors.New("invalid")
    })
    next := http.HandlerFunc(func(http.ResponseWriter, *http.Request) {})
    handler := RequireAuth(v, next)  // (2)

    req := httptest.NewRequest("GET", "/protected", nil)
    req.Header.Set("Authorization", "Bearer valid")
    rec := httptest.NewRecorder()
    handler.ServeHTTP(rec, req)
    // assert rec.Code == http.StatusOK
}

Here:

• (1) return a known user ID for a valid token
• (2) the middleware accepts it as a TokenValidator interface

No extra struct definitions cluttering up your test file.

Mocking HTTP calls

When your code makes HTTP requests to external services, the net/http/httptest package provides a test server that runs on localhost. Say you have a client that fetches exchange rates:

func (c *Client) GetRate(from, to string) (float64, error) {
    url := c.baseURL + "/latest?base=" + from + "&symbols=" + to
    resp, err := c.httpClient.Get(url)
    if err != nil {
        return 0, err
    }
    defer resp.Body.Close()
    // decode JSON, return rate...
}

In production, c.baseURL points to the real API. Testing against it is problematic - it’s slow, requires credentials, returns different values each time, and might rate-limit your CI.

The httptest.Server spins up a real HTTP server on localhost:

func TestGetRate(t *testing.T) {
    srv := httptest.NewServer(http.HandlerFunc(  // (1)
        func(w http.ResponseWriter, r *http.Request) {
            fmt.Fprint(w, `{"base":"USD","rates":{"EUR":0.92}}`)
        },
    ))
    defer srv.Close()  // (2)

    client := NewClient(srv.URL, "key")  // (3)
    rate, _ := client.GetRate("USD", "EUR")

    // assert rate == 0.92
}

Here:

• (1) spin up a local HTTP server with a handler that returns canned JSON
• (2) shut down the server when the test finishes
• (3) point your client at srv.URL instead of the real API

Your code makes real HTTP calls over TCP, but they never leave the machine. You can return different responses for different scenarios - rate limits, malformed JSON, network errors - whatever you need to test.

Mocking time

This is essentially the same technique as Mocking a function - we’re just applying it to time.Now. Code that depends on the current time is tricky to test:

func IsExpired(expiresAt time.Time) bool {
    return time.Now().After(expiresAt)
}

Every call to time.Now() returns a different value. You can’t write a reliable test because the result depends on when the test runs.

Make the clock injectable:

type Clock func() time.Time  // (1)

func IsExpired(expiresAt time.Time, clock Clock) bool {  // (2)
    return clock().After(expiresAt)
}

Here:

• (1) define a function type for getting the current time
• (2) accept it as a parameter

In production, pass time.Now:

func main() {
    expired := IsExpired(token.ExpiresAt, time.Now)  // (1)
    // ...
}

Here:

• (1) pass the real time.Now function - it satisfies the Clock type

In tests, pass a function that returns a fixed time:

func TestIsExpired(t *testing.T) {
    expiry := time.Date(2025, 6, 15, 12, 0, 0, 0, time.UTC)

    before := func() time.Time { return expiry.Add(-time.Hour) }  // (1)
    after := func() time.Time { return expiry.Add(time.Hour) }   // (2)

    if IsExpired(expiry, before) {
        t.Error("should not be expired")
    }
    if !IsExpired(expiry, after) {
        t.Error("should be expired")
    }
}

Here:

• (1) a clock that returns one hour before expiry
• (2) a clock that returns one hour after expiry

For code that uses time.Sleep, timers, or tickers, Go 1.25’s testing/synctest provides a fake clock that advances automatically when goroutines in the bubble are durably blocked:

func TestPeriodicFlush(t *testing.T) {
    synctest.Test(t, func(t *testing.T) {  // (1)
        count := 0
        go func() {
            ticker := time.NewTicker(10 * time.Second)  // (2)
            defer ticker.Stop()
            for range ticker.C {
                count++
                if count >= 3 {
                    return
                }
            }
        }()
        time.Sleep(35 * time.Second)  // (3)
        synctest.Wait()               // (4)
        // assert count == 3
    })
}

Here:

• (1) synctest.Test runs the function in an isolated bubble with fake time starting at 2000-01-01
• (2) the ticker uses fake time - no real 10-second waits
• (3) time.Sleep inside the bubble uses fake time; time advances when goroutines are durably blocked, so this returns instantly after the ticker fires 3 times
• (4) synctest.Wait is a synchronization point; it blocks until the other goroutines in the bubble are durably blocked or finished

Inside synctest.Test, the framework intercepts time operations. The test completes instantly rather than waiting for real time to pass.

Closing words

These are the most common ones where I typically avoid opting for mocking libraries. But there are cases when I still like to generate mocks for an interface. One example that comes to mind is testing gRPC servers. I’m sure I’m forgetting some other cases where I regularly use mocking libraries.

The point is not to discourage the use of mocking libraries or to make a general statement that “all mocking libraries are bad.” It’s that these mocking libraries have costs associated with them. Code generation is fun, but it’s one extra step that you have to teach someone who’s onboarding to your codebase.

Also, if you’re using LLMs to generate tests, you may want to write some tests manually to give the tool a sense of how you want your tests written, so it doesn’t pull in the universe just to mock something that can be mocked natively using Go constructs.

For more on why handwritten fakes often beat generated mocks, see Test state, not interactions.

Still, I’ve found that principles like SOLID, despite their OO origin, can be useful guides when thinking about design in Go.

Recently, while chatting with a few colleagues new to Go, I noticed that some of them had spontaneously rediscovered the Interface Segregation Principle (the “I” in SOLID) without even realizing it. The benefits were obvious, but without a shared vocabulary, it was harder to talk about and generalize the idea.

So I wanted to revisit ISP in the context of Go and show how small interfaces, implicit implementation, and consumer-defined contracts make interface segregation feel natural and lead to code that’s easier to test and maintain.

Clients should not be forced to depend on methods they do not use.

– Robert C. Martin (SOLID, interface segregation principle)

Or, put simply: your code shouldn’t accept anything it doesn’t use.

Consider this example:

type FileStorage struct{}

func (FileStorage) Save(data []byte) error {
    fmt.Println("Saving data to disk...")
    return nil
}

func (FileStorage) Load(id string) ([]byte, error) {
    fmt.Println("Loading data from disk...")
    return []byte("data"), nil
}

FileStorage has two methods: Save and Load. Now suppose you write a function that only needs to save data:

func Backup(fs FileStorage, data []byte) error {
    return fs.Save(data)
}

This works, but there are a few problems hiding here.

Backup takes a FileStorage directly, so it only works with that type. If you later want to back up to memory, a network location, or an encrypted store, you’ll need to rewrite the function. Because it depends on a concrete type, your tests have to use FileStorage too, which might involve disk I/O or other side effects you don’t want in unit tests. And from the function signature, it’s not obvious what part of FileStorage the function actually uses.

Instead of depending on a specific type, we can depend on an abstraction. In Go, you can achieve that through an interface. So let’s define one:

type Storage interface {
    Save(data []byte) error
    Load(id string) ([]byte, error)
}

Now Backup can take a Storage instead:

func Backup(store Storage, data []byte) error {
    return store.Save(data)
}

Backup now depends on behavior, not implementation. You can plug in anything that satisfies Storage, something that writes to disk, memory, or even a remote service. And FileStorage still works without any change.

You can also test it with a fake:

type FakeStorage struct{}

func (FakeStorage) Save(data []byte) error         { return nil }
func (FakeStorage) Load(id string) ([]byte, error) { return nil, nil }

func TestBackup(t *testing.T) {
    fake := FakeStorage{}
    err := Backup(fake, []byte("test-data"))
    if err != nil {
        t.Fatal(err)
    }
}

That’s a step forward. It fixes the coupling issue and makes the tests free of side effects. However, there’s still one issue: Backup only calls Save, yet the Storage interface includes both Save and Load. If Storage later gains more methods, every fake must grow too, even if those methods aren’t used. That’s exactly what the ISP warns against.

The above interface is too broad. So let’s narrow it to match what the function actually needs:

type Saver interface {
    Save(data []byte) error
}

Then update the function:

func Backup(s Saver, data []byte) error {
    return s.Save(data)
}

Now the intent is clear. Backup only depends on Save. A test double can just implement that one method:

type FakeSaver struct{}

func (FakeSaver) Save(data []byte) error { return nil }

func TestBackup(t *testing.T) {
    fake := FakeSaver{}
    err := Backup(fake, []byte("test-data"))
    if err != nil {
        t.Fatal(err)
    }
}