Learn coding concepts by building real projects with modern technologies

Best Practices for Interfaces in Go

By Lane Wagner on Mar 15, 2020

Interfaces in Go allow us to treat different types as the same data type temporarily because both types implement the same kind of behavior. They’re central to a Go programmer’s toolbelt and are often used improperly by new Go developers, which leads to unreadable and often buggy code.

What is an interface in Golang?

In Go, an interface is a custom type that other types are able to implement, which gives Go developers a powerful way to use abstraction. Interfaces are named collections of method signatures, and when other types implement all the required methods, they implicitly implement the interface.

For example, errors in Go are interfaces, and the standard error interface is simple, all a type needs to do to be considered an error is define an Error() method that accepts no parameters and returns a string.

type error interface {
    Error() string
}

The simplicity of the error interface makes writing logging and metrics implementations much easier. Let’s define a struct that represents a network problem:

type networkProblem struct {
	message string
	code    int
}

Then we can define an Error() method:

func (np networkProblem) Error() string {
	return fmt.Sprintf("network error! message: %s, code: %v", np.message, np.code)
}

Now, we can use an instance of the networkProblem struct wherever an error is accepted.

func handleErr(err error) {
	fmt.Println(err.Error())
}

np := networkProblem{
	message: "we received a problem",
	code:    404,
}

handleErr(np)

// prints "network error! message: we received a problem, code: 404"

Learn Go by writing Go code

I'm a senior engineer learning Go, and the pace of Boot.dev's Go Mastery courses has been perfect for me. The diverse community in Discord makes the weekly workshops a blast, and other members are quick to help out with detailed answers and explanations.

- Daniel Gerep from Cassia, Brasil

Best practices for writing interfaces

Writing clean interfaces is hard. Frankly, anytime you’re dealing with abstractions in code, the simple can become complex very quickly if you’re not careful. Let’s go over some rules of thumb for keeping interfaces clean.

  1. Keep interfaces small
  2. Interfaces should have no knowledge of satisfying types
  3. Interfaces are not classes

1. Keep Interfaces Small

If there is only one piece of advice that you take away from this article, make it this: keep interfaces small! Interfaces are meant to define the minimal behavior necessary to accurately represent an idea or concept.

Here is an example from the standard HTTP package of a larger interface that’s a good example of defining minimal behavior:

type File interface {
    io.Closer
    io.Reader
    io.Seeker
    Readdir(count int) ([]os.FileInfo, error)
    Stat() (os.FileInfo, error)
}

Any type that satisfies the interface’s behaviors can be considered by the HTTP package as a File. This is convenient because the HTTP package doesn’t need to know if it’s dealing with a file on disk, a network buffer, or a simple []byte.

2. Interfaces Should Have No Knowledge of Satisfying Types

An interface should define what is necessary for other types to classify as a member of that interface. They shouldn’t be aware of any types that happen to satisfy the interface at design time.

For example, let’s assume we are building an interface to describe the components necessary to define a car.

type car interface {
	Color() string
	Speed() int
	IsFiretruck() bool
}

Color() and Speed() make perfect sense, they are methods confined to the scope of a car. IsFiretruck() is an anti-pattern. We are forcing all cars to declare whether or not they are firetrucks. In order for this pattern to make any amount of sense, we would need a whole list of possible subtypes. IsPickup(), IsSedan(), IsTank()… where does it end??

Instead, the developer should have relied on the native functionality of type assertion to derive the underlying type when given an instance of the car interface. Or, if a sub-interface is needed, it can be defined as:

type firetruck interface {
	car
	HoseLength() int
}

Which inherits the required methods from car and adds one additional required method to make the car a firetruck.

3. Interfaces Are Not Classes

Additional information about interfaces

The empty interface

The empty interface doesn’t specify any methods, and as such every type in Go implements the empty interface.

interface{}

It’s for this reason that developers sometimes use a map[string]interface{} to work with arbitrary JSON data, although I recommend using anonymous structs instead where possible.

Zero value of an interface

Interfaces can be nil, in fact, it’s their zero value. That’s why when we check for errors in Go, we’re always checking if err != nil, because err is an interface.

Interfaces on pointers

It’s a common “gotcha” in Go to implement a method on a pointer type and expect the underlying type to implement the interface, it doesn’t work like that.

type rectangle interface {
    height() int
    width() int
}

type square struct {
    length int
}

func (sq *square) width() int {
    return sq.length
}

func (sq *square) height() int {
    return sq.length
}

Though you may expect it to, in this example the square type does not implement the rectangle interface. The *square type does. If I wanted the square type to implement the rectangle interface I would just need to remove the pointer receivers.

type rectangle interface {
    height() int
    width() int
}

type square struct {
    length int
}

func (sq square) width() int {
    return sq.length
}

func (sq square) height() int {
    return sq.length
}

Learn to code by building real projects

Related Reading