mdadul Adapter
Also known as: Wrapper
Purpose
Help the user decide whether Adapter is appropriate, then design and implement safe interface translation layers between client code and incompatible services.
When To Use
- User asks to explain Adapter or Wrapper pattern.
- Client needs to consume a legacy or third-party API with incompatible method signatures or data formats.
- Existing service cannot be changed safely (external dependency, high coupling, source unavailable).
- Integration requires protocol conversion (XML to JSON, units, field mapping, call ordering).
- Multiple incompatible providers should be normalized behind one client-facing contract.
Inputs
- Target client interface expected by business logic.
- Service interface provided by legacy/third-party system.
- Data and behavior mismatches (types, units, structure, error model, sync vs async).
- Operational constraints (performance overhead, logging, retries, idempotency, error policy).
- Language/runtime constraints (inheritance support, composition preference, DI/testing setup).
Workflow
- Clarify the goal. Confirm whether the user needs concept explanation, architecture review, or implementation/refactor.
- Check applicability. Use Adapter when the primary need is interface compatibility, not feature extension.
- Define boundary contracts. Document client-facing interface and service-facing interface, including data/error semantics.
- Choose adapter style. Prefer object adapter (composition). Use class adapter only when language and hierarchy constraints justify it.
- Scaffold adapter API. Implement the client interface in adapter class with a wrapped service dependency.
- Translate calls and data. Map arguments, convert payload formats, normalize return values, and bridge exception/error models.
- Integrate behind abstractions. Wire clients to depend on client interface, not concrete adapter/service implementations.
- Expand safely. Add new adapters for additional services/providers without changing client business logic.
- Validate behavior. Verify translation correctness, error propagation, and compatibility under representative scenarios.
Decision Branches
- If interface is already compatible and only extra behavior is needed: Prefer Decorator.
- If goal is simplified entry point for a subsystem (not protocol translation): Prefer Facade.
- If interface must remain unchanged while controlling access/lifecycle: Prefer Proxy.
- If abstraction and implementation should evolve independently from day one: Prefer Bridge.
- If multiple existing clients depend on current service interface and service can be modified safely: Consider direct service redesign over adding adapter layer.
Output Contract
When responding, provide:
- A suitability verdict (Adapter or a better alternative).
- Mismatch matrix (interface, data, error, lifecycle differences).
- Role mapping (Client, Client Interface, Service, Adapter).
- Incremental migration plan from direct service usage to adapter boundary.
- Minimal code sketch in the user's language showing translation logic.
- Validation checklist proving compatibility and non-regression.
Quality Checks
- Adapter fully implements the client-facing contract.
- Adapter delegates business work to service and only handles translation/boundary concerns.
- Data conversions are explicit, deterministic, and tested.
- Error mapping preserves actionable context for clients.
- Client code references abstractions, not concrete service classes.
- Adding a new service variant requires a new adapter, not client rewrites.
Common Mistakes To Prevent
- Putting business logic inside adapter instead of pure translation.
- Leaking service-specific types or exceptions through client interface.
- Performing partial conversion that leaves mixed-domain payloads.
- Tight-coupling client code to concrete adapter implementations.
- Overusing Adapter where simpler direct changes would reduce complexity.
References
- Detailed guide: REFERENCE.md
- Worked examples: EXAMPLES.md