Arquitectura hexagonal en Java: puertos, adaptadores y dominio aislado
Cómo separar las reglas de negocio de Spring, de la base de datos y del broker de mensajería, y qué cambia en el día a día de un equipo cuando esa separación existe de verdad.
Un núcleo de negocio que no conoce ninguna tecnología
También llamada puertos y adaptadores, la arquitectura hexagonal invierte la dirección de las dependencias: el dominio deja de depender de la infraestructura y pasa a definirla.
El estilo lo formuló Alistair Cockburn con un objetivo concreto: que la lógica de negocio no dependa de ninguna tecnología. El dominio define interfaces —los puertos— y la infraestructura las implementa —los adaptadores—, de modo que todas las dependencias apuntan hacia dentro.
El nombre del hexágono es incidental. No importan los seis lados, sino que exista un único núcleo rodeado de adaptadores intercambiables. Da igual si la entrada llega por HTTP, por un consumidor de Kafka o desde un test: para el dominio es la misma llamada a un puerto.
La regla práctica que resume todo el estilo cabe en una línea: ninguna clase del dominio importa nada de un framework. Si el paquete de dominio tiene un import org.springframework o un import jakarta.persistence, la arquitectura ya no es hexagonal, independientemente de cómo se llamen las carpetas.
Puertos y adaptadores
Un puerto es una interfaz que el dominio define con su propio vocabulario. Un adaptador es su implementación con una tecnología concreta.
Puertos de entrada
Los casos de uso que el exterior invoca: RegistrarPedido, ConsultarSaldo. Sus adaptadores son controladores REST, consumidores de mensajes o tareas programadas.
Puertos de salida
Las capacidades que el dominio necesita: RepositorioDePedidos, NotificadorDeCliente. Sus adaptadores usan JPA, un cliente HTTP o un productor de Kafka.
La diferencia crítica está en quién define la interfaz. El puerto de salida lo declara el dominio, con su lenguaje y sus tipos, no la capa de persistencia. Si la interfaz del repositorio devuelve entidades JPA en lugar de agregados del dominio, la inversión de dependencias no ha ocurrido: solo se ha añadido una interfaz.
La diferencia con la arquitectura en capas se mide en las pruebas
En la arquitectura en capas las dependencias fluyen hacia abajo y el dominio acaba dependiendo de la persistencia, de modo que un cambio de ORM o de base de datos se propaga hasta las reglas de negocio. En la hexagonal fluyen hacia el centro.
La consecuencia se nota al escribir tests. Con capas, verificar una regla de negocio suele exigir levantar el contexto de Spring y una base de datos en memoria. Con puertos y adaptadores, esa misma regla se prueba con objetos planos y dobles de prueba en milisegundos, y la suite de dominio se ejecuta en cada guardado.
La segunda consecuencia es la reversibilidad. Cambiar de Oracle a PostgreSQL, o de RabbitMQ a Kafka, es sustituir un adaptador cuando el dominio no los conoce. En una arquitectura en capas ese mismo cambio alcanza a las clases que contienen las reglas de negocio.
Cómo se traduce a un proyecto Spring Boot
Tres decisiones concretas: organizar por dominio en lugar de por capa técnica, mantener el dominio libre de Spring y declarar los adaptadores en la capa de infraestructura.
dominio/
Agregados, objetos de valor, servicios de dominio y las interfaces de los puertos. Sin una sola anotación de framework.
aplicacion/
Casos de uso que orquestan el dominio y definen los límites transaccionales de cada operación de negocio.
infraestructura/
Controladores REST, repositorios JPA, clientes HTTP, productores y consumidores, y la configuración de Spring.
Un matiz que suele pasarse por alto: las entidades JPA no son los agregados del dominio. Compartirlas ahorra unas cuantas clases de mapeo y a cambio ata el modelo de negocio al esquema relacional, que es exactamente lo que el estilo pretende evitar.
El detalle completo, con el código de cada capa y sus pruebas, está en la guía de arquitectura hexagonal desde cero.
Cuándo compensa y cuándo es sobreingeniería
Compensa cuando el sistema tiene reglas de negocio propias que van a evolucionar durante años y cuando la vida esperada del proyecto supera con holgura la de las tecnologías que usa.
No compensa en un CRUD sin lógica, en un prototipo desechable ni en un servicio cuya única función es transformar y reenviar datos. En esos casos la indirección añade clases sin comprar nada, porque no hay dominio que proteger.
El indicador más honesto es preguntarse qué pasaría si mañana hubiera que cambiar la base de datos o el framework web. Si la respuesta es «habría que revisar las reglas de negocio», el estilo aportará valor. Si es «casi nada, apenas hay lógica», no lo hará.
Preguntas frecuentes
Dudas habituales sobre arquitectura hexagonal en proyectos empresariales.
¿Qué es la arquitectura hexagonal?
La arquitectura hexagonal, también conocida como puertos y adaptadores, es un estilo arquitectónico propuesto por Alistair Cockburn en el que la lógica de negocio no depende de ninguna tecnología concreta. El dominio define interfaces llamadas puertos y la infraestructura las implementa mediante adaptadores, de modo que todas las dependencias apuntan hacia el núcleo. La regla que la resume es que ninguna clase del dominio importa nada de un framework.
¿Qué diferencia hay entre arquitectura hexagonal y arquitectura en capas?
En la arquitectura en capas las dependencias fluyen hacia abajo y el dominio acaba dependiendo de la persistencia. En la hexagonal fluyen hacia el centro: la persistencia depende del dominio. La consecuencia práctica es que las reglas de negocio se prueban sin base de datos ni contexto del framework, y que cambiar de base de datos o de broker de mensajería consiste en sustituir un adaptador en lugar de tocar el negocio.
¿Qué son los puertos y los adaptadores?
Un puerto es una interfaz definida por el dominio que describe algo que necesita o que ofrece, expresado en su propio vocabulario; un adaptador es su implementación con una tecnología concreta. Los puertos de entrada son los casos de uso que el exterior invoca y sus adaptadores son controladores REST o consumidores de mensajes. Los puertos de salida son capacidades que el dominio requiere, como un repositorio, y sus adaptadores usan JPA, HTTP o Kafka.
¿Cómo se implementa la arquitectura hexagonal con Spring Boot?
Se implementa organizando los paquetes por dominio en lugar de por capa técnica, manteniendo el módulo de dominio sin ninguna dependencia de Spring y declarando los beans de los adaptadores en la capa de infraestructura. Una estructura habitual separa dominio (agregados y puertos, sin anotaciones), aplicación (casos de uso y límites transaccionales) e infraestructura (controladores, repositorios JPA, clientes y configuración de Spring).
¿Cuándo compensa aplicar arquitectura hexagonal?
Compensa cuando el sistema tiene reglas de negocio propias que van a evolucionar durante años y cuando la vida esperada del proyecto supera la de sus tecnologías. No compensa en un CRUD sin lógica, en un prototipo desechable ni en un servicio que solo transforma y reenvía datos, porque la indirección añade clases sin proteger ningún dominio.
Recursos relacionados
Páginas pilar, guías y casos reales que amplían lo tratado aquí.
- Arquitectura Java El marco general en el que encaja este patrón.
- Domain-Driven Design Cómo modelar el dominio que la hexagonal protege.
- Guía completa con código Implementación paso a paso con Spring Boot y DDD.
- Spring Boot Estructura de proyecto y buenas prácticas.
- Java Microservicios Del monolito modular a los servicios distribuidos.
- Casos reales Arquitecturas hexagonales aplicadas en producción.
¿Quieres aplicar arquitectura hexagonal en tu plataforma Java?
Diseño la estructura, defino los puertos y acompaño al equipo durante la implementación para que el patrón llegue completo a producción.