Hexagonal (Ports & Adapters)

El dominio define puertos (interfaces); cada actor externo (API, DB, cola, tests) llega a través de un adaptador intercambiable.

   Driving (primarios)                      Driven (secundarios)
 ┌────────────────────┐                  ┌─────────────────────┐
 │  HTTP API          │                  │  EF Core            │
 │  CLI               │──▶ [puerto IN]   │  Stripe SDK         │
 │  Consumer de cola  │         │        │  SMTP               │
 │  Tests             │         ▼        └─────────▲───────────┘
 └────────────────────┘   ┌──────────┐             │
                          │  NÚCLEO  │─▶ [puerto OUT]
                          │ (negocio)│
                          └──────────┘

#Por qué un hexágono

El hexágono no significa nada especial: Cockburn eligió una figura con varios lados para sugerir que puede haber muchos puertos, y para evitar el dibujo de capas "arriba/abajo". Lo importante es el concepto de adentro y afuera, no la forma.

#Ejemplo en C#

// Puerto de entrada (driving): lo que la aplicación ofrece
public interface IPlaceOrder { Task<Guid> Handle(PlaceOrderCommand cmd); }

// Puertos de salida (driven): lo que la aplicación necesita
public interface IOrderRepository { void Add(Order o); }
public interface IPaymentGateway { Task<bool> ChargeAsync(decimal amount); }

// Núcleo: sin frameworks, sin EF, sin HTTP
public class PlaceOrderUseCase : IPlaceOrder
{
    private readonly IOrderRepository _repo;
    private readonly IPaymentGateway _payments;
    public PlaceOrderUseCase(IOrderRepository r, IPaymentGateway p) { _repo = r; _payments = p; }

    public async Task<Guid> Handle(PlaceOrderCommand cmd)
    {
        var order = Order.Create(cmd);
        if (!await _payments.ChargeAsync(order.Total))
            throw new PaymentDeclined();
        _repo.Add(order);
        return order.Id;
    }
}

Los adaptadores viven afuera y se inyectan:

// Adaptador driving: traduce HTTP al puerto de entrada
app.MapPost("/orders", async (PlaceOrderRequest req, IPlaceOrder useCase) =>
    Results.Ok(await useCase.Handle(new PlaceOrderCommand(req.CustomerId, req.Items))));

// Adaptador driven: traduce el puerto de salida a Stripe
public class StripePaymentGateway : IPaymentGateway
{
    public async Task<bool> ChargeAsync(decimal amount) { /* llamada al SDK */ return true; }
}

#Tests: la ganancia más concreta

El puerto de salida se reemplaza por un fake en memoria: el caso de uso se prueba en milisegundos, sin base de datos ni red.

public class FakePaymentGateway : IPaymentGateway
{
    public bool Approve { get; set; } = true;
    public Task<bool> ChargeAsync(decimal amount) => Task.FromResult(Approve);
}

El mismo núcleo puede ejecutarse desde un test, una API o un worker: son todos adaptadores driving distintos.

#Errores comunes

• Puertos que filtran tecnología: IOrderRepository.GetQueryable() devuelve IQueryable de EF. El puerto debe hablar el idioma del negocio, no el del ORM.
• Una interfaz por clase sin motivo: un puerto existe para aislar algo que cambia o que molesta en los tests, no para tener interfaces de todo.
• Lógica en el adaptador: si el controller decide reglas de negocio, el hexágono está agujereado.
• Puerto de entrada ignorado: el controller llama directo al repositorio y se saltea el caso de uso.

#Hexagonal en relación con las otras

Hexagonal, Onion y Clean comparten la misma idea (dominio al centro, dependencias hacia adentro) y se diferencian en cuánto prescriben de la estructura interna. Hexagonal es la más liviana: solo dice qué está adentro y qué afuera, y no obliga a un número de capas internas. Ver la comparativa.

#architecture #ports #adapters #hexagonal