Use when defining or implementing Go interfaces, designing abstractions, creating mockable boundaries for testing, or composing types through embedding. Also use when deciding whether to accept an interface or return a concrete type, or using type assertions or type switches, even if the user doesn'

Go Interfaces and Composition Resource Routing scripts/check interface compliance.sh Run as a heuristic to find exported interfaces that may need compile time assertions. scripts/check interface compliance.go Implementation helper invoked by check interface compliance.sh ; patch this when changing method set analysis. references/EMBEDDING.md Read when embedding interfaces or structs in public APIs. references/RECEIVER TYPE.md Read when pointer/value receivers affect interface satisfaction. Accept Interfaces, Return Concrete Types Interfaces belong in the package that consumes values, not the package that implements them. Return concrete (usually pointer or struct) types from constructors so new methods can be added without refactoring. Do not define interfaces before they are used. Without a realistic example of usage, it is too difficult to see whether an interface is even necessary. Generality: Hide Implementation, Expose Interface If a type exists only to implement an interface with no exported methods beyond that interface, return the interface from constructors to hide the implementation: Benefits: implementation can change without affecting callers, substituting algorithms requires only changing the constructor call. Type Assertions: Comma Ok Idiom Without checking, a failed assertion causes a runtime panic. Always use the comma ok idiom to test safely: To check if a value implements an interface: Type Switch It's idiomatic to reuse the variable name ( t := t.(type) ) — the variable has the correct type in each case branch. When a case lists multiple types ( case int, int64: ), the variable has the interface type. Embedding Avoid embedding types in public structs — the inner type's full method set becomes part of your public API. Use unexported fields instead. Interface Satisfaction Checks Use a blank identifier assignment to verify a type implements an interface at compile time: This causes a compile error if RawMessage doesn't implement json.Marshaler . Use this pattern when: There are no static conversions that would verify the interface automatically The type must satisfy an interface for correct behavior (e.g., custom JSON marshaling) Interface changes should break compilation, not silently degrade Don't add these checks for every interface — only when no other static conversion would catch the error. Validation : After defining interfaces or implementations, run bash scripts/check interface compliance.sh to verify all concrete types have compile time var I = ( T)(nil) checks. Receiver Type If in doubt, use a pointer receiver. Don't mix receiver types on a single type — if any method needs a pointer, use pointers for all methods. Use value receivers only for small, immutable types ( Point , time.Time ) or basic types. Quick Reference Concept Pattern Notes Consumer owns interface Define interfaces where used Not in the implementing package Safe type assertion v, ok := x.(Type) Returns zero value + false Type switch switch v := x.(type) Variable has correct type per case Interface embedding type RW interface { Reader; Writer } Union of methods Struct embedding type S struct { T } Promotes T's methods Interface check var I = ( T)(nil) Compile time verification Generality Return interface from constructor Hide implementation Related Skills Interface naming : See [go naming](../go naming/SKILL.md) when naming interfaces (the er suffix convention) or choosing receiver names Error types : See [go error handling](../go error handling/SKILL.md) when implementing the error interface, custom error types, or errors.As matching Generics vs interfaces : See [go generics](../go generics/SKILL.md) when deciding whether generics are needed or an interface already suffices Functional options : See [go functional options](../go functional options/SKILL.md) when using an interface based Option pattern for flexible constructors Defensive boundaries : See [go defensive](../go defensive/SKILL.md) when interface assertions are one part of a broader API boundary hardening pass

go-interfaces