When should you introduce an Adapter at a module or system boundary rather than changing the interface directly, and what are the design trade-offs?

## The decision: adapt or change directly An Adapter is fundamentally about **dependency direction and ownership**. The core question at a boundary is: *whose interface does my code depend on?* If your code depends directly on a foreign type, every change to that foreign type ripples into you. An adapter inverts this: your code depends on **your** target interface, and a single adapter class absorbs the foreign API. ### When an Adapter earns its keep 1. **You can't modify the adaptee** — third-party library, OS API, generated client, another team's service. You have no choice but to wrap. 2. **Many callers depend on a stable interface** — changing the interface directly would break a large blast radius; an adapter lets new and old coexist. 3. **Pluggable providers** — payment gateways, message brokers, cloud SDKs. One `PaymentGateway` target with per-vendor adapters lets you swap or A/B providers without touching call sites. 4. **Anti-corruption layer (DDD)** — an external bounded context has a different, often messier model. The adapter translates external concepts into your clean domain model so the foreign model never **leaks** inward. 5. **Testing seam** — depending on your own narrow interface lets you substitute a fake in tests instead of mocking a sprawling third-party type. 6. **API/version isolation** — a library upgrade with breaking changes is contained to the adapter; the rest of the codebase is insulated. ### When to change the interface directly instead - You **own both sides** and the interfaces are stable — adding an adapter is then ceremony with no isolation benefit. - The adapter would be a **pass-through** that simply re-exposes the adaptee (anemic adapter) — it adds indirection without value. - The translation is so lossy that the adapter hides important semantics; sometimes callers genuinely need the richer foreign API. ## Trade-offs to weigh | Benefit | Cost | |---|---| | Isolates volatility/3rd-party churn | One more layer to build and maintain | | Clean, testable seam (own interface) | Translation logic can be error-prone | | Vendor/provider swappability | Impedance mismatch: foreign concepts may not map cleanly | | Protects domain model (anti-corruption) | Indirection can obscure where work happens | | Honors open/closed at the boundary | Risk of leaky/anemic abstraction if target mirrors adaptee | ## Design guidance - **Design the target interface from the consumer's needs**, not from the adaptee's shape. If you reverse-engineer the target from the foreign API, you import its warts (a leaky abstraction) and lose most of the benefit. - **Keep the adapter thin but meaningful** — it should translate, not just rename. If it does nothing but forward, question whether you need it. - **One adapter per provider** behind a shared target keeps each translation focused and the set open for extension. - **Beware impedance mismatch** — error models, threading, pagination, and nullability often differ; decide deliberately how to map them, and don't silently swallow foreign error semantics. - **Performance** — adapters add a hop and sometimes data copies; usually negligible, but on hot paths measure (e.g. a view-style adapter that avoids copying vs one that converts collections). ## In Java terms This is the object-adapter form (composition) applied at scale: an interface you own, a class per external dependency implementing it, dependency-injected so the rest of the app codes against the abstraction. It is the practical realization of the Dependency Inversion Principle at module boundaries — high-level code depends on an abstraction, and the adapter binds that abstraction to a concrete external detail.