Arquitectura hexagonal, de cebolla y limpia

Una idea, tres nombres

La arquitectura hexagonal, la arquitectura de cebolla y la arquitectura limpia son tres formulaciones de una misma idea: poner la lógica de negocio en el centro, hacerla independiente de las interfaces de usuario, las bases de datos, los frameworks y los servicios externos, y hacer que todas las dependencias del código fuente apunten hacia ella. Describen la estructura interna de una aplicación, así que se combinan con cualquier estilo de despliegue: un único monolito, un monolito modular cuyos módulos se construyen cada uno de esta manera, o un microservicio.

Surgieron de la frustración con la clásica arquitectura en capas. En el estilo en capas de la Sección 5.2, la capa de negocio depende de la capa de persistencia, que depende de la base de datos, así que las reglas de negocio acaban moldeadas por las tablas y el mapeo objeto-relacional, y probar una regla implica arrancar una base de datos. La familia de estilos de esta sección invierte esa dependencia con el principio de inversión de dependencias: el código de negocio declara las interfaces que necesita, y el código de infraestructura las implementa. El principio en sí se trata en la Sección 3.5; esta sección muestra las arquitecturas construidas sobre él.

Arquitectura hexagonal: puertos y adaptadores

Alistair Cockburn describió la idea por primera vez en la wiki del Portland Pattern Repository y la desarrolló en un artículo en 2005 con el nombre, más descriptivo, de puertos y adaptadores. Su intención declarada era permitir que una aplicación sea dirigida por igual por usuarios, programas, pruebas automatizadas o scripts por lotes, y desarrollarla y probarla aislada de sus futuras bases de datos y dispositivos. En 2024, él y Juan Manuel Garrido de Paz publicaron un libro breve, Hexagonal Architecture Explained, que reformula el patrón.

Un puerto es una conversación con un propósito entre la aplicación y el mundo exterior, expresada como una interfaz: "hacer un pedido", "guardar pedidos", "cobrar una tarjeta". Un adaptador es el código que traduce entre un puerto y una tecnología concreta: un controlador HTTP, un repositorio SQL, el SDK de un proveedor de pagos, un script de línea de comandos, un fake en memoria. Un puerto puede tener muchos adaptadores. La aplicación dentro del hexágono solo conoce sus puertos.

El hexágono no tiene ningún significado como forma; Cockburn lo eligió para escapar de la imagen de capas de arriba abajo y para dejar espacio para dibujar varios puertos en cada lado. Lo que importa es el límite entre dentro y fuera y la asimetría entre dos tipos de puerto.

Lado conductor y lado conducido

Los puertos y adaptadores conductores (primarios) se sitúan a la izquierda de la imagen habitual. Un adaptador conductor recibe una solicitud de un actor primario (el navegador de un usuario, una app para dispositivos móviles, otro sistema, una prueba, un trabajo programado) y llama a un puerto conductor, que es la API propia de la aplicación: en la práctica, un caso de uso como PlaceOrder. El adaptador convierte HTTP, un mensaje o un argumento de línea de comandos en una llamada con valores del dominio, y convierte el resultado de nuevo en una respuesta.

Los puertos y adaptadores conducidos (secundarios) se sitúan a la derecha. La aplicación los llama cuando necesita algo del mundo exterior: guardar un pedido, cobrar una tarjeta, enviar una notificación, leer la hora. El puerto es una interfaz que pertenece a la aplicación y está escrita en sus términos (OrderRepository.save(order)), y un adaptador conducido la implementa para una tecnología (PostgreSQL, la API de un proveedor de tarjetas, una pasarela de SMS). Aquí es donde se produce la inversión de dependencias: en tiempo de ejecución la aplicación llama al adaptador, pero en el código fuente el adaptador depende de la interfaz de la aplicación, y no al revés.

El texto original de Cockburn habla de actores primarios y secundarios; los términos conductor y conducido son hoy más comunes, y él mismo los usa. La distinción importa para las pruebas: los puertos conductores se ejercitan con arneses de pruebas que actúan como usuarios, y los puertos conducidos se sustituyen por dobles de prueba. También importa para el cambio: los canales nuevos (un asistente de voz, una API para socios) llegan como adaptadores conductores nuevos, y la infraestructura nueva llega como adaptadores conducidos nuevos.

Alguien tiene que crear los adaptadores y conectarlos a la aplicación. Eso ocurre en una única raíz de composición, normalmente el código de arranque del programa, que es la única parte del sistema que conoce todos los adaptadores. Un framework de inyección de dependencias puede hacer este trabajo, pero unas simples llamadas a constructores en main suelen ser más claras.

Arquitectura de cebolla

Jeffrey Palermo describió la arquitectura de cebolla en una serie de entradas de blog a partir de julio de 2008, pensada para aplicaciones de negocio de larga vida con un comportamiento considerable (la desaconsejaba para sitios web pequeños). Dibujó anillos concéntricos: el modelo de dominio en el centro, los servicios de dominio a su alrededor, los servicios de aplicación alrededor de estos, y un anillo exterior que contiene la interfaz de usuario, la infraestructura (incluida la base de datos) y las pruebas. Sus principios clave son que la aplicación se construye en torno a un modelo de objetos independiente, que las capas interiores definen interfaces que implementan las capas exteriores, que todo el acoplamiento va hacia el centro y que el núcleo de la aplicación puede compilarse y ejecutarse por separado de la infraestructura.

Frente a la arquitectura hexagonal, la de cebolla añade anillos con nombre dentro de la aplicación y hace explícito un punto que la imagen de Cockburn deja implícito: la base de datos no es el cimiento del sistema, sino un servicio externo en el borde. Las interfaces de repositorio viven en el núcleo; sus implementaciones viven en el anillo de infraestructura.

La arquitectura limpia y la regla de dependencia

Robert C. Martin publicó "The Clean Architecture" en su blog en agosto de 2012 como síntesis de la arquitectura hexagonal, la arquitectura de cebolla y otras propuestas similares, y la amplió en el libro Clean Architecture en 2017. Su imagen tiene cuatro anillos. Las entidades contienen las reglas de negocio de toda la empresa. Los casos de uso contienen las reglas específicas de la aplicación que orquestan las entidades. Los adaptadores de interfaz convierten los datos entre la forma que necesitan los casos de uso y la que necesitan los agentes externos: controladores, presentadores y gateways. Los frameworks y drivers forman el anillo exterior: el framework web, la base de datos, la interfaz de usuario.

La regla de dependencia lo une todo: las dependencias del código fuente apuntan solo hacia dentro, y nada de un anillo interior puede nombrar nada declarado en un anillo exterior, ya sea una clase, una función o un formato de datos. Cuando el control debe fluir hacia fuera (un caso de uso que guarda un pedido), el anillo interior declara una interfaz y el anillo exterior la implementa. Los datos que cruzan un límite deben ser estructuras simples en los términos del anillo interior, nunca una fila de base de datos ni un objeto de solicitud HTTP. Martin sostiene también que la estructura de nivel superior debe revelar el propósito del sistema (pedidos, pagos, entregas) y no su framework, una idea que llama arquitectura que grita (screaming architecture).

Un caso de uso con un puerto y dos adaptadores

El siguiente ejemplo en Python implementa al estilo hexagonal el caso de uso PlaceOrder de la plataforma de reparto de comida. El primer fragmento es el interior: una pequeña clase de dominio, dos puertos conducidos escritos como clases typing.Protocol y el caso de uso, que actúa como puerto conductor. El segundo fragmento es el exterior: un adaptador de PostgreSQL y un doble de prueba en memoria que implementan el mismo puerto. El tercero muestra por qué importa: una prueba unitaria rápida y la raíz de composición donde se conectan los adaptadores de producción.

from dataclasses import dataclass
from decimal import Decimal
from typing import Protocol

@dataclass
class Order:
    id: str
    total: Decimal
    status: str = "new"

class OrderRepository(Protocol):        # driven port
    def save(self, order: Order) -> None: ...

class PaymentGateway(Protocol):         # driven port
    def charge(self, order_id: str, amount: Decimal) -> bool: ...

class PlaceOrder:                       # driving port + use case
    def __init__(self, orders: OrderRepository, payments: PaymentGateway):
        self.orders, self.payments = orders, payments

    def __call__(self, order_id: str, total: Decimal) -> Order:
        if total <= 0:
            raise ValueError("empty basket")
        order = Order(order_id, total)
        order.status = "paid" if self.payments.charge(order_id, total) else "payment-failed"
        self.orders.save(order)
        return order

class PostgresOrderRepository:          # real driven adapter
    def __init__(self, conn):
        self.conn = conn
    def save(self, order):
        with self.conn.cursor() as cur:
            cur.execute(
                "INSERT INTO orders (id, total, status) VALUES (%s, %s, %s) "
                "ON CONFLICT (id) DO UPDATE SET status = EXCLUDED.status",
                (order.id, order.total, order.status))
        self.conn.commit()

class InMemoryOrderRepository:          # test double, same port
    def __init__(self):
        self.saved = {}
    def save(self, order):
        self.saved[order.id] = order

class DecliningPayments:
    def charge(self, order_id, amount): return False

def test_failed_payment_is_recorded():
    orders = InMemoryOrderRepository()
    place = PlaceOrder(orders, DecliningPayments())
    place("A-17", Decimal("23.50"))
    assert orders.saved["A-17"].status == "payment-failed"

# composition root (main.py): the only place that knows every adapter
# place_order = PlaceOrder(PostgresOrderRepository(conn), CardProviderGateway(key))
# app.add_route("/orders", make_rest_controller(place_order))   # driving adapter

Fíjate en lo que el caso de uso no contiene: nada de SQL, ni códigos de estado HTTP, ni tipos de excepción específicos del proveedor, ni decoradores del framework. La prueba se ejecuta en milisegundos y cubre un caso (un pago rechazado) que sería incómodo de preparar contra el sandbox de un proveedor real. El adaptador de PostgreSQL necesita sus propias pruebas, pero son pruebas de integración centradas en una sola clase contra una base de datos real, no pruebas de reglas de negocio. Este es el beneficio para la capacidad de prueba descrito en la Sección 2.6: controlabilidad y observabilidad mediante dependencias inyectadas.

Costos, críticas y cuándo usarla

Los beneficios son reales, y también los costos. Cada puerto es una interfaz adicional; cada límite puede necesitar código de mapeo para convertir entre, por ejemplo, una entidad del ORM, un objeto de dominio y una respuesta de la API. Para una aplicación que sobre todo traslada campos de formulario a tablas con poca lógica entre medias, esta estructura añade archivos sin añadir protección, y las convenciones de un framework (un modelo active record, una interfaz de administración generada) pueden dar un resultado mejor y más rápido. Algunos profesionales con experiencia sostienen que las versiones estrictas de la arquitectura limpia producen demasiada indirección y que la mayoría de los equipos nunca cambian de base de datos; otros responden que el beneficio principal no es cambiar de tecnología, sino pruebas rápidas y fiables y un código de negocio que se puede leer sin conocer el framework. Ambos tienen razón en contextos distintos.

Úsala cuando la lógica de negocio es considerable y va a sobrevivir a los frameworks actuales; cuando el sistema se integra con servicios externos que probablemente cambien; cuando importan las pruebas rápidas y aisladas de las reglas de negocio; y como estructura interna de los módulos de un monolito modular o de servicios construidos con diseño guiado por el dominio (Sección 5.7). Ten cuidado con las aplicaciones CRUD sencillas, los prototipos y las herramientas de vida corta, donde la estructura predeterminada del framework suele bastar. Es común un término medio pragmático: puertos para los servicios externos y para todo lo que probablemente cambie, y las comodidades propias del framework en lo demás.

Hacer cumplir la regla de dependencia

Como ocurre con las capas, la regla se erosiona a menos que la compruebe una máquina. En Python, import-linter puede declarar los anillos como un contrato de tipo layers (adaptadores por encima de la aplicación, y esta por encima del dominio) y añadir contratos de tipo forbidden que impidan que los paquetes de dominio y de aplicación importen frameworks web, drivers de base de datos o SDK. En Java, ArchUnit tiene una regla ya preparada, onionArchitecture(), en la que nombras los paquetes del modelo de dominio, de los servicios de dominio, de los servicios de aplicación y de los adaptadores, y hace fallar una prueba si alguna dependencia apunta hacia fuera. Dividir el código en módulos de compilación separados (un módulo de dominio sin ninguna dependencia de frameworks) hace que las dependencias hacia fuera sean imposibles de compilar, que es la comprobación más fuerte de todas. Estas comprobaciones son ejemplos de las funciones de aptitud que se tratan en el Capítulo 11.

Una estructura de paquetes que hace visible la regla ayuda a quienes revisan: por ejemplo orders/domain, orders/application (casos de uso y puertos) y orders/adapters/{rest,postgres,payments}. Organizar primero por área de negocio y después por anillo mantiene la estructura alineada con los límites del dominio de las secciones 5.3 y 5.7.