Interfaces

What an interface is

An interface is a set of method signatures — a named contract of behavior. A type satisfies it by having those methods; there is no implements keyword and no explicit link:

type Stringer interface {
	String() string
}

type Point struct{ X, Y int }

// Point now satisfies Stringer — automatically, no declaration
func (p Point) String() string {
	return fmt.Sprintf("(%d, %d)", p.X, p.Y)
}

This is structural typing (often called duck typing, checked at compile time): if it has the methods, it fits. The payoff is decoupling — you can satisfy interfaces you’ve never heard of, including fmt.Stringer and io.Writer from the standard library, without those packages knowing your type exists. A producer of a type and a consumer that needs a behavior never have to agree on a shared base class; they only have to agree on a method shape.

Polymorphism through an interface

Write a function that takes the interface, and every implementer flows through the same code — no switch, no inheritance hierarchy:

graph TD
SHAPE["Shape interface { Area() float64 }"]
CIRCLE["Circle"] -->|satisfies| SHAPE
RECT["Rectangle"] -->|satisfies| SHAPE
SHAPE --> FN["totalArea(shapes []Shape)"]

package main

import (
"fmt"
"math"
)

// A small interface: one method.
type Shape interface {
Area() float64
}

type Circle struct{ R float64 }

func (c Circle) Area() float64 { return math.Pi * c.R * c.R }

type Rectangle struct{ W, H float64 }

func (r Rectangle) Area() float64 { return r.W * r.H }

// One function, any Shape — even types added later, in other packages.
func totalArea(shapes []Shape) float64 {
var sum float64
for _, s := range shapes {
	sum += s.Area() // dynamic dispatch: the concrete Area() is chosen at runtime
}
return sum
}

func main() {
shapes := []Shape{Circle{R: 2}, Rectangle{W: 3, H: 4}}
fmt.Printf("total area: %.2f\n", totalArea(shapes)) // 24.57
}

Under the hood: the (type, value) pair

An interface value isn’t magic — it’s a two-word structure: a dynamic type (a pointer to the concrete type’s method table) and a value (the data, or a pointer to it). Calling a method looks up the implementation in that table — dynamic dispatch:

graph LR
IV["interface value (Shape)"] --> T["type → *Circle's method table"]
IV --> V["value → Circle{R:2}"]
T --> M["Area() implementation"]

Three consequences fall out of this model:

• Comparisons: two interface values are equal when their types and values are equal. An interface is nil only when both halves are nil (the trap below).
• Boxing: storing a concrete value in an interface may copy it to the heap so the pointer is stable — a small allocation. In tight loops this can matter.
• Dispatch cost: an interface call is an indirect call through the table, slightly more expensive than a direct call and not inlinable. Real, but rarely your bottleneck.

Method sets decide who satisfies

Whether a type satisfies an interface depends on its method set, and that differs for T versus *T. The rule: the method set of *T includes both value- and pointer-receiver methods; the method set of T includes only value-receiver methods. So a pointer-receiver method means only a pointer satisfies the interface:

package main

import "fmt"

type Speaker interface{ Speak() string }

type Dog struct{ Name string }

// POINTER receiver — so only *Dog is in Speaker's method set
func (d *Dog) Speak() string { return d.Name + " says woof" }

func main() {
d := Dog{Name: "Rex"}

var s Speaker = &d // OK: *Dog has Speak
fmt.Println(s.Speak())

// var bad Speaker = d  // compile error:
//   Dog does not implement Speaker (Speak has pointer receiver)

// the practical rule: if any method needs a pointer receiver,
// pass pointers when you store the type in an interface.
fmt.Println("does value Dog satisfy Speaker?", false)
}

This is the single most common “why won’t this compile?” with interfaces — see methods for when to choose each receiver.

The empty interface and type switches

The empty interface interface{} — spelled any since Go 1.18 — has no methods, so every type satisfies it. It’s the escape hatch for “a value whose type I don’t know yet”: JSON decoding, fmt.Println’s arguments, generic containers before generics. You recover the concrete type with a type assertion or a type switch:

package main

import "fmt"

// describe inspects a value of unknown type at runtime.
func describe(v any) string {
switch x := v.(type) { // x is typed inside each case
case nil:
	return "nil"
case int:
	return fmt.Sprintf("int: %d", x)
case string:
	return fmt.Sprintf("string of length %d", len(x))
case fmt.Stringer:
	return "Stringer: " + x.String() // interfaces work as cases too
default:
	return fmt.Sprintf("other type %T", x)
}
}

func main() {
for _, v := range []any{42, "go", 3.14, nil} {
	fmt.Println(describe(v))
}
}

Reach for any sparingly — it discards the type system. With Go 1.18+ generics, many old uses of any (containers, utility functions) are better expressed with type parameters; see type assertions for the full mechanics.

Composing small interfaces

Idiomatic Go favors small interfaces — the most powerful have a single method (io.Writer, io.Reader, fmt.Stringer, error). You build bigger contracts by embedding them:

// io.ReadWriter is literally two one-method interfaces glued together
type ReadWriter interface {
	Reader // Read(p []byte) (int, error)
	Writer // Write(p []byte) (int, error)
}

A type satisfies the composed interface exactly when it satisfies each embedded one. This is why so much of the standard library interoperates: a *os.File, a *bytes.Buffer, and a net.Conn are all io.ReadWriters, so anything written against that interface works with all of them. See embedding for the full mechanics.

Implementing a standard-library interface

The real power of structural typing: implement a stdlib interface and instantly plug into stdlib machinery. Give a type Len, Less, and Swap and sort.Sort will sort it:

package main

import (
"fmt"
"sort"
)

// ByLen is []string with the three methods sort.Interface requires.
type ByLen []string

func (s ByLen) Len() int           { return len(s) }
func (s ByLen) Less(i, j int) bool { return len(s[i]) < len(s[j]) }
func (s ByLen) Swap(i, j int)      { s[i], s[j] = s[j], s[i] }

func main() {
words := ByLen{"banana", "kiwi", "fig", "apple"}
sort.Sort(words) // sort.Sort works on ANY sort.Interface — no generics needed
fmt.Println(words) // [fig kiwi apple banana]
}

The interfaces worth knowing by heart:

Designing good interfaces

• Keep them small. One or two methods compose and mock far better than a twelve-method “manager.” The bigger an interface, the fewer types satisfy it and the more it couples.
• Define them at the consumer. An interface belongs next to the code that needs the behavior, not next to the type that provides it. The provider returns a concrete struct; the consumer declares the little interface it depends on.
• Accept interfaces, return structs. Be liberal in what you take, concrete in what you give back — so callers keep the full method set and you keep freedom to extend.
• Don’t add an interface “just in case.” A single implementation needs no interface; introduce one when a second implementation or a test seam actually appears. Premature interfaces (“interface pollution”) add indirection with no payoff.

The nil-interface trap

var p *MyError = nil
var err error = p       // err holds (*MyError, nil)
fmt.Println(err == nil) // false! — the famous typed-nil bug

🐞 Fix the bug

The most famous interface gotcha in Go: a typed nil inside an interface is not nil. Valid input still takes the error branch here. Edit until Run & check matches.

valid input

package main

import "fmt"

type validationError struct{ msg string }

func (e *validationError) Error() string { return e.msg }

func validate(input string) error {
var err *validationError
if input == "" {
	err = &validationError{"input is empty"}
}
return err
}

func main() {
if err := validate("gopher"); err != nil {
	fmt.Println("failed:", err)
	return
}
fmt.Println("valid input")
}

Next: how types borrow behavior by embedding others — struct & interface embedding.

Related topics