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 Usarlo

• Al construir nuevas funcionalidades donde la mantenibilidad y la testabilidad a largo plazo son importantes.
• Al refactorizar código con capas pesadas o fuertemente acoplado a frameworks, donde la lógica de dominio está mezclada con preocupaciones de E/S.
• Al admitir múltiples interfaces para el mismo caso de uso (HTTP, CLI, workers de cola, tareas programadas).
• Al reemplazar infraestructura (base de datos, APIs externas, bus de mensajes) sin reescribir reglas de negocio.

Usa esta habilidad 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 casos de uso).
• Puertos de salida: Contratos para las dependencias que la aplicación necesita (repositorios, pasarelas, publicadores de eventos, reloj, UUID, etc.).
• Adaptadores: Implementaciones de infraestructura y entrega de puertos (controladores HTTP, repositorios de base de datos, consumidores de cola, envoltorios de SDK).
• Punto de composición: Única ubicación de cableado donde los adaptadores concretos se vinculan a los casos de uso.

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

La dirección de la dependencia siempre es hacia adentro:

• Adaptadores -> aplicación/dominio
• Aplicación -> interfaces de puerto (contratos de entrada/salida)
• Dominio -> abstracciones solo del dominio (sin dependencias de frameworks 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, envoltorios 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 puertos mediante el constructor/argumentos. Valida invariantes a nivel de aplicación, coordina reglas de dominio y devuelve estructuras de datos simples.

Paso 4: Construir adaptadores en los bordes

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

Paso 5: Cablear todo en un punto de composición

Instancia 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ímites

• Pruebas unitarias de casos de uso con puertos falsos.
• Pruebas de integración de adaptadores con dependencias de infraestructura reales.
• Pruebas 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 Sugerido de Módulos

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;
  }
}

Punto 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 Multi-Lenguaje

Usa las mismas reglas de límites en todos los ecosistemas; solo cambian 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/argumento.
  • Adaptadores: adapters/inbound/*, adapters/outbound/*.
  • Composición: módulo de fábrica/contenedor explícito (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 (@Service de Spring es opcional, no requerido).
  • Composición: configuración de Spring o clase de cableado manual; mantén el cableado fuera de las clases de dominio/caso de uso.
• Kotlin
  • 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ódulo 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: estructuras con campos de interfaz más constructores New... explícitos.
  • Composición: cableado en cmd/<app>/main.go (o paquete de cableado dedicado), mantén los constructores explícitos.

Antipatrones a Evitar

• Entidades de dominio que importan modelos ORM, tipos de framework web o clientes SDK.
• Casos de uso que leen 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.
• Permitir que los adaptadores se llamen entre sí directamente en lugar de fluir a través de puertos de casos de uso.
• Distribuir el cableado de dependencias en muchos archivos con singletons globales ocultos.

Manual de Migración

1. Elige un corte vertical (un único endpoint/trabajo) con dolor de cambios frecuentes.
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 a 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. Añade pruebas alrededor del nuevo límite (unitarias + integración de adaptadores).
7. Repite por cada corte; 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 big-bang: migra por cada funcionalidad y preserva el comportamiento con pruebas de caracterización.
• Fachada primero: envuelve servicios heredados detrás de puertos de salida antes de reemplazar internos.
• Congelación de composición: centraliza el cableado temprano para que nuevas dependencias no se filtren en las capas de dominio/caso de uso.
• Regla de selección de corte: prioriza flujos con alta rotación y bajo radio de impacto primero.
• Ruta de reversión: mantén un interruptor reversible o un cambio de ruta por cada corte migrado 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; afirma 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 del protocolo (HTTP/CLI/payload de cola a entrada del 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/consulta, reintentos y tiempos de espera.
• Pruebas de extremo a extremo: cubre los recorridos críticos del usuario a través de adaptador de entrada -> caso de uso -> adaptador de salida.
• Seguridad de refactorización: añade 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 Buenas 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).
• El punto de composición es explícito y fácil de auditar.
• Los casos de uso son testeables con falsos simples en memoria para los puertos.
• La refactorización comienza desde un corte 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.