Arquitectura Hexagonal

¿Qué hace Arquitectura Hexagonal?

La arquitectura hexagonal (Puertos y Adaptadores) mantiene la lógica de negocio independiente de frameworks, transporte y detalles de persistencia. La aplicación central depende de puertos abstractos, y los adaptadores implementan esos puertos en los bordes.

Cuándo Usarla

• Construir nuevas funcionalidades donde la mantenibilidad y testabilidad a largo plazo son importantes.
• Refactorizar código con capas pesadas o basado en frameworks donde la lógica de dominio está mezclada con preocupaciones de E/S.
• Soportar múltiples interfaces para el mismo caso de uso (HTTP, CLI, workers de cola, tareas cron).
• Reemplazar infraestructura (base de datos, APIs externas, bus de mensajes) sin reescribir las reglas de negocio.

Usa esta skill cuando la solicitud involucre límites, diseño centrado en el dominio, refactorización de servicios fuertemente acoplados o desacoplamiento de la lógica de aplicación de bibliotecas específicas.

Conceptos Clave

• Modelo de dominio: Reglas de negocio y entidades/objetos de valor. Sin imports de frameworks.
• Casos de uso (capa de aplicación): Orquestan el comportamiento del dominio y los pasos del flujo de trabajo.
• Puertos de entrada: Contratos que describen lo que la aplicación puede hacer (comandos/consultas/interfaces de caso de uso).
• Puertos de salida: Contratos para dependencias que la aplicación necesita (repositorios, pasarelas, publicadores de eventos, reloj, UUID, etc.).
• Adaptadores: Implementaciones de infraestructura y entrega de los puertos (controladores HTTP, repositorios de base de datos, consumidores de cola, wrappers de SDK).
• Raíz de composición: Único lugar de cableado donde los adaptadores concretos se vinculan a los casos de uso.

Las interfaces de puerto de salida generalmente residen en la capa de aplicación (o solo en el dominio cuando la abstracción es verdaderamente a nivel de dominio), mientras que los adaptadores de infraestructura las implementan.

La dirección de las dependencias siempre es hacia adentro:

• Adaptadores -> aplicación/dominio
• Aplicación -> interfaces de puerto (contratos de entrada/salida)
• Dominio -> abstracciones solo de dominio (sin dependencias de framework o infraestructura)
• Dominio -> nada externo

Cómo Funciona

Paso 1: Modelar un límite de caso de uso

Define un caso de uso único con un DTO de entrada y salida claro. Mantén los detalles de transporte (Express req, GraphQL context, wrappers de payload de trabajo) fuera de este límite.

Paso 2: Definir primero los puertos de salida

Identifica cada efecto secundario como un puerto:

• persistencia (UserRepositoryPort)
• llamadas externas (BillingGatewayPort)
• transversales (LoggerPort, ClockPort)

Los puertos deben modelar capacidades, no tecnologías.

Paso 3: Implementar el caso de uso con orquestación pura

La clase/función del caso de uso recibe los puertos a través del constructor/argumentos. Valida invariantes a nivel de aplicación, coordina reglas de dominio y devuelve estructuras de datos simples.

Paso 4: Construir adaptadores en el borde

• Adaptador de entrada: convierte la entrada del protocolo en entrada del caso de uso.
• Adaptador de salida: mapea los contratos de la aplicación a APIs/ORM/constructores de consultas concretos.
• El mapeo se queda en los adaptadores, no dentro de los casos de uso.

Paso 5: Cablear todo en una raíz de composición

Instancia los adaptadores, luego inyéctalos en los casos de uso. Mantén este cableado centralizado para evitar comportamientos ocultos de localizador de servicios.

Paso 6: Probar por límite

• Prueba unitaria de casos de uso con puertos falsos.
• Prueba de integración de adaptadores con dependencias de infraestructura reales.
• Prueba E2E de flujos orientados al usuario a través de adaptadores de entrada.

Diagrama de Arquitectura

flowchart LR
  Client["Cliente (HTTP/CLI/Worker)"] --> InboundAdapter["Adaptador de Entrada"]
  InboundAdapter -->|"llama"| UseCase["Caso de Uso (Capa de Aplicación)"]
  UseCase -->|"usa"| OutboundPort["Puerto de Salida (Interfaz)"]
  OutboundAdapter["Adaptador de Salida"] -->|"implementa"| OutboundPort
  OutboundAdapter --> ExternalSystem["BD/API/Cola"]
  UseCase --> DomainModel["Modelo de Dominio"]

Diseño de Módulos Sugerido

Usa organización por funcionalidad con límites explícitos:

src/
  features/
    orders/
      domain/
        Order.ts
        OrderPolicy.ts
      application/
        ports/
          inbound/
            CreateOrder.ts
          outbound/
            OrderRepositoryPort.ts
            PaymentGatewayPort.ts
        use-cases/
          CreateOrderUseCase.ts
      adapters/
        inbound/
          http/
            createOrderRoute.ts
        outbound/
          postgres/
            PostgresOrderRepository.ts
          stripe/
            StripePaymentGateway.ts
      composition/
        ordersContainer.ts

Ejemplo en TypeScript

Definiciones de puertos

export interface OrderRepositoryPort {
  save(order: Order): Promise<void>;
  findById(orderId: string): Promise<Order | null>;
}

export interface PaymentGatewayPort {
  authorize(input: { orderId: string; amountCents: number }): Promise<{ authorizationId: string }>;
}

Caso de uso

type CreateOrderInput = {
  orderId: string;
  amountCents: number;
};

type CreateOrderOutput = {
  orderId: string;
  authorizationId: string;
};

export class CreateOrderUseCase {
  constructor(
    private readonly orderRepository: OrderRepositoryPort,
    private readonly paymentGateway: PaymentGatewayPort
  ) {}

  async execute(input: CreateOrderInput): Promise<CreateOrderOutput> {
    const order = Order.create({ id: input.orderId, amountCents: input.amountCents });

    const auth = await this.paymentGateway.authorize({
      orderId: order.id,
      amountCents: order.amountCents,
    });

    // markAuthorized devuelve una nueva instancia de Order; no muta en el lugar.
    const authorizedOrder = order.markAuthorized(auth.authorizationId);
    await this.orderRepository.save(authorizedOrder);

    return {
      orderId: order.id,
      authorizationId: auth.authorizationId,
    };
  }
}

Adaptador de salida

export class PostgresOrderRepository implements OrderRepositoryPort {
  constructor(private readonly db: SqlClient) {}

  async save(order: Order): Promise<void> {
    await this.db.query(
      "insert into orders (id, amount_cents, status, authorization_id) values ($1, $2, $3, $4)",
      [order.id, order.amountCents, order.status, order.authorizationId]
    );
  }

  async findById(orderId: string): Promise<Order | null> {
    const row = await this.db.oneOrNone("select * from orders where id = $1", [orderId]);
    return row ? Order.rehydrate(row) : null;
  }
}

Raíz de composición

export const buildCreateOrderUseCase = (deps: { db: SqlClient; stripe: StripeClient }) => {
  const orderRepository = new PostgresOrderRepository(deps.db);
  const paymentGateway = new StripePaymentGateway(deps.stripe);

  return new CreateOrderUseCase(orderRepository, paymentGateway);
};

Mapeo a Múltiples Lenguajes

Usa las mismas reglas de límite en todos los ecosistemas; solo cambia la sintaxis y el estilo de cableado.

• TypeScript/JavaScript
  • Puertos: application/ports/* como interfaces/tipos.
  • Casos de uso: clases/funciones con inyección por constructor/argumentos.
  • Adaptadores: adapters/inbound/*, adapters/outbound/*.
  • Composición: módulo explícito de fábrica/contenedor (sin globales ocultos).
• Java
  • Paquetes: domain, application.port.in, application.port.out, application.usecase, adapter.in, adapter.out.
  • Puertos: interfaces en application.port.*.
  • Casos de uso: clases simples (Spring @Service es opcional, no requerido).
  • Composición: configuración Spring o clase de cableado manual; mantén el cableado fuera de las clases de dominio/caso de uso.
• Kotlin
  • Los módulos/paquetes reflejan la división de Java (domain, application.port, application.usecase, adapter).
  • Puertos: interfaces de Kotlin.
  • Casos de uso: clases con inyección por constructor (Koin/Dagger/Spring/manual).
  • Composición: definiciones de módulos o funciones de composición dedicadas; evita patrones de localizador de servicios.
• Go
  • Paquetes: internal/<feature>/domain, application, ports, adapters/inbound, adapters/outbound.
  • Puertos: interfaces pequeñas propiedad del paquete de aplicación consumidor.
  • Casos de uso: structs con campos de interfaz más constructores New... explícitos.
  • Composición: cablear en cmd/<app>/main.go (o paquete de cableado dedicado), mantén los constructores explícitos.

Antipatrones a Evitar

• Entidades de dominio importando modelos ORM, tipos de frameworks web o clientes SDK.
• Casos de uso leyendo directamente de req, res o metadatos de cola.
• Devolver filas de base de datos directamente desde los casos de uso sin mapeo de dominio/aplicación.
• Dejar que los adaptadores se llamen entre sí directamente en lugar de fluir a través de los puertos de caso de uso.
• Distribuir el cableado de dependencias en muchos archivos con singletons globales ocultos.

Plan de Migración

1. Elige una rebanada vertical (un único endpoint/trabajo) con dolor de cambio frecuente.
2. Extrae un límite de caso de uso con tipos de entrada/salida explícitos.
3. Introduce puertos de salida alrededor de las llamadas de infraestructura existentes.
4. Mueve la lógica de orquestación de controladores/servicios al caso de uso.
5. Mantén los adaptadores antiguos, pero haz que deleguen en el nuevo caso de uso.
6. Agrega pruebas alrededor del nuevo límite (unitarias + integración de adaptadores).
7. Repite rebanada por rebanada; evita reescrituras completas.

Refactorización de Sistemas Existentes

• Enfoque estrangulador: mantén los endpoints actuales, enruta un caso de uso a la vez a través de nuevos puertos/adaptadores.
• Sin reescrituras tipo big-bang: migra por rebanada de funcionalidad y preserva el comportamiento con pruebas de caracterización.
• Fachada primero: envuelve servicios heredados detrás de puertos de salida antes de reemplazar los internos.
• Congelar composición: centraliza el cableado temprano para que nuevas dependencias no se filtren a las capas de dominio/caso de uso.
• Regla de selección de rebanadas: prioriza flujos de alta rotación y bajo riesgo de impacto primero.
• Ruta de reversión: mantén un interruptor reversible o cambio de ruta por rebanada migrada hasta que el comportamiento en producción esté verificado.

Guía de Pruebas (Mismos Límites Hexagonales)

• Pruebas de dominio: prueba entidades/objetos de valor como reglas de negocio puras (sin mocks, sin configuración de framework).
• Pruebas unitarias de casos de uso: prueba la orquestación con falsos/stubs para puertos de salida; verifica resultados de negocio e interacciones con puertos.
• Pruebas de contrato de adaptadores de salida: define suites de contrato compartidas a nivel de puerto y ejecútalas contra cada implementación de adaptador.
• Pruebas de adaptadores de entrada: verifica el mapeo de protocolo (payload HTTP/CLI/cola a entrada de caso de uso y mapeo de salida/error de vuelta al protocolo).
• Pruebas de integración de adaptadores: ejecuta contra infraestructura real (BD/API/cola) para serialización, comportamiento de esquema/consultas, reintentos y tiempos de espera.
• Pruebas de extremo a extremo: cubre recorridos críticos de usuario a través del adaptador de entrada -> caso de uso -> adaptador de salida.
• Seguridad en refactorización: agrega pruebas de caracterización antes de la extracción; mantenlas hasta que el comportamiento del nuevo límite sea estable y equivalente.

Lista de Verificación de Mejores Prácticas

• Las capas de dominio y caso de uso importan solo tipos internos y puertos.
• Cada dependencia externa está representada por un puerto de salida.
• La validación ocurre en los límites (adaptador de entrada + invariantes del caso de uso).
• Usa transformaciones inmutables (devuelve nuevos valores/entidades en lugar de mutar estado compartido).
• Los errores se traducen a través de los límites (errores de infraestructura -> errores de aplicación/dominio).
• La raíz de composición es explícita y fácil de auditar.
• Los casos de uso son testeables con falsos en memoria simples para los puertos.
• La refactorización comienza desde una rebanada vertical con pruebas que preservan el comportamiento.
• Los detalles específicos del lenguaje/framework se quedan en los adaptadores, nunca en las reglas de dominio.