How Go interfaces work

An interface is a type that specifies method signatures. No implementation, just the contract.

type Speaker interface {
    Speak() string
}

Any type that has a Speak() string method satisfies Speaker. That's it. No declaration needed.

type Dog struct{ Name string }

func (d Dog) Speak() string {
    return "Woof! My name is " + d.Name
}

type Cat struct{ Name string }

func (c Cat) Speak() string {
    return "Meow! Call me " + c.Name
}

func main() {
    var s Speaker
    s = Dog{Name: "Rex"}
    fmt.Println(s.Speak())  // Woof! My name is Rex
    s = Cat{Name: "Whiskers"}
    fmt.Println(s.Speak())  // Meow! Call me Whiskers
}

Go checks at compile time: "Does Dog have all the methods Speaker requires?" Yes? Then Dog is a Speaker.

Why small interfaces matter

The Go standard libraryWhat is standard library?A collection of ready-made tools that come built into a language - no install required. Covers common tasks like reading files or making web requests. Ask AI for more is famous for tiny, focused interfaces:

One method each. This is intentional.

> // AI generates this -- too rigid
> type Database interface {
>     Connect() error
>     Query(string) ([]Row, error)
>     Insert(Row) error
>     Update(Row) error
>     Delete(int) error
>     Close() error
> }
>
> // Idiomatic Go -- small, composable
> type Querier interface {
>     Query(string) ([]Row, error)
> }
>
> type Inserter interface {
>     Insert(Row) error
> }
>

Evaluating AI interface design

When AI generates interfaces, run through this checklist:

The last point deserves emphasis: accept interfaces, return structs.

// Good: accepts any io.Reader, returns concrete type
func ReadConfig(r io.Reader) (*Config, error) { ... }

// Bad: returns an interface (hides what you actually get)
func NewReader() io.Reader { ... }

Interface composition

You can embed interfaces within other interfaces to compose behavior:

type Reader interface {
    Read(p []byte) (n int, err error)
}

type Writer interface {
    Write(p []byte) (n int, err error)
}

type ReadWriter interface {
    Reader
    Writer
}

This is how io.ReadWriteCloser is defined in the standard libraryWhat is standard library?A collection of ready-made tools that come built into a language - no install required. Covers common tasks like reading files or making web requests. Ask AI for more. Any type implementing both Read and Write automatically satisfies ReadWriter.

The nil interface trap

An interface value is actually a pair: (concrete type, concrete value). This creates one of Go's most infamous gotchas:

type Thing struct{}

func (t *Thing) Method() {}

var thing *Thing = nil
var i interface{} = thing

fmt.Println(i == nil)  // false! The interface holds (*Thing, nil)

The interface knows the type (*Thing) even though the value is nil. So the interface itself isn't nil.

> func GetThing() error {
>     var err *MyError = nil
>     // ... some logic that might set err ...
>     return err  // Returns (*MyError, nil) -- NOT a nil error!
> }
>
> if err := GetThing(); err != nil {
>     // This executes even when there's no error!
> }
>

> func GetThing() error {
>     // ... some logic ...
>     return nil  // Returns (nil, nil) -- truly nil interface
> }
>

The empty interface and any

The empty interface interface{} (or its alias any since Go 1.18) matches every type:

func AcceptAnything(x any) {
    fmt.Printf("Received: %v (type: %T)\n", x, x)
}

AcceptAnything(42)           // int
AcceptAnything("hello")      // string
AcceptAnything([]int{1,2,3}) // slice

You'll see any in JSONWhat is json?A text format for exchanging data between systems. It uses key-value pairs and arrays, and every programming language can read and write it. Ask AI for more unmarshaling, generic containers, and reflection code. It's powerful but throws away type safety.

Common interface patterns

The error interface

The built-in error type is an interface. Any type with an Error() string method qualifies:

type ValidationError struct {
    Field   string
    Message string
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("validation error in %s: %s", e.Field, e.Message)
}

func ValidateAge(age int) error {
    if age < 0 {
        return &ValidationError{Field: "age", Message: "cannot be negative"}
    }
    return nil
}

Sorting with sort.Interface

type ByAge []Person

func (a ByAge) Len() int           { return len(a) }
func (a ByAge) Swap(i, j int)      { a[i], a[j] = a[j], a[i] }
func (a ByAge) Less(i, j int) bool { return a[i].Age < a[j].Age }

people := []Person{{"Alice", 30}, {"Bob", 25}}
sort.Sort(ByAge(people))

Quick reference