Arquitectura hexagonal: explicación clara y cuándo NO usarla
Introducción
La arquitectura hexagonal (Ports & Adapters) se ha convertido en una palabra fetiche: se menciona como si fuera un estándar universal de “buen diseño”. Y ahí está la trampa.
Hexagonal no es un diagrama ni una forma de ordenar carpetas. Es una política de dependencias que introduce coste cognitivo a cambio de una promesa: proteger el corazón del sistema (reglas de negocio) de lo que cambia más (frameworks, bases de datos, protocolos, integraciones, colas, UI…).
Cuando esa promesa se cumple, hexagonal es una inversión excelente. Cuando no se cumple, es sobreingeniería disfrazada de “arquitectura”. Vamos a separarlo con claridad, ejemplos y criterios.
Hexagonal en una frase
El dominio no depende de la infraestructura. El dominio define contratos (puertos) y el mundo exterior se adapta (adaptadores).
El problema real que resuelve (y por qué importa)
Hexagonal aparece cuando un sistema empieza a pagar dos impuestos:
- Impuesto al cambio: cada requisito nuevo obliga a tocar demasiadas piezas técnicas.
- Impuesto al test: probar una regla de negocio requiere levantar medio entorno.
En esa fase, el sistema deja de ser “software” y se convierte en “miedo”: miedo a modificar, miedo a desplegar, miedo a refactorizar. Hexagonal intenta devolver control: que el cambio se quede cerca del dominio y que los detalles sean reemplazables.
Mapa mental (sin código)
Piensa en el sistema como un núcleo con entradas y salidas:
- Puertos de entrada: lo que el sistema ofrece (casos de uso, operaciones de negocio).
- Puertos de salida: lo que el sistema necesita del exterior (persistencia, email, pagos, APIs, colas…).
- Adaptadores: implementaciones concretas de esos puertos (HTTP, DB, mensajería, ficheros…)
Canales de entrada (HTTP, UI, batch, eventos)
│
▼
[Puertos de entrada / Casos de uso]
│
▼
[Dominio]
│
▼
[Puertos de salida] ──► Adaptadores (DB, APIs, colas, email)
El detalle importante no es el dibujo. Es la dirección del acoplamiento: el dominio define “qué necesita”, y lo de fuera se pliega.
Qué NO es hexagonal (y conviene dejarlo claro)
- No es “poner interfaces a todo”. Eso es burocracia, no arquitectura.
- No es “microservicios”. Hexagonal puede vivir perfectamente en un monolito modular.
- No es “DDD”. Encaja bien con DDD, pero no son lo mismo.
- No es “más capas por capricho”. Es menos dependencia del detalle, no más carpetas.
Cuándo hexagonal aporta valor de verdad
Hexagonal suele ser una buena inversión cuando se cumplen varias condiciones (no una sola):
| Señal | Qué significa | Por qué hexagonal ayuda |
|---|---|---|
| Dominio con reglas e invariantes reales | No es CRUD, hay lógica que importa | Proteges el conocimiento valioso y reduces regresiones |
| Múltiples canales de entrada | API + batch + eventos + UI… | Reutilizas casos de uso sin duplicar lógica |
| Integraciones externas críticas | Pagos, ERPs, logística, identidad, etc. | Aíslas dependencias volátiles detrás de puertos |
| Necesidad real de testabilidad rápida | Tests lentos o frágiles | Testas reglas sin infraestructura pesada |
| Vida larga del sistema | Producto que evoluciona años | Amortizas coste cognitivo con cambios más baratos |
Casos de uso buenos (donde hexagonal suele brillar)
1) Producto con reglas complejas y cambios frecuentes
Ejemplo típico: pricing, promociones, disponibilidad, reservas, reglas de elegibilidad, scoring, conciliación… La lógica cambia porque el negocio cambia. Hexagonal ayuda a que el cambio afecte al núcleo y no se disperse en tecnología.
2) Misma lógica expuesta por varios canales
API pública para clientes + panel interno + procesamiento nocturno + eventos de terceros. Si no hay hexagonal (o límites similares), terminas copiando lógica o inyectando reglas en cada canal. Eso es una fábrica de inconsistencias.
3) Integraciones “pluggables” o reemplazables
Cambiar proveedor de pagos, mensajería, OCR, verificación de identidad, motor de notificaciones… En proyectos reales, el “vendor swap” ocurre. Si la integración está mezclada con el dominio, el cambio es traumático.
4) Sistemas regulados o con auditoría fuerte
Cuando necesitas evidencias, trazabilidad y controles (por normativa o por impacto reputacional), te conviene separar claramente reglas, decisiones y efectos. Hexagonal facilita aislar responsabilidades y controlar cambios.
Casos de uso malos (donde suele ser sobreingeniería)
1) CRUD simple y estable
Si tu sistema es básicamente alta/baja/modificación/consulta con poca lógica, hexagonal suele ser ruido. Metes capas, mappers y puertos sin necesidad: el coste cognitivo sube y el valor no aparece.
2) Prototipos o productos con fecha de caducidad
Si el objetivo es validar mercado o entregar algo temporal, el enfoque sano es simplicidad y velocidad controlada. Hexagonal puede ser “arquitectura de escaparate”: te hace sentir bien, pero te frena.
3) Equipo sin contexto y sin acompañamiento
Hexagonal requiere criterio. Sin criterio, el resultado típico es: interfaces vacías, carpetas duplicadas, mappers sin fin y un sistema que nadie entiende. En ese escenario, el patrón no eleva: confunde.
Errores típicos (los que convierten hexagonal en burocracia)
| Error | Qué ocurre | Cómo se corrige |
|---|---|---|
| Interfaces por deporte | Ruido + coste cognitivo | Puertos solo donde hay cambio real o dependencia externa |
| Dominio “anémico” | El dominio no decide nada, solo datos | Reglas e invariantes dentro del dominio, no en adaptadores |
| Adaptadores demasiado listos | La lógica se escurre a HTTP/DB/mensajería | Adaptador traduce y delega; no gobierna el negocio |
| Mapa de dependencias roto | El núcleo vuelve a depender de detalles | Reglas automáticas/convenciones + revisión en PR |
| “Reescritura total” | Refactor infinito, producto bloqueado | Adopción incremental por casos de uso, sin big-bang |
Guía práctica: cómo diseñar puertos sin caer en “interfaces genéricas”
La calidad de una arquitectura hexagonal se decide en el diseño de puertos. Un buen puerto:
- habla en lenguaje del dominio (no “save”, “manager”, “helper”),
- expresa una intención (“registrar pago”, “emitir factura”, “calcular precio”),
- evita filtrar detalles técnicos (SQL, HTTP, SDKs) al núcleo.
Regla simple: si el puerto “podría ser de cualquier proyecto”, probablemente está mal diseñado.
Guía de adopción incremental (sin romper el proyecto)
La adopción profesional de hexagonal no se hace “transformando todo”. Se hace por fricción:
- Elige un caso de uso con dolor real (bugs, cambios frecuentes, tests lentos).
- Define el núcleo de decisión (reglas e invariantes) y muévelo a un área sin dependencias externas.
- Introduce un puerto de salida solo para la dependencia que te duele (DB, pagos, email…).
- Haz que el canal de entrada (API/batch/evento) sea un adaptador fino que solo traduzca.
- Valida con tests rápidos en el núcleo y con tests de borde en adaptadores.
- Repite con el siguiente caso de uso. Sin big-bang.
Cómo saber si tu hexagonal “está viva” o es solo un dibujo
Señales de que funciona:
- puedes testear reglas sin levantar infraestructura,
- puedes cambiar un proveedor externo tocando poco código,
- los controladores/handlers son finos,
- los cambios de negocio se quedan cerca del núcleo.
Señales de que es postureo:
- los adaptadores contienen la lógica real,
- el dominio es un DTO gigante,
- hay interfaces duplicadas sin necesidad,
- nadie sabe dónde tocar para un cambio simple.
Checklist de decisión (para elegir con criterio)
- ¿Hay reglas de negocio con peso y cambios frecuentes?
- ¿Tengo más de un canal de entrada (o lo tendré)?
- ¿Mis dependencias externas cambian o condicionan el negocio?
- ¿Me cuesta testear rápido y con confianza?
- ¿Tengo capacidad operativa/cultural para sostener límites?
- ¿Podría resolverlo con un monolito modular bien hecho sin añadir más capas?
Conclusión
Hexagonal no es “mejor diseño” por defecto. Es una herramienta para escenarios concretos: proteger el dominio, reducir coste de cambio y mejorar el testeo cuando el sistema y el negocio lo justifican.
Si lo aplicas por moda, pagas complejidad sin retorno. Si lo aplicas por criterio, te compras estabilidad y capacidad de evolución. En Gondor defendemos arquitectura consciente: menos dogma, más sistemas que se pueden mantener y operar.