¿Qué es arquitectura hexagonal en programación?

La arquitectura hexagonal, o de puertos y adaptadores, es un patrón de diseño de software que aísla la lógica de negocio de lo externo (interfaz, base de datos, APIs) mediante puertos, que son interfaces, y adaptadores, que las implementan. Así se prueba el núcleo sin infraestructura y se cambia de tecnología sin tocarlo. Lo describió Alistair Cockburn en 2005.

¿Has escuchado antes de la arquitectura hexagonal? 

Este tipo de arquitectura para los softwares ha dado mucho de qué hablar últimamente, y no nos sorprende en absoluto.

Se trata de una arquitectura que te permite crear una aplicación capaz de funcionar sin una interfaz de usuario o base de datos. Así, podrás trabajar en ella aún cuando la base no esté disponible y conectar las aplicaciones sin la intervención del usuario.

¿Quieres saber más sobre la arquitectura hexagonal? ¡Pues sigue leyendo!

¿Qué es la arquitectura hexagonal?

La arquitectura hexagonal, a la que también se le conoce como arquitectura de puertos y adaptadores, es una arquitectura de software que se basa en la idea de aislar la lógica comercial central de las preocupaciones externas, por medio de la separación de la aplicación en componentes débilmente acoplados.

Pero, ¿por qué no lo ilustramos a través de un ejemplo? Imaginemos que estamos creando una API que necesita obtener algunos datos de una API REST.

En lugar de tener nuestra clase de caso de uso (o clase de servicio) acoplada a la API REST externa, podemos crear un puerto, que define la interfaz que nuestra clase de caso de uso tiene que implementar para obtener los datos.

Luego podemos crear un Adapter, que es una clase que implementa la interfaz Port y delega las llamadas a la API REST externa u otro servicio externo.

De esta forma, si necesitamos cambiar la manera en que obtenemos los datos, solo necesitamos crear un nuevo adaptador que implemente la interfaz del puerto, sin tener que cambiar la implementación del caso de uso.

Ahora bien, el hexágono es solo una forma elegante de describir el núcleo de la aplicación que se compone de objetos de dominio, casos de uso que operan en ellos y puertos de entrada y salida que proporcionan una interfaz con el mundo exterior.

Quién creó la arquitectura hexagonal y por qué se llama así

La arquitectura de software hexagonal la planteó Alistair Cockburn, que fechó su artículo original el 4 de septiembre de 2005. Su objetivo era que una aplicación pudiera usarse igual desde una persona, un programa o un script de pruebas, y que se pudiera desarrollar y probar sin sus dispositivos y bases de datos finales.

El nombre es una convención de dibujo: el hexágono deja espacio para dibujar varias interfaces y no significa que haya seis puertos. Un servicio sencillo puede tener uno solo y otro mayor puede separar puertos para eventos, notificaciones, base de datos y administración (Wikipedia).

Los 3 principios de la arquitectura hexagonal

Este tipo de arquitectura de software se sustenta en 3 principios básicos a cumplir:

1. A la izquierda, el lado del usuario

Este es el lado a través del cual el usuario o los programas externos interactuarán con la aplicación, y es la que contiene el código que permite dichas interacciones. 

Por lo general, su código de interfaz de usuario, sus rutas HTTP para una API, sus serializaciones JSON para programas que consumen su aplicación están aquí.

Este es el lado donde encontramos a los actores que impulsan la Lógica de Negocios.

2. La Lógica de Negocios, en el centro

Esta es la parte que queremos aislar de los lados izquierdo y derecho. Contiene todo el código que concierne e implementa la lógica empresarial. 

El vocabulario empresarial y la lógica empresarial pura, que se relaciona con el problema concreto que resuelve su aplicación, todo lo que la hace rica y específica está en el centro. 

Idealmente, un experto en el dominio que no sabe cómo codificar, podría leer un fragmento de código en esta parte y señalarle una inconsistencia. De hecho, si lo piensas, es algo que podría pasarte si eres el desarrollador.

3. A la derecha, el lado del servidor

Aquí es donde encontraremos lo que tu aplicación necesita, lo que hace que funcione. 

Contiene detalles esenciales de la infraestructura, como el código que interactúa con la base de datos, realiza llamadas al sistema de archivos o el código que maneja las llamadas HTTP a otras aplicaciones de las que depende, por ejemplo.

Este es el lado donde encontramos a los actores que son manejados por la Lógica de Negocios.

¿Por qué es importante la arquitectura hexagonal?

Una primera característica importante de esta separación es que separa los problemas. En cualquier momento, puedes optar por centrarte en una única lógica, casi de manera independiente de las otras dos: lógica del lado del usuario, lógica empresarial o lógica del lado del servidor. 

Son más fáciles de entender sin mezclarlos y las restricciones de cada lógica tienen menos impacto en las demás.

Otra característica es que ponemos la lógica empresarial al frente de nuestro código. Se puede aislar en un directorio o módulo para que sea explícito para todos los desarrolladores. 

Puede definirse, refinarse y probarse sin asumir la carga cognitiva del resto del programa. Esto es importante porque al final, es la comprensión de los desarrolladores del negocio, es decir, lo que entra en producción.

Por último, en cuanto a las pruebas que se realizan de manera automática lograremos probar con un esfuerzo razonable:

• Toda la lógica de negocios individualmente.

• Integración entre el lado del usuario y la lógica de negocios independientemente del lado del servidor.

• Integración entre la lógica de negocios y el lado del servidor de forma independiente en el lado del usuario

Los estereotipos de la arquitectura hexagonal

Como todo tipo de arquitectura para el desarrollo de software, encontramos algunos estereotipos o características que identifican a la arquitectura hexagonal, ¿te parece si vemos algunos de ellos en detalle?

1. Objetos de dominio

En un dominio rico en reglas comerciales, los objetos de dominio son el elemento vital de una aplicación, y es que los objetos de dominio pueden contener tanto estado como comportamiento. 

Cuanto más cerca esté el comportamiento del estado, más fácil será entender, razonar y mantener el código.

Los objetos de dominio no tienen ninguna dependencia externa. Son Java puro y proporcionan una API para casos de uso para operar en ellos.

Dado que los objetos de dominio no dependen de otras capas de la aplicación, los cambios en otras capas no los afectan. Pueden evolucionar libres de dependencias. 

Este es un excelente ejemplo del principio de responsabilidad única, que establece que los componentes tienen que tener una sola razón para cambiar. Para nuestro objeto de dominio, este motivo es un cambio en los requisitos comerciales.

Tener una única responsabilidad nos permite evolucionar nuestros objetos de dominio sin tener que considerar dependencias externas. Esta capacidad de evolución hace que el estilo de arquitectura hexagonal sea perfecto para cuando se practica el diseño basado en dominios. 

Durante el desarrollo, simplemente seguimos el flujo natural de las dependencias: comenzamos a codificar en los objetos del dominio y salimos de allí. Si eso no es controlado por dominio, entonces ¿qué puede serlo?

2. Casos de uso

Conocemos los casos de uso como descripciones abstractas de lo que hacen los usuarios con nuestro software. En el estilo de arquitectura hexagonal, tiene sentido promover casos de uso a ciudadanos de primera clase de nuestra base de código.

Un caso de uso en este sentido es una clase que maneja todo, bueno, un cierto caso de uso. Como ejemplo, consideremos el caso de uso clásico: enviar dinero de una cuenta a otra en una aplicación bancaria. 

Crearíamos una clase SendMoneyUseCasecon una API distinta que permita a un usuario transferir dinero. El código contiene todas las validaciones y la lógica de las reglas comerciales que son específicas del caso de uso y, por lo tanto, no se pueden implementar dentro de los objetos del dominio. 

Similar a los objetos de dominio, una clase de caso de uso no depende de los componentes externos. Cuando necesita algo de fuera del hexágono, creamos un puerto de salida.

3. Puertos de entrada y salida

Los objetos de dominio y los casos de uso están dentro del hexágono, es decir, dentro del núcleo de la aplicación. Cada comunicación hacia y desde el exterior ocurre a través de puertos dedicados.

Un puerto de entrada es una interfaz simple a la que pueden llamar componentes externos y que se implementa mediante un caso de uso. El componente que llama a dicho puerto de entrada se denomina adaptador de entrada o adaptador de conducción.

Un puerto de salida es, de nuevo, una interfaz simple a la que nuestros casos de uso pueden llamar si necesitan algo desde el exterior, como acceso a la base de datos, por ejemplo. 

Esta interfaz está diseñada para adaptarse a las necesidades de los casos de uso, pero está implementada por un componente externo denominado adaptador de salida o controlado. 

Si estás familiarizado con los principios SOLID, esta es una aplicación del principio de inversión de dependencia, porque estamos invirtiendo la dependencia de los casos de uso al adaptador de salida mediante una interfaz.

Con los puertos de entrada y salida en su lugar, tenemos lugares muy distintos donde los datos ingresan y salen de nuestro sistema, lo que facilita el razonamiento sobre la arquitectura.

4. Adaptadores

Los adaptadores forman la capa exterior de la arquitectura hexagonal, por lo que no son parte del núcleo pero interactúan con él.

Los adaptadores de entrada o adaptadores de conducción llaman a los puertos de entrada para hacer algo. 

Un adaptador de entrada podría ser una interfaz web, por ejemplo. Cuando un usuario hace clic en un botón en un navegador, el adaptador web llama a un determinado puerto de entrada para llamar al caso de uso correspondiente.

Nuestros casos de uso llaman a los adaptadores de salida o adaptadores controlados y pueden, por ejemplo, proporcionar datos de una base de datos. Un adaptador de salida implementa un conjunto de interfaces de puerto de salida. Ten en cuenta que las interfaces están dictadas por los casos de uso y no al revés.

Los adaptadores facilitan el intercambio de una cierta capa de la aplicación. Si la aplicación tiene que poder utilizarse desde un cliente pesado además de la web, agregamos un adaptador de entrada de cliente pesado. 

Si la aplicación necesita una base de datos diferente, agregamos un nuevo adaptador de persistencia que implementa las mismas interfaces de puerto de salida que el anterior.

Cómo funciona la arquitectura hexagonal: ejemplo mínimo de puerto y adaptador en Java

Funciona invirtiendo una dependencia: el caso de uso define lo que necesita (un puerto) y la tecnología concreta se enchufa desde fuera (un adaptador). Este ejemplo mínimo en Java, escrito para este artículo, consulta un cliente sin que el núcleo sepa dónde se guardan los datos.

1. Definimos el puerto de salida dentro del núcleo, con el lenguaje del negocio.

2. El caso de uso, que implementa el puerto de entrada, recibe ese puerto por constructor.

3. Un adaptador de salida lo implementa con la tecnología elegida. Cambiar de base de datos es escribir otro adaptador.

// Núcleo (hexágono)
public record Cliente(String id, String nombre) {}

public class ClienteNoEncontrado extends RuntimeException {
    public ClienteNoEncontrado(String id) { super("Cliente no encontrado: " + id); }
}

// Puerto de entrada: lo llaman los adaptadores de entrada (web, CLI, tests)
public interface ObtenerClienteUseCase {
    Cliente ejecutar(String id);
}

// Puerto de salida: lo define el caso de uso, lo implementa el exterior
public interface ClienteRepositorio {
    java.util.Optional<Cliente> buscarPorId(String id);
}

// Caso de uso: no importa ningún framework ni librería de base de datos
public class ObtenerClienteService implements ObtenerClienteUseCase {
    private final ClienteRepositorio repositorio;

    public ObtenerClienteService(ClienteRepositorio repositorio) {
        this.repositorio = repositorio;
    }

    @Override
    public Cliente ejecutar(String id) {
        return repositorio.buscarPorId(id).orElseThrow(() -> new ClienteNoEncontrado(id));
    }
}

// Adaptador de salida (fuera del hexágono): aquí podría ir JPA, JDBC o una API REST
public class ClienteRepositorioEnMemoria implements ClienteRepositorio {
    private final java.util.Map<String, Cliente> datos = new java.util.HashMap<>();

    public void guardar(Cliente c) { datos.put(c.id(), c); }

    @Override
    public java.util.Optional<Cliente> buscarPorId(String id) {
        return java.util.Optional.ofNullable(datos.get(id));
    }
}

// Núcleo (hexágono)
public record Cliente(String id, String nombre) {}

public class ClienteNoEncontrado extends RuntimeException {
    public ClienteNoEncontrado(String id) { super("Cliente no encontrado: " + id); }
}

// Puerto de entrada: lo llaman los adaptadores de entrada (web, CLI, tests)
public interface ObtenerClienteUseCase {
    Cliente ejecutar(String id);
}

// Puerto de salida: lo define el caso de uso, lo implementa el exterior
public interface ClienteRepositorio {
    java.util.Optional<Cliente> buscarPorId(String id);
}

// Caso de uso: no importa ningún framework ni librería de base de datos
public class ObtenerClienteService implements ObtenerClienteUseCase {
    private final ClienteRepositorio repositorio;

    public ObtenerClienteService(ClienteRepositorio repositorio) {
        this.repositorio = repositorio;
    }

    @Override
    public Cliente ejecutar(String id) {
        return repositorio.buscarPorId(id).orElseThrow(() -> new ClienteNoEncontrado(id));
    }
}

// Adaptador de salida (fuera del hexágono): aquí podría ir JPA, JDBC o una API REST
public class ClienteRepositorioEnMemoria implements ClienteRepositorio {
    private final java.util.Map<String, Cliente> datos = new java.util.HashMap<>();

    public void guardar(Cliente c) { datos.put(c.id(), c); }

    @Override
    public java.util.Optional<Cliente> buscarPorId(String id) {
        return java.util.Optional.ofNullable(datos.get(id));
    }
}

// Núcleo (hexágono)
public record Cliente(String id, String nombre) {}

public class ClienteNoEncontrado extends RuntimeException {
    public ClienteNoEncontrado(String id) { super("Cliente no encontrado: " + id); }
}

// Puerto de entrada: lo llaman los adaptadores de entrada (web, CLI, tests)
public interface ObtenerClienteUseCase {
    Cliente ejecutar(String id);
}

// Puerto de salida: lo define el caso de uso, lo implementa el exterior
public interface ClienteRepositorio {
    java.util.Optional<Cliente> buscarPorId(String id);
}

// Caso de uso: no importa ningún framework ni librería de base de datos
public class ObtenerClienteService implements ObtenerClienteUseCase {
    private final ClienteRepositorio repositorio;

    public ObtenerClienteService(ClienteRepositorio repositorio) {
        this.repositorio = repositorio;
    }

    @Override
    public Cliente ejecutar(String id) {
        return repositorio.buscarPorId(id).orElseThrow(() -> new ClienteNoEncontrado(id));
    }
}

// Adaptador de salida (fuera del hexágono): aquí podría ir JPA, JDBC o una API REST
public class ClienteRepositorioEnMemoria implements ClienteRepositorio {
    private final java.util.Map<String, Cliente> datos = new java.util.HashMap<>();

    public void guardar(Cliente c) { datos.put(c.id(), c); }

    @Override
    public java.util.Optional<Cliente> buscarPorId(String id) {
        return java.util.Optional.ofNullable(datos.get(id));
    }
}

El mismo adaptador en memoria sirve para los tests: pruebas el caso de uso completo sin base de datos, que es justo lo que promete el patrón (si quieres herramientas para esas pruebas, mira nuestra guía de testing automatizado). Si usas Spring Boot, el framework se queda en los adaptadores y en la configuración; el núcleo sigue siendo Java puro.

Ventajas de la arquitectura hexagonal

Para los desarrolladores, la arquitectura hexagonal ofrece varias ventajas, por lo que vale la pena mencionar algunas de ellas. 

• Retrasar las decisiones sobre tecnologías: la arquitectura hexagonal te permite decidir comenzar a escribir un proyecto y, de hecho, construirlo y probarlo, mientras pospone las decisiones tecnológicas que involucrarían conocimientos y datos que pueden no estar disponibles al comienzo de un proyecto.

• Cambiar de tecnología con menor impacto: gracias a la arquitectura hexagonal, las empresas tecnológicas pueden decidir comenzar con la tecnología más simple (como la clásica base de datos relacional) y luego pasar a otra simplemente cambiando el adaptador.

• Prueba la lógica empresarial aislada de los sistemas externos: Gracias a las interfaces, es posible crear stubs o simulacros para probar tu dominio central y tu lógica empresarial aislada de los sistemas externos. Esto confirmará que cualquier cambio en la tecnología no afectará la lógica comercial.

• Remodele su dominio interno con menos esfuerzo en los sistemas externos: en cierto punto, el dominio interno evolucionará. Si el equipo técnico ha podido desacoplar con éxito y mantener en los adaptadores externos sólo el subconjunto de datos que necesitan, esto tendría que resultar en un precio más bajo y menos esfuerzo.

Sin embargo, no todo es bueno con la arquitectura hexagonal. Claro, que el principal inconveniente es que este tipo de separación le costará más esfuerzo al equipo técnico al crear interfaces y mapear diferentes dominios.

Arquitectura hexagonal frente a Clean, Onion y capas clásicas

Las cuatro separan la lógica de negocio de la tecnología, con vocabulario y dibujo distintos. La tabla resume quién propuso cada una, según las fuentes originales.

Fuentes: Cockburn (2005), Palermo (2008), Martin (2012) y Fowler (2015).

Mi criterio: si ya entiendes la hexagonal, Onion y Clean no te enseñan una idea nueva. Martin lo dice a su manera: todas persiguen independencia de frameworks, de la interfaz y de la base de datos, y poder probar las reglas de negocio sin nada de eso. Elige la que tu equipo sepa explicar en cinco minutos y respete en el código.

Cuándo usar la arquitectura hexagonal y cuándo no

Compensa cuando la lógica de negocio es compleja, la aplicación vivirá años o tendrás que cambiar de base de datos, proveedor o canal de entrada. Palermo advierte que su variante cebolla encaja en aplicaciones empresariales de larga vida y no en webs pequeñas, y lo mismo vale aquí.

No compensa en un script, un prototipo desechable o un CRUD sin reglas de negocio: crearías interfaces y mapeos para nada. Fowler recomienda aplicar esta separación a pequeña escala y, cuando el sistema crece, dividirlo en módulos orientados al dominio con capas internas.

Arquitectura hexagonal en 2026: microservicios, DDD, frameworks e IA

El patrón tiene más de veinte años y sigue vigente porque no depende de ninguna tecnología.

• Microservicios. Cada servicio puede tener su propio hexágono: el núcleo del servicio no sabe si le llegan peticiones por HTTP o por una cola de mensajes. Si quieres el contexto, lee nuestro artículo sobre microservicios escalables.

• Frameworks. En Spring Boot, cuya documentación oficial muestra la serie 4.x como vigente en octubre de 2026, el framework hace de adaptador: controladores y repositorios fuera, casos de uso sin anotaciones dentro.

• Asistentes de IA. Según la encuesta de Stack Overflow de 2025, el 84 % de los desarrolladores usa o planea usar herramientas de IA (76 % en 2024), y el 46 % desconfía de la exactitud de lo que generan. Varios desarrolladores sostienen que unos límites claros entre núcleo y adaptadores acotan el daño que puede hacer un agente de IA al editar código (ejemplo). Es una opinión de práctica, no un resultado medido: no hay estudios controlados que lo confirmen. Lo que sí es verificable es que los tests sobre el núcleo, sin infraestructura, te sirven para revisar código que no has escrito tú.

El futuro es de quienes saben
construir tecnología

| Título + Especialización

El programa para desarrollar habilidades tech desde cero y entrar en el mundo digital.

Descubre Rock the AI Code →

El futuro es de quienes saben
construir tecnología

| Título + Especialización

El programa para desarrollar habilidades tech desde cero y entrar en el mundo digital.

Descubre Rock the AI Code →

Preguntas frecuentes sobre la arquitectura hexagonal

¿Qué es la arquitectura hexagonal en software?

Es un estilo de arquitectura que coloca la lógica de negocio en el centro y la rodea de puertos (interfaces) y adaptadores (implementaciones concretas para la web, la base de datos u otros servicios). El núcleo no conoce la tecnología externa, de modo que puedes probarlo solo y cambiar la infraestructura sin reescribirlo.

¿Cómo funciona la arquitectura hexagonal?

El exterior habla con el núcleo a través de puertos de entrada, que implementan los casos de uso. Cuando el núcleo necesita algo de fuera, como guardar un dato, llama a un puerto de salida, que implementa un adaptador. Las dependencias apuntan siempre hacia el núcleo, nunca al revés.

¿Qué es una arquitectura hexagonal y por qué se llama así?

Es un patrón de diseño de software creado por Alistair Cockburn en 2005. Se llama hexagonal porque el hexágono es una forma de dibujo que deja sitio para varias interfaces alrededor del núcleo. No quiere decir que tenga seis puertos: puede tener uno, tres o diez.

¿Qué es la arquitectura hexagonal en Java?

Es aplicar el patrón con interfaces Java: el puerto es una interface del núcleo, el caso de uso la usa y el adaptador, por ejemplo con JPA o JDBC, la implementa. El núcleo se escribe en Java sin anotaciones de Spring ni de persistencia, y el framework solo vive en los adaptadores.

¿Cuál es la diferencia entre arquitectura hexagonal y Clean Architecture?

La hexagonal (Cockburn, 2005) se centra en puertos y adaptadores; la Clean Architecture (Martin, 2012) añade círculos concéntricos y una regla de dependencia estricta, y declara que integra la hexagonal, la cebolla y otras. En la práctica comparten objetivos y se combinan sin problema.