Embedding interfaces in interfaces

Embedding an interface in another interface is the simplest kind of embedding
in Go, because interfaces only declare capabilities; they don’t actually
define any new data or behavior for a type.

Let’s start with the example listed in Effective Go, because it presents a
well known case of interface embedding in the Go standard library. Given the
io.Reader and io.Writer interfaces:

How do we define an interface for a type that’s both a reader and a writer? An
explicit way to do this is:

Apart from the obvious issue of duplicating the same method declarations in
several places, this hinders the readability of ReadWriter because it’s not
immediately apparent how it composes with the other two interfaces. You either
have to remember the exact declaration of each method by heart or keep looking
back at other interfaces.

Note that there are many such compositional interfaces in the standard
library; there’s io.ReadCloser, io.WriteCloser, io.ReadWriteCloser,
io.ReadSeeker, io.WriteSeeker, io.ReadWriteSeeker and more in other
packages. The declaration of the Read method alone would likely have to be
repeated more than 10 times in the standard library. This would be a shame, but
luckily interface embedding provides the perfect solution:

In addition to preventing duplication, this declaration states intent in
the clearest way possible: in order to implement ReadWriter, you have to
implement Reader and Writer.

Fixing overlapping methods in Go 1.14

Embedding interfaces is composable and works as you’d expect. For example,
given the interfaces A, B, C and D such that:

The method set of D will
consist of Amethod(), Bmethod(), Cmethod() and Dmethod().

However, suppose C were defined as:

Generally speaking, this shouldn’t change the method set of D. However,
prior to Go 1.14 this would result in an error “Duplicate method Amethod”
for D, because Amethod() would be declared twice – once through the
embedding of B and once through the embedding of C.

Go 1.14 fixed this
and these days the new example works and just as we’d expect. The
method set of D is the union of the method sets of the interfaces it
embeds and of its own methods.

A more practical example comes from the standard library. The type
io.ReadWriteCloser is defined as:

But it could be defined more succinctly with:

Prior to Go 1.14 this wouldn’t have been possible due to the duplication of
method Close() coming in from io.ReadCloser and again from
io.WriteCloser.

Example: net.Error

The net package has its own error interface declared thus:

Note the embedding of the built-in error interface. This embedding declares
intent very clearly: a net.Error is also an error. Readers of the code
wondering whether they can treat it as such have an immediate answer, instead
of having to look for a declaration of an Error() method and mentally
compare it to the canonical one in error.

Example: heap.Interface

The heap package has the following interface declared for client types to
implement:

All types implementing heap.Interface must also implement
sort.Interface; the latter requires 3 methods, so writing heap.Interface
without the embedding would look like:

The version with the embedding is superior on many levels. Most importantly,
it makes it immediately clear that a type has to implement sort.Interface
first; this information is much more tricky to pattern-match from the longer
version.