Puente entre Interfaces Incompatibles con el Adapter Pattern
Integra APIs legacy y librerías de terceros con object, class y two-way adapters en Java, TypeScript y Python.
Visión general
Digamos que tu app habla con pagos a través de una interfaz PaymentProcessor: charge(amount), refund(transactionId). El SDK de Stripe llama a eso charges.create({ amount }). El de PayPal, orders.capture({ amount }). Ninguno coincide. Podrías esparcir llamadas específicas de Stripe y PayPal por toda la base de código, pero cambiar de proveedor implicaría tocar cada archivo que mueve dinero.
Un adapter es una clase envoltorio que cumple tu interfaz y traduce cada llamada a lo que el SDK espera. El código de negocio solo ve el adapter, así que cambiar Stripe por PayPal cuesta un archivo nuevo — nada más cambia. Abajo encontrarás object adapters, class adapters, two-way adapters y adapter registries con ejemplos funcionales. Ver también Patrón Specification.
Cuándo usarlo
Usa esta receta cuando:
- Integras una librería de terceros cuya interfaz no coincide con la tuya. Consulta Arquitectura Hexagonal para aislamiento de ports/adapters.
- Migras desde un sistema legacy dejando intacto el código que depende de él. Consulta Factory Pattern para crear instancias de adapters.
- Pones una fachada simplificada frente a un subsistema complejo.
- Corres más de una implementación de la misma capacidad (pagos, almacenamiento, mensajería). Consulta Strategy Pattern para selección de algoritmos en tiempo de ejecución.
- Pruebas código que depende de servicios externos inyectando un adapter en memoria.
Solución
Object Adapter (TypeScript)
interface PaymentProcessor {
charge(amount: number, currency: string): Promise<string>;
refund(transactionId: string): Promise<void>;
}
interface Order {
id: string;
total: number;
currency: string;
}
class StripeSDK {
async createCharge(params: { amount: number; currency: string }) {
return { id: 'ch_' + Math.random().toString(36) };
}
async createRefund(params: { charge: string }) {}
}
class StripeAdapter implements PaymentProcessor {
constructor(private stripe: StripeSDK) {}
async charge(amount: number, currency: string): Promise<string> {
const result = await this.stripe.createCharge({ amount: amount * 100, currency });
return result.id;
}
async refund(transactionId: string): Promise<void> {
await this.stripe.createRefund({ charge: transactionId });
}
}
class CheckoutService {
constructor(private processor: PaymentProcessor) {}
async process(order: Order): Promise<string> {
return this.processor.charge(order.total, order.currency);
}
}
Class Adapter (Java)
interface ModernLogger {
void log(String level, String message);
}
class LegacyLogger {
public void writeLogEntry(String entry) {
System.out.println("[LEGACY] " + entry);
}
}
class LoggerAdapter extends LegacyLogger implements ModernLogger {
@Override
public void log(String level, String message) {
writeLogEntry(String.format("[%s] %s", level.toUpperCase(), message));
}
}
ModernLogger logger = new LoggerAdapter();
logger.log("info", "Application started");
Python Adapter con Registry
from abc import ABC, abstractmethod
from typing import Dict
class StorageAdapter(ABC):
@abstractmethod
def upload(self, key: str, data: bytes) -> str: pass
@abstractmethod
def download(self, key: str) -> bytes: pass
class S3Adapter(StorageAdapter):
def __init__(self, client):
self.client = client
def upload(self, key: str, data: bytes) -> str:
self.client.put_object(Bucket="my-bucket", Key=key, Body=data)
return f"s3://my-bucket/{key}"
def download(self, key: str) -> bytes:
return self.client.get_object(Bucket="my-bucket", Key=key)["Body"].read()
class AzureBlobAdapter(StorageAdapter):
def __init__(self, container_client):
self.container = container_client
def upload(self, key: str, data: bytes) -> str:
self.container.upload_blob(name=key, data=data, overwrite=True)
return f"azure://my-container/{key}"
def download(self, key: str) -> bytes:
return self.container.download_blob(key).readall()
class StorageFactory:
_adapters: Dict[str, type] = {}
@classmethod
def register(cls, name: str, adapter_class: type):
cls._adapters[name] = adapter_class
@classmethod
def create(cls, name: str, config: dict) -> StorageAdapter:
return cls._adapters[name](**config)
StorageFactory.register("s3", S3Adapter)
StorageFactory.register("azure", AzureBlobAdapter)
storage = StorageFactory.create("s3", {"client": boto3_client})
url = storage.upload("report.pdf", pdf_bytes)
PayPal Adapter y Soporte Multi-Provider
class PayPalSDK {
async captureOrder(params: { amount: number; currency: string }) {
return { id: 'PAYID-' + Math.random().toString(36) };
}
async refundPayment(params: { captureId: string }) {}
}
class PayPalAdapter implements PaymentProcessor {
constructor(private paypal: PayPalSDK) {}
async charge(amount: number, currency: string): Promise<string> {
const result = await this.paypal.captureOrder({ amount, currency });
return result.id;
}
async refund(transactionId: string): Promise<void> {
await this.paypal.refundPayment({ captureId: transactionId });
}
}
// Selección de proveedor vía factory
class PaymentProcessorFactory {
private static providers: Map<string, () => PaymentProcessor> = new Map();
static register(name: string, factory: () => PaymentProcessor) {
this.providers.set(name, factory);
}
static create(name: string): PaymentProcessor {
const factory = this.providers.get(name);
if (!factory) throw new Error(`Unknown provider: ${name}`);
return factory();
}
}
PaymentProcessorFactory.register('stripe', () =>
new StripeAdapter(new StripeSDK()));
PaymentProcessorFactory.register('paypal', () =>
new PayPalAdapter(new PayPalSDK()));
// Uso — cambia de proveedor vía config
const processor = PaymentProcessorFactory.create(process.env.PAYMENT_PROVIDER);
Two-Way Adapter para Migración Incremental
// Interfaz vieja — en proceso de retiro
interface LegacyPaymentApi {
processPayment(amount: number): Promise<{ txId: string }>;
}
// Interfaz nueva — arquitectura objetivo
interface ModernPaymentApi {
charge(amount: number, currency: string): Promise<string>;
refund(transactionId: string): Promise<void>;
}
// Two-way adapter — satisface ambas interfaces
class PaymentBridge implements LegacyPaymentApi, ModernPaymentApi {
constructor(private processor: PaymentProcessor) {}
// Interfaz legacy — delega a la nueva
async processPayment(amount: number): Promise<{ txId: string }> {
const txId = await this.processor.charge(amount, 'USD');
return { txId };
}
// Interfaz moderna
async charge(amount: number, currency: string): Promise<string> {
return this.processor.charge(amount, currency);
}
async refund(transactionId: string): Promise<void> {
return this.processor.refund(transactionId);
}
}
// El código viejo puede usar processPayment(), el nuevo usa charge()
// Ambas coexisten durante la migración
In-Memory Adapter para Testing
class InMemoryPaymentAdapter implements PaymentProcessor {
private transactions: Map<string, { amount: number; currency: string }> = new Map();
private refunded: Set<string> = new Set();
async charge(amount: number, currency: string): Promise<string> {
const txId = 'test_' + Math.random().toString(36);
this.transactions.set(txId, { amount, currency });
return txId;
}
async refund(transactionId: string): Promise<void> {
if (!this.transactions.has(transactionId)) {
throw new Error('Transaction not found');
}
this.refunded.add(transactionId);
}
// Helpers de test
getChargedAmount(txId: string): number | undefined {
return this.transactions.get(txId)?.amount;
}
wasRefunded(txId: string): boolean {
return this.refunded.has(txId);
}
}
// Uso en tests
describe('CheckoutService', () => {
it('carga el monto correcto', async () => {
const processor = new InMemoryPaymentAdapter();
const service = new CheckoutService(processor);
const txId = await service.process({
id: 'order-1',
total: 99.99,
currency: 'USD',
});
expect(processor.getChargedAmount(txId)).toBe(99.99);
});
});
Explicación
- Object adapter: el adapter guarda una referencia al adaptee (la clase de terceros) y le delega las llamadas. Es el enfoque más flexible — funciona con clases
final, favorece la composición sobre la herencia, y permite que un solo adapter envuelva más de un adaptee. - Class adapter: el adapter hereda del adaptee y satisface la interfaz objetivo. Requiere que el adaptee no sea
finaly solo funciona en lenguajes de herencia simple — si el adapter ya extiende otra clase, esta vía queda descartada. Menos flexible, ligeramente más rápido. - Two-way adapter: ¿dos sistemas que deben interoperar y no puedes cambiar ninguno? Un two-way adapter satisface ambas interfaces y traduce llamadas en cada dirección, actuando como puente mientras migras.
- Adapter registry: cuando soportas varios proveedores (Stripe, PayPal, Braintree), un registro mapea nombres de proveedor a clases adapter. La factory elige el adapter correcto desde la configuración, así la lógica de negocio nunca decide qué proveedor usar.
Variantes
| Variante | Flexibilidad | Rendimiento | Mejor para |
|---|---|---|---|
| Object adapter | Alta | Medio | Uso general, SDKs de terceros |
| Class adapter | Baja | Alto | Crítico en rendimiento, un solo adaptee |
| Two-way adapter | Media | Medio | Migración incremental |
| Facade adapter | Alta | Medio | Simplificar subsistemas complejos |
| Registry + adapter | Alta | Medio | Soporte de varios proveedores |
Lo que funciona
- Adapta en el límite, no en todas partes: pon los adapters donde las interfaces externas se encuentran con tus abstracciones internas, y mantén los tipos del proveedor fuera de la lógica de negocio por completo.
- Documenta la traducción: los adapters hacen más que renombrar métodos. Pueden convertir unidades, transformar tipos de error o agrupar requests en lotes. Anota qué traduce cada adapter.
- Mapea errores a tu taxonomía: las APIs de terceros lanzan excepciones específicas del proveedor. Captúralas en el adapter y relanza las tuyas.
StripeCardErrorse convierte enPaymentDeclinedError. - Mantén los adapters delgados: un adapter con cientos de líneas de lógica es un servicio, no un adapter. Mueve las transformaciones complejas a servicios de aplicación y deja que el adapter traduzca llamadas y se quite del medio.
- Prueba con contract tests: comprueba que el adapter satisface la interfaz objetivo en lugar de ejercitar el SDK de terceros. Mockea el adaptee, corre el adapter de forma aislada. Consulta Input Validation para contratos de límite.
Errores comunes
- Filtrar detalles del adaptee: devuelve los objetos de respuesta nativos del adaptee y cada consumidor termina aprendiendo la API de terceros. Devuelve tipos de dominio en su lugar.
- Adapter inflado: meter caching, reintentos y métricas dentro del adapter lo hace difícil de probar y reutilizar. Usa decoradores o interceptores para las preocupaciones transversales; el adapter solo traduce.
- Ignorar null/undefined: las APIs de terceros devuelven
nulldonde tu interfaz espera un objeto vacío o un error lanzado. Define un contrato de null por adapter y aplícalo de forma consistente. - Dejar que el SDK se filtre: cuando el proveedor lanza un cambio incompatible, el adapter debería absorberlo. Si el código de negocio llama al SDK directamente, cada cambio se propaga a todas partes — el adapter deja de ser tu amortiguador.
Lecturas adicionales
- Adapter pattern — Refactoring Guru
- Adapter pattern — Wikipedia
- Referencia de la API de Stripe — el tipo de superficie de SDK que un adapter aísla
Preguntas frecuentes
¿Es el adapter pattern lo mismo que el facade pattern?
No. Un adapter hace compatible una interfaz con otra. Una fachada te da una interfaz simplificada sobre un subsistema complejo. Puedes usar ambos: una fachada simplifica un subsistema, y un adapter hace que esa fachada coincida con la interfaz de tu aplicación.
¿Debería escribir un adapter para cada librería de terceros?
No — solo para librerías cuyas interfaces chocan con la tuya y quedan bajo código de negocio. Una librería de logging que habla SLF4J ya es estándar; un SDK de pagos con su propio vocabulario es para lo que sirven los adapters.
¿Cómo manejo actualizaciones de SDK con adapters?
El adapter absorbe el golpe. Cuando el SDK lanza un cambio incompatible, editas ese único archivo y corres los contract tests para confirmar que sigue satisfaciendo la interfaz objetivo. Nada del código de negocio se mueve.
¿Pueden usarse adapters para testing?
Sí — un InMemoryPaymentAdapter respaldado por un Map satisface PaymentProcessor sin problema. Inyéctalo en los tests en lugar del adapter real de Stripe y obtienes ejecuciones rápidas y deterministas sin red.
Recursos Relacionados
Construir Apps Mantenibles con Arquitectura Hexagonal
Estructura aplicaciones con ports y adapters para aislar la lógica de negocio de frameworks, bases de datos y servicios externos y facilitar los tests.
RecipeCrea Objetos de Forma Flexible con el Patrón Factory
Cómo usar factory methods, abstract factories e inyección de dependencias para desacoplar la creación de objetos de su uso y facilitar las pruebas.
RecipeDiseñar un API Gateway Escalable para Microservicios
Construí un gateway de API que enrute requests, maneje autenticación, rate limiting, caching y traducción de protocolos entre clientes y microservicios backend.
PatternPatrón Singleton: Ejemplos en Java, Python y TypeScript
Garantiza que una clase tenga una única instancia y ofrece acceso global a ella — el patrón creacional para controlar la creación de objetos, con implementaciones listas para producción.
RecipeIntercambiar Algoritmos en Runtime con el Strategy Pattern
Cómo encapsular algoritmos y comportamientos intercambiables usando el strategy pattern con inyección de dependencias, function pointers y lambda strategies en Java, TypeScript y Python.