¿Qué es la Arquitectura Hexagonal?

La Arquitectura Hexagonal, también conocida como Ports & Adapters, es un estilo arquitectónico propuesto por Alistair Cockburn cuyo objetivo principal consiste en aislar completamente la lógica de negocio de cualquier detalle técnico.

En una aplicación tradicional es habitual encontrar reglas de negocio mezcladas con controladores REST, consultas SQL, anotaciones de frameworks o librerías externas. Con el paso del tiempo esto provoca un fuerte acoplamiento que dificulta el mantenimiento y hace que cualquier cambio tenga un impacto mayor del esperado.

La Arquitectura Hexagonal propone invertir esa dependencia. El dominio deja de conocer tecnologías como Spring Boot, Hibernate, Kafka o PostgreSQL y pasa a depender únicamente de abstracciones. De esta manera el negocio permanece estable mientras la infraestructura puede evolucionar libremente.

¿Qué problema resuelve la Arquitectura Hexagonal?

Antes de entender la solución, es necesario comprender el problema. La mayoría de aplicaciones Java comienzan con una arquitectura sencilla basada en capas: controladores, servicios, repositorios y base de datos.

Este enfoque funciona correctamente en proyectos pequeños, pero conforme la aplicación crece empiezan a aparecer dependencias entre capas, reglas de negocio repartidas por todo el código y una fuerte dependencia del framework utilizado.

Los síntomas aparecen muy rápido

En muchas empresas la lógica de negocio acaba dependiendo más del framework que del propio dominio del negocio.

El verdadero problema

El problema no es Spring Boot, Hibernate o cualquier otra tecnología. El problema aparece cuando el dominio conoce esos detalles técnicos.

Si nuestras entidades contienen anotaciones de persistencia, nuestros casos de uso llaman directamente a repositorios JPA y la lógica de negocio conoce cómo se almacenan los datos, el dominio deja de ser independiente y cualquier cambio tecnológico afecta directamente al corazón de la aplicación.

¿Cómo funciona la Arquitectura Hexagonal?

La Arquitectura Hexagonal organiza toda la aplicación alrededor del dominio de negocio. En lugar de colocar la base de datos o el framework en el centro del diseño, el protagonista pasa a ser el propio negocio.

Todo aquello relacionado con tecnologías externas (REST, Kafka, PostgreSQL, MongoDB, Redis, RabbitMQ, servicios cloud, etc.) permanece fuera del núcleo de la aplicación y únicamente se comunica con él a través de contratos bien definidos llamados Puertos (Ports).

El dominio siempre ocupa el centro

El dominio contiene únicamente las reglas del negocio. No conoce Spring Boot. No conoce Hibernate. No conoce PostgreSQL. No conoce Kafka. Tampoco sabe si la aplicación es una API REST, GraphQL o una aplicación de escritorio.

Los Puertos (Ports)

Los puertos son interfaces que definen cómo el dominio necesita comunicarse con el exterior.

El dominio no sabe cómo se almacenan los datos. Simplemente define un contrato indicando qué necesita.

public interface CustomerRepository {

    Customer save(Customer customer);

    Optional<Customer> findById(Long id);

}

Obsérvese que esta interfaz no depende de Spring Data JPA, Hibernate ni ninguna otra librería.

Los Adaptadores (Adapters)

Los adaptadores implementan esos contratos utilizando una tecnología concreta.

@Repository
public class JpaCustomerRepository
        implements CustomerRepository {

    private final SpringCustomerRepository repository;

    @Override
    public Customer save(Customer customer){

        return repository.save(customer);

    }

}

Si mañana decides sustituir PostgreSQL por MongoDB, únicamente cambiará este adaptador. El dominio continuará exactamente igual.

La Arquitectura Hexagonal no intenta organizar carpetas. Intenta organizar las dependencias.

Implementando Puertos y Adaptadores

Una vez comprendido el concepto de Arquitectura Hexagonal, llega el momento de trasladarlo a un proyecto real.

Uno de los errores más habituales consiste en pensar que basta con crear carpetas llamadas domain o application. En realidad, lo importante es respetar la dirección de las dependencias y mantener el dominio completamente aislado de cualquier tecnología externa.

Estructura recomendada

src/main/java

com.freelance.architecture

├── domain
│   ├── model
│   ├── ports
│   ├── services
│   └── exceptions
│
├── application
│   └── usecases
│
├── infrastructure
│   ├── persistence
│   ├── messaging
│   ├── configuration
│   └── security
│
└── adapters
    ├── inbound
    │   └── rest
    └── outbound
        ├── jpa
        └── kafka

Esta organización permite localizar rápidamente cada responsabilidad y evita que las tecnologías de infraestructura se mezclen con el dominio.

El caso de uso

Los Use Cases representan las acciones que el negocio puede realizar. No contienen detalles de infraestructura ni conocen cómo se almacenan los datos.

public class CreateCustomerUseCase {

    private final CustomerRepository repository;

    public CreateCustomerUseCase(CustomerRepository repository){

        this.repository = repository;

    }

    public Customer execute(CreateCustomerCommand command){

        Customer customer = new Customer(

            command.name(),
            command.email()

        );

        return repository.save(customer);

    }

}

El adaptador de persistencia

El adaptador es el responsable de traducir el contrato definido por el dominio hacia una tecnología concreta.

@Repository
public class JpaCustomerRepositoryAdapter
        implements CustomerRepository {

    private final SpringDataRepository repository;

    @Override
    public Customer save(Customer customer){

        CustomerEntity entity = mapper.toEntity(customer);

        return mapper.toDomain(

            repository.save(entity)

        );

    }

}

Si el día de mañana decides sustituir JPA por MongoDB únicamente tendrás que crear un nuevo adaptador.

El controlador REST

El controlador deja de contener reglas de negocio y se limita a recibir la petición HTTP, construir el comando correspondiente y delegar en el caso de uso.

@RestController
@RequestMapping("/customers")
public class CustomerController {

    private final CreateCustomerUseCase useCase;

    @PostMapping
    public CustomerResponse create(

        @RequestBody CreateCustomerRequest request){

        return mapper.toResponse(

            useCase.execute(

                mapper.toCommand(request)

            )

        );

    }

}

Cada componente conoce únicamente la responsabilidad que le corresponde. Esa separación es la clave para construir aplicaciones fáciles de evolucionar.

Implementación completa con Spring Boot

Uno de los mayores errores al adoptar Arquitectura Hexagonal consiste en pensar que Spring Boot desaparece de la aplicación. No es así.

Spring Boot sigue siendo una excelente herramienta para construir APIs, configurar la aplicación e integrar componentes externos. La diferencia es que deja de ocupar el centro del diseño y pasa a convertirse en un simple detalle de infraestructura.

En una aplicación correctamente diseñada, el dominio podría ejecutarse incluso sin Spring Boot. El framework únicamente conecta el mundo exterior con los casos de uso.

Dependencias Maven

La infraestructura depende de Spring Boot, mientras que el dominio no tiene ninguna dependencia del framework.

<dependencies>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>

    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
    </dependency>

</dependencies>

Configuración de Spring

Los casos de uso son clases Java normales. Spring únicamente se encarga de instanciarlas mediante configuración.

@Configuration
public class CustomerConfiguration {

    @Bean
    CreateCustomerUseCase createCustomerUseCase(
            CustomerRepository repository){

        return new CreateCustomerUseCase(repository);

    }

}

Ventajas de este enfoque

Una petición completa

Cuando un cliente realiza una petición HTTP, el flujo siempre es el mismo:

HTTP Request

↓

REST Controller

↓

Application Use Case

↓

Output Port

↓

Persistence Adapter

↓

Database

↓

Application Use Case

↓

REST Response

Spring Boot ya no es el corazón de la aplicación. Es simplemente una herramienta para conectar el dominio con el exterior.

Arquitectura Hexagonal y Domain-Driven Design

Uno de los mayores beneficios de la Arquitectura Hexagonal es que encaja de forma natural con Domain-Driven Design (DDD). Ambos enfoques persiguen exactamente el mismo objetivo: situar el dominio de negocio en el centro de la aplicación y evitar que las decisiones técnicas condicionen las reglas del negocio.

Mientras que la Arquitectura Hexagonal define cómo deben organizarse las dependencias, Domain-Driven Design proporciona un conjunto de patrones para modelar correctamente el dominio.

Las piezas del dominio

Una entidad de dominio

public class Customer {

    private CustomerId id;

    private Name name;

    private Email email;

    public Customer(Name name, Email email){

        this.name = name;

        this.email = email;

    }

    public void changeEmail(Email newEmail){

        this.email = newEmail;

    }

}

Observa que esta entidad no contiene anotaciones de Hibernate, Lombok ni Spring Boot. Es una clase Java pura cuyo único propósito consiste en representar reglas de negocio.

Value Objects

public record Email(String value){

    public Email{

        if(value == null || !value.contains("@")){

            throw new IllegalArgumentException();

        }

    }

}

Al encapsular la validación dentro del propio Value Object evitamos repetir reglas por toda la aplicación y conseguimos un dominio mucho más consistente.

¿Dónde viven los casos de uso?

Los casos de uso pertenecen a la capa de aplicación. Son los encargados de coordinar el dominio utilizando los puertos definidos por éste.

CreateCustomerUseCase

↓

CustomerRepository

↓

Customer Aggregate

↓

CustomerCreatedEvent

Eventos de dominio

En aplicaciones empresariales es muy habitual utilizar Domain Events para comunicar cambios importantes del negocio sin acoplar distintos módulos entre sí.

public record CustomerCreatedEvent(

    UUID customerId,

    Instant createdAt

){}

Más adelante estos eventos podrán publicarse mediante Kafka, RabbitMQ o cualquier otro mecanismo sin modificar el dominio.

Domain-Driven Design no sustituye a la Arquitectura Hexagonal. Ambos patrones se complementan para construir aplicaciones más mantenibles y preparadas para evolucionar.

Beneficios reales de la Arquitectura Hexagonal

La Arquitectura Hexagonal no es una moda ni una forma diferente de organizar carpetas. Su objetivo es reducir el impacto que tienen los cambios tecnológicos sobre el negocio y facilitar la evolución del software durante años.

En aplicaciones empresariales que permanecen activas durante mucho tiempo, el coste de mantenimiento suele superar ampliamente el coste del desarrollo inicial. Una buena arquitectura permite que ese crecimiento sea sostenible.

Mayor mantenibilidad

Separar claramente el dominio de la infraestructura permite localizar rápidamente cualquier cambio. Las reglas de negocio permanecen en un único lugar y no aparecen repartidas entre controladores, repositorios, filtros o configuraciones.

Testing mucho más sencillo

Los casos de uso pueden ejecutarse sin levantar Spring Boot ni conectar una base de datos.

CreateCustomerUseCase useCase =
        new CreateCustomerUseCase(fakeRepository);

Customer customer =
        useCase.execute(command);

assertEquals("Javier", customer.getName());

Esto reduce considerablemente el tiempo de ejecución de las pruebas y permite detectar errores mucho antes.

Independencia tecnológica

Cambiar una tecnología deja de ser una operación traumática. El dominio permanece estable mientras los adaptadores evolucionan.

Preparada para Microservicios

La Arquitectura Hexagonal facilita enormemente la migración desde un monolito hacia microservicios. Los casos de uso ya se encuentran desacoplados de la infraestructura, por lo que resulta mucho más sencillo extraer funcionalidades hacia servicios independientes.

Escalabilidad del equipo

En proyectos grandes participan varios equipos de desarrollo de forma simultánea. Una arquitectura bien definida reduce conflictos, facilita las revisiones de código y acelera la incorporación de nuevos desarrolladores.

Errores más comunes al implementar Arquitectura Hexagonal

Después de participar en proyectos de modernización de aplicaciones Java, uno de los patrones que más se repite es que muchas implementaciones dicen utilizar Arquitectura Hexagonal, pero en realidad únicamente han cambiado la organización de las carpetas.

La verdadera Arquitectura Hexagonal no consiste en mover clases entre paquetes, sino en controlar cuidadosamente la dirección de las dependencias.

// Incorrecto

@Service
public class CreateCustomerUseCase {

    private final JpaCustomerRepository repository;

}

// Correcto

public class CreateCustomerUseCase {

    private final CustomerRepository repository;

}

¿Cuándo utilizar Arquitectura Hexagonal?

La mejor arquitectura no es la más compleja. Es la más sencilla capaz de resolver el problema.

Conclusiones

La Arquitectura Hexagonal no pretende sustituir Spring Boot, Hibernate, JPA o cualquier otra tecnología. Su objetivo consiste en proteger el conocimiento más importante de una organización: las reglas de negocio.

A lo largo de esta guía hemos visto cómo separar el dominio de la infraestructura mediante Puertos y Adaptadores, consiguiendo aplicaciones más fáciles de mantener, probar y evolucionar.

Este cambio de perspectiva permite que tecnologías como bases de datos, brokers de mensajería o frameworks puedan cambiar con el paso del tiempo sin obligar a reescribir la lógica de negocio.

Checklist antes de adoptar Arquitectura Hexagonal

¿Cuándo utilizar Arquitectura Hexagonal?

Próximos pasos

La Arquitectura Hexagonal suele combinarse con otros patrones que permiten construir plataformas empresariales robustas y preparadas para evolucionar.