Go Interfaces and Composition

Interfaces in Go are consumer contracts, not implementation hierarchies. They should be small, discovered late, and owned by the package that uses them — not the package that satisfies them.

Core Rules

1. Accept interfaces, return concrete types. Consumers state what they need; producers expose what they have.
2. Interfaces belong in the consumer package. Defining an interface next to its sole implementation is almost always wrong.
3. Don't design with interfaces — discover them. Wait for a second implementation or a test mock to demand one.
4. The bigger the interface, the weaker the abstraction. Aim for 1–3 methods; compose larger contracts from smaller ones.
5. Receiver consistency: if any method needs a pointer receiver, give every method a pointer receiver.
6. Verify satisfaction at compile time with var _ I = (*T)(nil) when the relationship must not break silently.
7. Use the comma-ok idiom for every type assertion. A bare assertion panics on mismatch.

Decision: Should I Introduce an Interface?

Read references/consumer-owned-interfaces.md when migrating a producer-defined interface back to the consumer, or when designing a new package boundary.

Accept Interfaces, Return Concrete Types

// Good — consumer defines what it needs
package notify
type Sender interface { Send(to, body string) error }
type Service struct{ s Sender }
func NewService(s Sender) *Service { return &Service{s: s} }

// Good — producer returns a concrete type
package email
type Client struct{ /* ... */ }
func New(cfg Config) *Client { /* ... */ }
func (c *Client) Send(to, body string) error { /* ... */ }

// Bad — producer defines and returns its own interface,
// forcing every consumer to depend on email.Sender.
func New(cfg Config) Sender { return &client{...} }

The exception is "expose an interface, hide the implementation": when a type has no exported methods beyond what the interface promises, returning the interface (func NewHash() hash.Hash32) is fine.

Keep Interfaces Small

Standard library interfaces are the model: io.Reader, io.Writer, io.Closer, fmt.Stringer, error — one or two methods each. Compose larger contracts:

type ReadWriteCloser interface { io.Reader; io.Writer; io.Closer }

If you find yourself writing a five-method interface, split it until each piece has a single reason to exist.

Compile-Time Satisfaction Check

var _ io.ReadWriter = (*MyBuffer)(nil)

Use when the type must satisfy an interface for correctness (custom JSON marshalling, http.Handler) and no other static use already enforces it. Don't add one for every interface.

Type Assertions and Type Switches

Always use the comma-ok form. Type switches re-declare the variable; cases with multiple types fall back to the interface type. Use optional-behaviour assertions to enhance a path without requiring the capability:

s, ok := v.(string)                              // comma-ok
switch x := v.(type) { case string: /* ... */ }  // type switch
if f, ok := w.(http.Flusher); ok { f.Flush() }   // optional behaviour

Embedding: Composition, Not Inheritance

Struct embedding promotes the inner type's methods and fields to the outer type. Use it deliberately — every promoted method becomes part of your public API.

type Server struct {
    *slog.Logger          // exposes Info/Warn/Error on Server
    addr string
}

Avoid embedding in exported types unless the promotion is the whole point. The inner type's method set is locked in once published.

Read references/embedding-and-receivers.md when designing struct embedding, overriding promoted methods, resolving name conflicts, or choosing between pointer and value receivers.

Dependency Injection via Interfaces

Constructors take interfaces; tests pass fakes. No DI container required.

type UserStore interface {
    FindByID(ctx context.Context, id string) (*User, error)
}

type UserService struct{ store UserStore }
func NewUserService(s UserStore) *UserService { return &UserService{store: s} }

The UserStore interface lives in the package that defines UserService. The concrete *pgUserStore lives in a database package and doesn't know UserService exists.

Preventing Accidental Copies

Structs that must not be copied (those holding a mutex, internal pointers, or a sync.WaitGroup) should embed a noCopy sentinel so go vet catches the mistake:

type noCopy struct{}
func (*noCopy) Lock()   {}
func (*noCopy) Unlock() {}

type ConnPool struct {
    _   noCopy
    mu  sync.Mutex
    /* ... */
}

Pass these by pointer (func process(p *ConnPool)), never by value.

Don't reach for `noCopy` reflexively. Plain value types (config structs, request DTOs, immutable snapshots) should be copyable — adding noCopy to them locks consumers into pointer-only APIs for no gain. The rule of thumb: if the struct owns a sync.Mutex, sync.WaitGroup, sync.Pool, internal chan, or a pointer that must stay unique (file handle, OS resource), embed noCopy. Otherwise leave it copyable.

Anti-Patterns

Verification Checklist

Before finishing an interface change:

• [ ] Interfaces are defined in the package that consumes them
• [ ] Constructors return concrete types (or hide a single unexported implementation behind a small interface)
• [ ] No interface has more than ~3 methods unless it composes named smaller ones
• [ ] Every type assertion uses the comma-ok form
• [ ] Pointer vs value receivers are consistent across all methods on a type
• [ ] Compile-time var _ I = (*T)(nil) exists where silent regressions would hurt
• [ ] Exported structs don't accidentally promote inner-type APIs through embedding

References

• references/consumer-owned-interfaces.md — where interfaces live and how to migrate
• references/embedding-and-receivers.md — embedding, overrides, pointer vs value receivers
• references/std-interfaces-cheatsheet.md — canonical signatures from the standard library