go-interfaces

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?

Situation	Verdict
Single implementation, no tests need to swap it	No interface. Use the concrete type.
Second implementation appears (or is imminent)	Extract an interface in the consumer package.
Test needs to fake an external dependency	Define a small interface in the consumer; pass a fake.
You want to expose optional behaviour (Flusher, ReaderFrom)	Define a tiny interface; check with _, ok := v.(Iface).
You want a stable plugin/SPI boundary	Yes, but keep it minimal and version it explicitly.

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 { /* ... */ }