You own a Go package many teams import. Should you export an interface for their fakes, or a concrete type?

## The decision You are writing a package other teams import — a client, a store, a service wrapper. They will need to test their code without your real dependency. Two shapes are available: 1. **Export an interface** (`type Client interface { ... }`) and have your constructor return it, so consumers can implement it in their tests. 2. **Return a concrete type** (`*Client`) and let each consumer declare, in its own package, the one or two methods it calls. Both are testable. They differ in who can change what afterwards, and that is the whole question. ## Why exporting the interface is the expensive choice An exported interface that others implement is API in the strongest sense. Its method *list* is part of the contract, not just each method's signature. Adding a method — the most ordinary thing that happens to a growing package — breaks every implementation outside your module. Test fakes are implementations, so the blast radius is not "a few adapters", it is every consumer's test suite. The timing is what makes it an organisational problem rather than a technical one. The breakage does not land when you merge; it lands when each team upgrades, weeks apart, in repositories you cannot see or fix. You have created work you cannot schedule, on teams you do not manage, and the failure they see is a compile error in *their* test file with your package's name on it. You also cannot take it back. Un-exporting the interface, or narrowing it, breaks the consumers who now name it in their own signatures. The choice is irreversible in the direction that matters. ## Why the concrete type keeps your options open Return `*Client`, and you can add methods whenever you like: no consumer implements your type, so nothing downstream can break from a method being added. Each consumer declares its own view of what it uses: ```go // in the consumer's package type userFetcher interface { UserByID(ctx context.Context, id int64) (User, error) } ``` Your concrete type satisfies it without knowing it exists. Two consumers can hold different views of the same type. When you add a method, their interfaces are unchanged, their fakes are unchanged, and nobody upgrades in a hurry. The cost is real but small: consumers write a couple of lines each, and there is no single canonical name for the abstraction. The saving is that you keep the right to evolve. ## When exporting an interface is correct Three cases justify it, and they share a property: your package is the one *consuming* the abstraction. - **You accept implementations.** A parameter or a registration function takes something callers provide. Then the interface is genuinely yours to declare, and it should be tiny. - **You legitimately ship several implementations** behind one name and callers choose among them at runtime. - **A standard shape already exists.** Accepting an `io.Reader` or a `context.Context` is not you inventing API; those method sets are fixed by convention and will not grow. Even then, keep the method count near one or two. A small exported interface can survive a long time precisely because there is little reason to widen it. ## Managing it when you must widen If an exported interface has to grow, you have choices that differ in who pays: - Declare a **second, additive interface** and type-assert for it at the point of use, so old implementations keep working and new capability is opt-in. This is how the standard library handles this problem. - Ship a **struct consumers can embed** that provides implementations of everything, so adding a method does not break embedders. This shifts the guarantee but also removes the compile error that told them to look. - Cut a **new major version** of the module. Honest, and expensive for everyone. - Simply break it and **own the migration**: announce it, and send the changes to the affected repositories yourself rather than filing tickets. Sometimes correct — but it should be a decision made deliberately, with the cost acknowledged, not the side effect of a merged pull request. ## How to defend the call The argument that persuades a reviewer is about reversibility and cost ownership, not about style. Returning a concrete type is the choice that can be changed later — you can always add an exported interface once you know its shape, and existing consumers are unaffected. Exporting an interface early commits you to a method list before anybody has used the package, on behalf of teams who have not written their code yet. The counter-argument worth taking seriously is discoverability: consumers unfamiliar with the idiom may not realise they can declare their own view, and may reach for your concrete type in their signatures, taking the coupling anyway. That is answered with documentation and an example in the package docs, not by exporting an interface you cannot withdraw. ## What it looks like as a standard Write it down as a rule with an escape hatch: packages return concrete types; exported interfaces are declared only where the package accepts implementations; any exported interface that others implement is treated as frozen, and widening it is a compatibility event that goes through review with a named owner for the downstream migration.