Lesson 1: Go Interfaces: Implicit Satisfaction

Why This Matters #

Open the Kubernetes source code and you'll see this pattern everywhere:

type Client interface {
    Get(ctx context.Context, key ObjectKey, obj Object, opts ...GetOption) error
    List(ctx context.Context, list ObjectList, opts ...ListOption) error
    Create(ctx context.Context, obj Object, opts ...CreateOption) error
    Update(ctx context.Context, obj Object, opts ...UpdateOption) error
    Delete(ctx context.Context, obj Object, opts ...DeleteOption) error
}

That's not a class hierarchy. It's not an abstract base class. It's a Go interface. And understanding how it works — deeply — is the difference between writing Go and writing idiomatic Go.

The Core Idea: Implicit Satisfaction #

In Java or C#, you write class Foo implements Bar. The type declares that it implements the interface. The relationship is explicit and bidirectional.

Go flips this: the interface defines what it needs, and any type that happens to have those methods automatically satisfies it. The type doesn't even need to know the interface exists.

This is called implicit interface satisfaction, and it's arguably the most important design decision in Go. Effective Go §

A Concrete Example #

// Define an interface: anything that can Speak
type Speaker interface {
    Speak() string
}

// Dog has a Speak method — it satisfies Speaker automatically
type Dog struct {
    Name string
}

func (d Dog) Speak() string {
    return d.Name + " says woof!"
}

// Cat also satisfies Speaker
type Cat struct {
    Name string
}

func (c Cat) Speak() string {
    return c.Name + " says meow!"
}

// This function accepts ANYTHING that can Speak
func MakeItSpeak(s Speaker) {
    fmt.Println(s.Speak())
}

func main() {
    MakeItSpeak(Dog{"Rex"})   // Rex says woof!
    MakeItSpeak(Cat{"Whiskers"}) // Whiskers says meow!
}

Interface Syntax #

Declaring an Interface #

type InterfaceName interface {
    MethodName(param Type) ReturnType
    OtherMethod(param1 Type1, param2 Type2) (ReturnType, error)
}

Implementing an Interface #

You implement an interface by defining methods on a type. The receiver type matters:

type Counter struct {
    value int
}

// Value receiver:
func (c Counter) Value() int { return c.value }
// Both Counter AND *Counter satisfy interfaces with Value()

// Pointer receiver:
func (c *Counter) Increment() { c.value++ }
// Only *Counter satisfies interfaces with Increment()

Compile-Time Interface Checks #

Use this pattern to verify at compile time that a type satisfies an interface:

var _ io.Reader = (*MyReader)(nil)  // *MyReader must implement io.Reader
var _ io.Reader = MyReader{}        // MyReader must implement io.Reader

If the type doesn't satisfy the interface, the code won't compile. This is cheap documentation and a safety net.

The Most Important Interface: io.Reader #

If you learn one interface in Go, make it this one:

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

That's it. One method. Two return values. And it's the backbone of all I/O in Go.

Implementing Your Own io.Reader #

type UpperReader struct {
    source string
    pos    int
}

func (r *UpperReader) Read(p []byte) (int, error) {
    if r.pos >= len(r.source) {
        return 0, io.EOF
    }
    n := copy(p, strings.ToUpper(r.source[r.pos:]))
    r.pos += n
    return n, nil
}

func main() {
    r := &UpperReader{source: "hello"}
    io.Copy(os.Stdout, r)  // Prints: HELLO
}

Because UpperReader implements io.Reader, it works with io.Copy, io.ReadAll, bufio.NewScanner, and every other function in the standard library that accepts an io.Reader.

Interface Composition #

You can embed interfaces inside other interfaces:

type ReadWriter interface {
    io.Reader
    io.Writer
}

type ReadWriteCloser interface {
    io.Reader
    io.Writer
    io.Closer
}

A type satisfies ReadWriter if it has both Read and Write methods. Composition, not inheritance.

This is how the standard library builds up complex interfaces from simple ones. io.ReadWriteCloser is just Reader + Writer + Closer.

The Empty Interface (any) #

interface{} — now also written as any (since Go 1.18) — is satisfied by every type. It's Go's universal container, but use it sparingly.

var x any
x = "hello"
x = 42
x = Dog{Name: "Rex"}

// To get the value back, use a type assertion:
s, ok := x.(string)  // ok=false because x is a Dog now

// Or a type switch:
switch v := x.(type) {
case string:  fmt.Println("string:", v)
case int:     fmt.Println("int:", v)
default:   fmt.Printf("%T: %v\n", v, v)
}

Interface Design Principles #

1. Accept interfaces, return structs #

// GOOD: callers can pass anything that reads
func ProcessData(r io.Reader) error { ... }

// GOOD: returns a concrete type, caller can still treat as interface
func NewStore() *FileStore { ... }

// BAD (usually): returning an interface limits what callers can do
func NewStore() Store { ... }

2. Keep interfaces small #

The most powerful interfaces in Go's standard library have 1–3 methods. io.Reader: 1 method. io.Writer: 1 method. fmt.Stringer: 1 method.

3. Define interfaces where they're used, not where they're implemented #

This is a direct consequence of implicit satisfaction. The consumer decides what interface it needs — the producer doesn't declare anything.

4. Naming conventions #

• Single-method interfaces: method name + er → Reader, Writer, Stringer, Marshaler
• Multi-method interfaces: describe what they do → ReadWriter, Handler, Client

5. The nil interface trap #

var r io.Reader          // nil interface (type=nil, value=nil)
var b *bytes.Buffer      // nil pointer
r = b                     // r is NOT nil! (type=*bytes.Buffer, value=nil)
fmt.Println(r == nil)  // false!

An interface is nil only when both its dynamic type and dynamic value are nil. A nil pointer stored in an interface makes the interface non-nil.

Interfaces in Cloud-Native Go #

Let's look at a real pattern from the Kubernetes controller-runtime library:

// From sigs.k8s.io/controller-runtime/pkg/client
type Client interface {
    Get(ctx context.Context, key ObjectKey, obj Object, opts ...GetOption) error
    List(ctx context.Context, list ObjectList, opts ...ListOption) error
    Create(ctx context.Context, obj Object, opts ...CreateOption) error
    Update(ctx context.Context, obj Object, opts ...UpdateOption) error
    Patch(ctx context.Context, obj Object, patch Patch, opts ...PatchOption) error
    Delete(ctx context.Context, obj Object, opts ...DeleteOption) error
    DeleteAllOf(ctx context.Context, obj Object, opts ...DeleteAllOfOption) error
    Status() StatusWriter
    SubResource(subResource string) SubResourceClient
    Scheme() *runtime.Scheme
    RESTMapper() meta.RESTMapper
    GroupVersionKindFor(obj runtime.Object) (schema.GroupVersionKind, error)
    IsObjectNamespaced(obj runtime.Object) (bool, error)
}

Yes, this is a large interface — a pragmatic exception to the "keep it small" rule when you genuinely need all these operations. But notice the pattern:

• Controllers depend on Client, not on a concrete implementation. This means you can test a controller with a fake client.
• Multiple implementations exist: A real client that talks to the API server, a fake client for tests, a dry-run client, a delegating client.
• The interface is defined at the consumption point — in the controller-runtime library, not in the API server.

Practice #

Quick Check #

What's Next? #

You now understand the most fundamental abstraction in Go. In the next lesson, we'll tackle error handling — because in Go, error is just an interface:

type error interface {
    Error() string
}

Everything you learned here applies directly — error wrapping, sentinel errors, custom error types, and the patterns used in production Go code.

Ask Questions #

Your teaching agent is here to help. If anything was unclear, ask now. Want to check your exercise code? Paste it and I'll review it. Want to understand why Kubernetes made that Client interface so large? Ask.