Go Interfaces

Go Interfaces and Composition

Available Scripts

• `scripts/check-interface-compliance.sh` — Finds exported interfaces missing compile-time compliance checks (var _ I = (*T)(nil)). Run bash scripts/check-interface-compliance.sh --help for options.

---

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.

// Good: consumer defines the interface it needs
package consumer

type Thinger interface { Thing() bool }

func Foo(t Thinger) string { ... }

// Good: producer returns concrete type
package producer

type Thinger struct{ ... }
func (t Thinger) Thing() bool { ... }
func NewThinger() Thinger { return Thinger{ ... } }

// Bad: producer defines and returns its own interface
package producer

type Thinger interface { Thing() bool }
type defaultThinger struct{ ... }
func NewThinger() Thinger { return defaultThinger{ ... } }

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:

func NewHash() hash.Hash32 {
    return &myHash{}  // unexported type
}

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:

str, ok := value.(string)
if ok {
    fmt.Printf("string value is: %q\n", str)
}

To check if a value implements an interface:

if _, ok := val.(json.Marshaler); ok {
    fmt.Printf("value %v implements json.Marshaler\n", val)
}

---

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.

Read references/EMBEDDING.md when using struct embedding for composition, overriding embedded methods, resolving name conflicts, applying the HandlerFunc adapter pattern, or deciding whether to embed in public API types.

---

Interface Satisfaction Checks

Use a blank identifier assignment to verify a type implements an interface at compile time:

var _ json.Marshaler = (*RawMessage)(nil)

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.

Read references/RECEIVER-TYPE.md when deciding between pointer and value receivers for a new type, especially for types with sync primitives or large structs.

---

Quick Reference

---

Related Skills

• Interface naming: See go-naming when naming interfaces (the -er suffix convention) or choosing receiver names
• Error types: See go-error-handling when implementing the error interface, custom error types, or errors.As matching
• Generics vs interfaces: See go-generics when deciding whether generics are needed or an interface already suffices
• Functional options: See go-functional-options when using an interface-based Option pattern for flexible constructors
• Compile-time checks: See go-defensive when adding var _ I = (*T)(nil) satisfaction checks at API boundaries

Embedding Patterns in Go

Sources: Effective Go, Uber Style Guide

Go uses embedding for composition instead of inheritance. Embedding promotes the inner type's methods to the outer type, satisfying interfaces automatically.

Interface Embedding

Combine interfaces by embedding them:

type ReadWriter interface {
    Reader
    Writer
}

A ReadWriter can do what a Reader does and what a Writer does. Only interfaces can be embedded within interfaces.

Struct Embedding

Embedding promotes methods from the inner type to the outer type without explicit forwarding.

type ReadWriter struct {
    *Reader  // *bufio.Reader
    *Writer  // *bufio.Writer
}

With embedding, bufio.ReadWriter satisfies io.Reader, io.Writer, and io.ReadWriter automatically.

Mix embedded and named fields:

type Job struct {
    Command string
    *log.Logger
}

job.Println("starting now...")
job.Logger.SetPrefix("Job: ")

Method Overriding

Define a method on the outer type to override the promoted method:

func (job *Job) Printf(format string, args ...any) {
    job.Logger.Printf("%q: %s", job.Command, fmt.Sprintf(format, args...))
}

The outer method takes precedence — calls to job.Printf(...) invoke the outer method, while the embedded method is still accessible via job.Logger.Printf(...).

Embedding vs Subclassing

When an embedded method is invoked, the receiver is the inner type, not the outer one. The embedded type has no knowledge that it is embedded — there is no equivalent to this or super referencing the containing type.

type Base struct{}
func (b *Base) Name() string { return "Base" }

type Derived struct{ Base }

d := Derived{}
d.Name() // returns "Base", not "Derived"

Name Conflict Resolution

1. Outer hides inner — Fields or methods on the outer type shadow those promoted from an embedded type at the same name 2. Same-level conflicts are errors — If two embedded types at the same depth promote the same name, it is a compile error (unless the name is never accessed)

type A struct{}
func (A) Hello() string { return "A" }

type B struct{}
func (B) Hello() string { return "B" }

type C struct {
    A
    B
}

// c.Hello()  // compile error: ambiguous selector
c.A.Hello()   // OK: explicit disambiguation

Don't Embed in Public Structs

Embedding exposes the inner type's full method set as part of your public API. This creates a maintenance burden: changes to the embedded type's methods break your API's compatibility guarantees.

Bad

type SMap struct {
    sync.Mutex  // Lock and Unlock are now part of SMap's API
    data map[string]string
}

Good

type SMap struct {
    mu   sync.Mutex  // unexported field — implementation detail
    data map[string]string
}

func (m *SMap) Get(k string) string {
    m.mu.Lock()
    defer m.mu.Unlock()
    return m.data[k]
}

Exception: Embedding is acceptable in test types and internal structs where API stability is not a concern.

The HandlerFunc Adapter Pattern

Methods can be defined on any named type, not just structs. The http.HandlerFunc pattern converts an ordinary function into an interface implementation:

type HandlerFunc func(ResponseWriter, *Request)

func (f HandlerFunc) ServeHTTP(w ResponseWriter, req *Request) {
    f(w, req)
}

Any function with the right signature becomes an HTTP handler:

http.Handle("/args", http.HandlerFunc(ArgServer))

This adapter pattern is useful whenever you need a single-method interface satisfied by a standalone function.

Receiver Type: Pointer vs Value

Advisory: Go Wiki CodeReviewComments

Choosing whether to use a value or pointer receiver on methods can be difficult. If in doubt, use a pointer, but there are times when a value receiver makes sense.

When to Use Pointer Receiver

• Method mutates receiver: The receiver must be a pointer
• Receiver contains sync.Mutex or similar: Must be a pointer to avoid copying
• Large struct or array: A pointer receiver is more efficient. If passing all

elements as arguments feels too large, it's too large for a value receiver

• Concurrent or called methods might mutate: If changes must be visible in

the original receiver, it must be a pointer

• Elements are pointers to something mutating: Prefer pointer receiver to

make the intention clearer

When to Use Value Receiver

• Small unchanging structs or basic types: Value receiver for efficiency
• Map, func, or chan: Don't use a pointer to them
• Slice without reslicing/reallocating: Don't use a pointer if the method

doesn't reslice or reallocate the slice

• Small value types with no mutable fields: Types like time.Time with no

mutable fields and no pointers work well as value receivers

• Simple basic types: int, string, etc.

// Value receiver: small, immutable type
type Point struct {
    X, Y float64
}

func (p Point) Distance(q Point) float64 {
    return math.Hypot(q.X-p.X, q.Y-p.Y)
}

// Pointer receiver: method mutates receiver
func (p *Point) ScaleBy(factor float64) {
    p.X *= factor
    p.Y *= factor
}

// Pointer receiver: contains sync.Mutex
type Counter struct {
    mu    sync.Mutex
    count int
}

func (c *Counter) Increment() {
    c.mu.Lock()
    c.count++
    c.mu.Unlock()
}

Consistency Rule

Don't mix receiver types. Choose either pointers or struct types for all available methods on a type. If any method needs a pointer receiver, use pointer receivers for all methods.

// Good: Consistent pointer receivers
type Buffer struct {
    data []byte
}

func (b *Buffer) Write(p []byte) (int, error) { /* ... */ }
func (b *Buffer) Read(p []byte) (int, error)  { /* ... */ }
func (b *Buffer) Len() int                     { return len(b.data) }

// Bad: Mixed receiver types
func (b Buffer) Len() int                      { return len(b.data) }  // inconsistent