Interfaces: implicit satisfaction, the typed-nil trap, and what indirection costs

Implicit satisfaction: the contract nobody signs

A Go type satisfies an interface by simply having the methods — no implements keyword, no declaration, no import. If your struct has Read(p []byte) (int, error), it is an io.Reader, even if io was never imported and the interface was written years later. This is structural typing checked at compile time, and it inverts the dependency arrow: the consumer defines the interface it needs, and any producer that happens to fit, fits. You can define a one-method interface in your package and the standard library’s types already satisfy it — retrofitting an abstraction onto code you don’t own, with zero changes to that code. Because nothing declares intent, the idiom for “I promise this type satisfies that interface, fail the build if not” is a compile-time assertion:

type Store interface {
    Get(ctx context.Context, key string) ([]byte, error)
}

// Compile-time proof: *RedisStore satisfies Store. Costs nothing at runtime.
var _ Store = (*RedisStore)(nil)

The (type, value) pair — and the typed-nil trap

Under the hood an interface value is two machine words (16 bytes on 64-bit): a pointer to type/method metadata — the itab, holding the concrete type and the resolved method addresses — and a pointer to the data. Assigning a concrete value to an interface fills both words. This representation explains everything weird about interfaces. Equality compares both words. A type assertion reads the type word. And the trap from the Hook: an interface is nil only when both words are nil. Store a nil *HealthError into an error and the type word gets set (*HealthError) while the data word stays nil — the interface itself is not nil:

type HealthError struct{ Reason string }

func (e *HealthError) Error() string { return e.Reason }

func check() *HealthError {
    return nil // healthy: nil pointer of CONCRETE type
}

func main() {
    var err error = check()         // (type=*HealthError, data=nil)
    fmt.Println(err == nil)         // false — type word is set!
    fmt.Printf("%#v\n", err)        // (*main.HealthError)(nil) — the tell
}

The rule that prevents it: functions that can fail return the error interface type, never a concrete error pointer type. Inside, return a literal nil, not a possibly-nil typed variable. When you’re debugging a “non-nil nil,” %#v (or %T) exposes the type word that %v hides. This isn’t a compiler bug to route around — it falls straight out of the two-word representation, and once you see the pair, the behavior is the only one possible.

Small interfaces, and accept-interfaces-return-structs

How do you know when to introduce an interface and how big to make it? The standard library’s answer is consistent: its most-used interfaces have one method: io.Reader, io.Writer, fmt.Stringer. That’s deliberate — the bigger the interface, the weaker the abstraction. A one-method interface is satisfiable by hundreds of types and composable into bigger ones (io.ReadWriteCloser is three one-method interfaces embedded); a twelve-method interface is satisfiable by exactly one struct plus the mock you wrote for it, which means it’s not an abstraction, it’s a header file. The companion rule: accept interfaces, return structs. Parameters typed as small interfaces ask for the minimum capability — take an io.Reader, not an *os.File, and the function works on files, network connections, buffers, and test strings alike. Returns typed as concrete structs preserve the full method set and let callers decide what to abstract; returning an interface hides methods callers may need and freezes your API around today’s guess. (The known exception: return the error interface — see the previous section for why that one’s mandatory.)

// Asks for the minimum, works with anything readable.
func CountLines(r io.Reader) (int, error) { ... }

// Returns the concrete type: callers get the full *Parser API
// and can still assign it to any interface THEY define.
func NewParser(opts ...Option) *Parser { ... }

Type switches are the inspection tool when one value may be several things: switch v := x.(type) branches on the dynamic type and binds v with the right static type per case. Idiomatic for protocol decoding and capability probing (does this io.Writer also implement Flusher?); a smell when a growing switch over your own types replaces what a method on the interface should have been.

What indirection costs — and when it matters

Interface calls are dynamic dispatch: load the method address from the itab, jump. The call itself is a couple of nanoseconds — close to a direct call and rarely the issue. The real costs are second-order. Inlining is blocked: the compiler can’t inline a callee it can’t identify, so a one-line getter behind an interface stays a real call and everything that inlining would have unlocked (constant folding, dead-code elimination, keeping values in registers) is off. Escape to the heap: storing a value in an interface generally forces it to be heap-allocated, because the interface’s data word holds a pointer — pass an int as interface{} in a hot loop and you may allocate on every iteration, which is GC pressure, not just nanoseconds. Honest numbers: a direct call ~1–2 ns, an interface call ~2–4 ns, but a lost inline plus a forced allocation can turn a free operation into ~25–50 ns with GC amortization — a 10–30× difference in the hottest loops and irrelevant outside them. The compiler devirtualizes when it can prove the concrete type (and profile-guided optimization, Go 1.21+, devirtualizes hot call sites from production profiles), but you shouldn’t count on it across package boundaries. The engineering posture: design with interfaces at architectural seams — storage, transport, clock — where the call frequency is per-request, and keep per-element hot paths (codecs, parsers, tight loops over millions of items) concrete or generic; measure with a profiler before flattening any abstraction in the name of speed.