StackPractices
beginner Por Mathias Paulenko

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.

Temas: design

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 final y 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.
sequenceDiagram diagram: participant App as Tu código

Variantes

VarianteFlexibilidadRendimientoMejor para
Object adapterAltaMedioUso general, SDKs de terceros
Class adapterBajaAltoCrítico en rendimiento, un solo adaptee
Two-way adapterMediaMedioMigración incremental
Facade adapterAltaMedioSimplificar subsistemas complejos
Registry + adapterAltaMedioSoporte 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. StripeCardError se convierte en PaymentDeclinedError.
  • 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 null donde 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

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.