design-pattern-adapter

Skill: Adapter

Intent

Convert one interface into another interface expected by clients so existing functionality can be reused without rewriting either side immediately.

Applicability Signals

• Signal 1: A third-party or legacy component provides needed behavior but exposes mismatched method names/signatures.
• Signal 2: Client code expects a stable contract and cannot absorb provider-specific differences.
• Signal 3: Multiple integrations repeat small translation shims, creating duplicated glue code.

Contraindications

• Case 1: You own both sides and can safely change one interface directly.
• Case 2: Mismatch is temporary and can be removed faster by small targeted refactor.
• Case 3: Adapter would hide severe semantic differences, not just interface differences.

Decision Heuristics

• If interface incompatibility is the core blocker while behavior is otherwise acceptable, prefer Adapter.
• If you need to simplify a whole subsystem API, Facade is often a better fit.
• Decision anti-bias note: avoid stacking adapters to postpone necessary domain model cleanup.

Implementation Checklist

• Define/confirm the target interface clients already rely on.
• Wrap the adaptee in an adapter that implements the target interface.
• Translate method names, argument shapes, and return formats explicitly.
• Centralize validation/error mapping at adapter boundaries.
• Add tests for both normal and mismatch/error translation paths.

Misuse Checks

• Misuse 1: Adapter adds business logic unrelated to translation → Remediation: move business rules back into domain/service layer.
• Misuse 2: Client leaks adaptee types through adapter API → Remediation: keep API strictly on target interface types.
• Misuse 3: Chain of adapters accumulates for one workflow → Remediation: consolidate into one explicit mapping boundary or refactor contract.

Verification Rubric

• Correctness:
  • Client code can call target interface without direct adaptee knowledge.
  • Adapter correctly maps input/output and error semantics.
• Design quality:
  • Translation concerns are isolated in adapter, not scattered in clients.
  • Target contract remains stable and readable.
• Regression safety:
  • Tests cover baseline flow and at least one edge-case translation path.

Language-Specific Adaptations (Optional)

• TypeScript: use interface-based adapter classes; add runtime guards when external payloads are untyped.
• Python: prefer composition over inheritance; use protocols for target contract clarity.
• Go: implement target interface on adapter struct wrapping adaptee.

Related Patterns (Optional)

• Facade: simplifies complex subsystem usage; adapter focuses on interface compatibility.
• Bridge: separates abstraction and implementation when both should vary independently.

Attribution & Sources

• Source Site: Refactoring.Guru
• Source URLs:
  • https://refactoring.guru/design-patterns/adapter
  • https://refactoring.guru/design-patterns
• Derivation Note: Concepts derived from referenced sources; explanatory wording rewritten for this repository.
• Policy Note: This artifact intentionally includes no direct quotes and no Refactoring.Guru images.