Why does adding a method to an exported Go interface break importers, when adding one to a struct does not?

## Why the two cases differ In Go a type satisfies an interface by having the right methods. There is no `implements` clause, no registration, and no list of implementers anywhere. That is the feature that makes small interfaces so pleasant to consume — and it is exactly what makes an exported interface almost impossible to change. When you publish ```go type Store interface { Get(ctx context.Context, key string) ([]byte, error) } ``` you have published a *requirement*: "one method, this signature". Every type in every downstream module that happens to have that method satisfies it. You cannot enumerate them, grep for them, or notify them. Adding `Delete` to the interface enlarges the requirement, and each of those types instantly fails to satisfy it. The failure is a compile error at every point where such a value is passed as a `Store`, typically reading `does not implement Store (missing method Delete)`. Adding a method to an exported **struct** is the mirror image. A method belongs to exactly one type; declaring `func (c *Client) Close() error` adds capability to `Client` and asks nothing of anyone. No existing call site changes meaning, no existing type needs new code. ## Why the blast radius is bigger than it looks The implementers who break are not only "real" ones. Every test fake counts. A downstream team that wrote a fifteen-line `fakeStore` for their unit tests now has a broken test build — and they will have several. In practice one line added to a widely imported interface produces failures across many packages and repositories at once, all of them in code you cannot fix. And the break is not opt-in the way people assume. Nobody is dragged onto your new version by publishing it alone, because Go's minimal version selection picks the highest version any requirement asks for, not the newest that exists. But the moment a team upgrades — or a *third* module they depend on bumps its requirement on you — the break arrives. ## There are no default methods Java added default methods to interfaces and C# added default interface members precisely so that interfaces could grow. Go has neither. An interface declaration in Go contains only method signatures and embedded interfaces; there is no body to supply. So there is no "compatible" way to add a method — the change is a break, always. ## The two real strategies **Seal the interface if you might grow it.** Include an unexported method in the interface: ```go type Event interface { Kind() string sealed() } ``` A type outside the declaring package cannot supply `sealed()` — unexported identifiers are not accessible across package boundaries — so only your package can implement `Event`. Since every implementer is yours, adding methods later breaks nobody outside. The standard library uses this shape; `testing.TB` includes an unexported method for exactly this reason, so that the `testing` package can extend it. The price is that consumers cannot write their own implementations at all, which is a real cost: it forbids test doubles as well as alternatives. Seal a *closed set* (an enum-like union of your own types), not an extension point. **Otherwise, add a second interface and upgrade at the call site.** Keep the published interface frozen and define the new capability separately: ```go type Deleter interface { Delete(ctx context.Context, key string) error } if d, ok := s.(Deleter); ok { // use the richer behaviour } else { // fall back } ``` This is the shape the standard library uses everywhere it needed to grow: `io.Writer` never gained a method, but `io.WriterTo`, `io.ReaderFrom` and `http.Flusher` let a value announce extra capability, and the consumer type-asserts for it. It costs you a branch and a fallback path, and it is the only additive option once an interface is out in the wild. ## Design consequences This is the strongest argument for keeping exported interfaces tiny. A one-method interface is a promise you can keep forever; a ten-method "service" interface is a promise you will want to break within two releases. It is also an argument for defining interfaces in the *consuming* package rather than exporting them from the producer: an interface that only you import is one you can change at will, because the compiler will show you every implementer — they are all in your own build. ## Adding a method is not always free even on a struct Two edge cases are worth knowing. If downstream code embeds your struct in its own type and that outer type already has a member of the same name at the same depth, a new method can make a selector ambiguous. And a new method can make your type unexpectedly satisfy an interface, changing which arm of a downstream type switch matches. Both are rare, and neither is in the same league as changing an interface, but they are the reason the honest answer is "adding a method to a struct is safe in practice" rather than "always safe".