Arquitectura hexagonal

Resumen

Arquitectura hexagonal, también llamada ports and adapters, es un patrón arquitectónico que coloca la lógica de la aplicación en el centro y conecta el exterior mediante puertos explícitos y adaptadores reemplazables. El núcleo no debería depender directamente de frameworks, bases de datos, APIs externas o interfaces de usuario.

Importa porque protege las reglas del negocio de decisiones de infraestructura. Permite probar casos de uso sin levantar una base real, cambiar un proveedor externo sin reescribir el dominio y mantener clara la frontera entre lo que la aplicación hace y cómo se conecta al mundo.

Alcance y supuestos

Este paquete cubre arquitectura hexagonal a nivel conceptual: núcleo de aplicación, puertos, adaptadores primarios o driving, adaptadores secundarios o driven, e inversión de dependencias. Usa TypeScript como ejemplo para mostrar contratos e implementaciones sin atarse a un framework específico.

No cubre toda la taxonomía de clean architecture, estructuras de carpetas obligatorias, despliegue de microservicios, DDD táctico completo ni implementación de dependency injection containers. Asume que entiendes servicios de aplicación, interfaces, dependencias externas y pruebas automatizadas.

Modelo mental

Piensa en una consola de videojuegos. El juego es el núcleo: define reglas, estado y decisiones. Los controles, la pantalla, el disco y la red son formas de interactuar con ese juego. Puedes cambiar de joystick o mostrar la imagen en otra pantalla sin reescribir las reglas del juego.

En arquitectura hexagonal, los puertos son las formas de conexión que el núcleo acepta o necesita. Un puerto de entrada describe una conversación que inicia el mundo exterior, como "crear pedido". Un puerto de salida describe algo que el núcleo necesita del exterior, como "guardar pedido" o "enviar email".

Los adaptadores son las piezas concretas que traducen entre el mundo exterior y esos puertos: un controlador HTTP, un repositorio PostgreSQL, un cliente SMTP o un fake para tests. El hexágono no es importante por su forma; importa porque todos los lados externos son detalles intercambiables alrededor del núcleo.

Uso práctico

Usa arquitectura hexagonal cuando quieres que la lógica de aplicación sobreviva a cambios de infraestructura o sea testeable sin dependencias reales:

• ✅ Un caso de uso CreateOrder puede depender de un puerto OrderRepository, no de una librería PostgreSQL concreta.
• ✅ Un test puede usar un adaptador en memoria para verificar reglas sin red, base de datos ni framework web.
• ❌ Poner todo en carpetas llamadas ports y adapters no basta si el núcleo sigue importando controladores o SDKs externos.
• ❌ Para un CRUD muy pequeño, la separación puede agregar más ceremonia que beneficio.

Ejemplo trabajado: aislar un caso de uso de la base de datos

Supón que una aplicación necesita crear pedidos. Sin una frontera clara, el caso de uso podría importar directamente un cliente SQL y quedar acoplado a esa tecnología. En arquitectura hexagonal, el núcleo define el puerto que necesita.

type Order = {
  id: string;
  total: number;
};

interface OrderRepository {
  save(order: Order): Promise<void>;
}

class CreateOrder {
  constructor(private orders: OrderRepository) {}

  async execute(total: number) {
    if (total <= 0) {
      throw new Error("Total must be positive");
    }

    const order = { id: crypto.randomUUID(), total };
    await this.orders.save(order);

    return order;
  }
}

CreateOrder contiene la regla de aplicación: no se crean pedidos con total inválido. También necesita persistir, pero solo conoce el puerto OrderRepository. No sabe si detrás hay PostgreSQL, DynamoDB, un archivo o memoria.

Un adaptador concreto implementa ese puerto para una tecnología específica:

class InMemoryOrderRepository implements OrderRepository {
  private saved: Order[] = [];

  async save(order: Order) {
    this.saved.push(order);
  }

  all() {
    return this.saved;
  }
}

El test puede conectar el caso de uso con el adaptador en memoria:

const repository = new InMemoryOrderRepository();
const createOrder = new CreateOrder(repository);

const order = await createOrder.execute(120);

console.log(order.total); // 120
console.log(repository.all().length); // 1

La misma lógica podría usarse desde un controlador HTTP con otro adaptador, o desde un job de consola, sin cambiar CreateOrder. Esa es la frontera clave: los adaptadores dependen del núcleo; el núcleo no depende de adaptadores concretos.

Antes de aplicar arquitectura hexagonal, revisa cuatro preguntas:

1. ¿Qué reglas pertenecen al núcleo y no deberían importar frameworks?
2. ¿Qué conversaciones entran al sistema y merecen puertos de entrada?
3. ¿Qué capacidades externas necesita el núcleo y deben expresarse como puertos de salida?
4. ¿Qué adaptadores concretos pueden cambiar sin alterar los casos de uso?

Si esas fronteras son reales, la arquitectura hexagonal reduce acoplamiento y mejora testabilidad. Si solo estás renombrando capas sin invertir dependencias, el patrón queda superficial.

Evidencia

• Alistair Cockburn, Hexagonal Architecture describe el patrón original y explica que un puerto identifica una conversación intencional mientras los adaptadores conectan tecnologías externas.
• AWS Prescriptive Guidance, Hexagonal architecture pattern presenta arquitectura hexagonal como ports and adapters para crear arquitecturas desacopladas.