Artículo

Arquitectura hexagonal en Java y Spring Boot: puertos y adaptadores

Qué es la arquitectura hexagonal (puertos y adaptadores), cómo organizar un proyecto Java y Spring Boot con ella y cuándo compensa, con ejemplo.

En resumen: la arquitectura hexagonal (o puertos y adaptadores) pone la lógica de negocio en el centro, sin depender de frameworks ni bases de datos. El centro define puertos (interfaces): de entrada, lo que la aplicación ofrece; de salida, lo que necesita. Fuera viven los adaptadores: un controlador REST, un repositorio JPA, un cliente HTTP. Las dependencias siempre apuntan hacia dentro. Ejemplo probado con Java 25, compatible desde Java 17.

Vídeo explicativo

El problema que resuelve

En la arquitectura por capas clásica, el servicio depende del repositorio JPA, y el repositorio de la base de datos. La lógica de negocio acaba mezclada con anotaciones de JPA, excepciones de Spring y DTOs de la API. Cambiar la base de datos o probar una regla sin arrancar Spring se vuelve caro.

Alistair Cockburn propuso invertirlo: el núcleo define qué necesita mediante interfaces y el mundo exterior se adapta a él.

             Adaptadores de entrada                 Adaptadores de salida
         (REST, consola, colas, tests)          (JPA, HTTP, email, ficheros)
                     │                                      ▲
                     ▼                                      │
          ┌─────────────────────────────────────────────────┴─┐
          │  Puerto de entrada          Puerto de salida      │
          │  (TransferirDineroUseCase)  (CuentaRepository)     │
          │          │                        ▲               │
          │          ▼                        │               │
          │      Servicio de aplicación ──────┘               │
          │                 │                                 │
          │                 ▼                                 │
          │           Dominio (Cuenta)                        │
          └───────────────────────────────────────────────────┘
                 Las dependencias apuntan hacia dentro

Ejemplo completo sin frameworks

El núcleo no importa nada de Spring. Eso es lo que permite ejecutarlo así, en un solo archivo:

import java.util.HashMap;
import java.util.Map;
import java.util.Optional;

// ---------- Dominio: sin dependencias de frameworks ----------
record Cuenta(String id, long saldoCentimos) {
    Cuenta retirar(long cantidad) {
        if (cantidad <= 0) {
            throw new IllegalArgumentException("Cantidad no válida");
        }
        if (cantidad > saldoCentimos) {
            throw new IllegalStateException("Saldo insuficiente");
        }
        return new Cuenta(id, saldoCentimos - cantidad);
    }

    Cuenta ingresar(long cantidad) {
        return new Cuenta(id, saldoCentimos + cantidad);
    }
}

// ---------- Puerto de entrada: lo que la aplicación ofrece ----------
interface TransferirDineroUseCase {
    void transferir(String origen, String destino, long cantidad);
}

// ---------- Puerto de salida: lo que la aplicación necesita ----------
interface CuentaRepository {
    Optional<Cuenta> buscar(String id);
    void guardar(Cuenta cuenta);
}

// ---------- Aplicación: orquesta el dominio a través de los puertos ----------
class TransferirDineroService implements TransferirDineroUseCase {
    private final CuentaRepository cuentas;

    TransferirDineroService(CuentaRepository cuentas) {
        this.cuentas = cuentas;
    }

    @Override
    public void transferir(String origen, String destino, long cantidad) {
        Cuenta desde = cuentas.buscar(origen).orElseThrow(() -> new IllegalArgumentException("No existe " + origen));
        Cuenta hacia = cuentas.buscar(destino).orElseThrow(() -> new IllegalArgumentException("No existe " + destino));
        cuentas.guardar(desde.retirar(cantidad));
        cuentas.guardar(hacia.ingresar(cantidad));
    }
}

// ---------- Adaptador de salida: una implementación concreta del puerto ----------
class CuentaRepositoryEnMemoria implements CuentaRepository {
    private final Map<String, Cuenta> datos = new HashMap<>();

    @Override
    public Optional<Cuenta> buscar(String id) {
        return Optional.ofNullable(datos.get(id));
    }

    @Override
    public void guardar(Cuenta cuenta) {
        datos.put(cuenta.id(), cuenta);
    }
}

// ---------- Adaptador de entrada: traduce una petición externa al caso de uso ----------
class TransferenciaConsoleAdapter {
    private final TransferirDineroUseCase useCase;

    TransferenciaConsoleAdapter(TransferirDineroUseCase useCase) {
        this.useCase = useCase;
    }

    void ejecutar(String linea) {
        String[] p = linea.split(" ");
        try {
            useCase.transferir(p[0], p[1], Long.parseLong(p[2]));
            System.out.println("OK: " + linea);
        } catch (RuntimeException e) {
            System.out.println("Rechazada (" + linea + "): " + e.getMessage());
        }
    }
}

public class Main {
    public static void main(String[] args) {
        CuentaRepositoryEnMemoria repo = new CuentaRepositoryEnMemoria();
        repo.guardar(new Cuenta("ana", 10_000));
        repo.guardar(new Cuenta("luis", 500));

        TransferenciaConsoleAdapter consola =
                new TransferenciaConsoleAdapter(new TransferirDineroService(repo));
        consola.ejecutar("ana luis 2500");
        consola.ejecutar("luis ana 99999");
        consola.ejecutar("ana pepe 100");

        System.out.println(repo.buscar("ana").orElseThrow());
        System.out.println(repo.buscar("luis").orElseThrow());
    }
}

Salida:

OK: ana luis 2500
Rechazada (luis ana 99999): Saldo insuficiente
Rechazada (ana pepe 100): No existe pepe
Cuenta[id=ana, saldoCentimos=7500]
Cuenta[id=luis, saldoCentimos=3000]

Lo mismo con Spring Boot

En un proyecto real cambian solo los adaptadores: el de entrada es un @RestController que llama a TransferirDineroUseCase, y el de salida un @Component que implementa CuentaRepository usando un repositorio de Spring Data JPA y convierte entre la entidad JPA y el record Cuenta del dominio. El dominio y el servicio no se tocan. Una estructura de paquetes habitual:

com.empresa.cuentas
├── domain/                     Cuenta (record), reglas de negocio
├── application/
│   ├── port/in/                TransferirDineroUseCase
│   ├── port/out/               CuentaRepository
│   └── service/                TransferirDineroService
├── adapter/
│   ├── in/web/                 CuentaController, DTOs de la API
│   └── out/persistence/        CuentaJpaEntity, CuentaPersistenceAdapter
└── config/                     @Configuration que crea el servicio como @Bean

Si el servicio se registra con un @Bean en config/, ni siquiera necesita @Service: la capa de aplicación queda libre de Spring. Para que nadie rompa las reglas (por ejemplo, que el dominio importe JPA), se comprueban con tests de ArchUnit.

Ventajas e inconvenientes

A favorEn contra
Reglas de negocio probables sin Spring ni base de datosMás interfaces, clases y mapeos
Cambiar de base de datos o de API no toca el núcleoCurva de aprendizaje para el equipo
El código refleja los casos de uso del negocioExcesiva para un CRUD sin reglas
Encaja con DDD y con microserviciosRequiere disciplina para no saltarse los puertos

Cuándo merece la pena: cuando hay lógica de negocio real que proteger y el proyecto vivirá años. Para un CRUD que solo guarda y lee formularios, la arquitectura por capas es suficiente.

Preguntas frecuentes

¿Hexagonal, Clean Architecture y Onion son lo mismo?

Comparten la idea central (el dominio no depende de la infraestructura y las dependencias apuntan hacia dentro). Cambian la nomenclatura y el número de capas.

¿Las entidades JPA son el dominio?

En una hexagonal estricta no: la entidad JPA vive en el adaptador de persistencia y se convierte al modelo de dominio. Es más código, pero el dominio no depende de JPA. Algunos equipos aceptan anotar el dominio con JPA como compromiso.

¿Cómo se relaciona con SOLID?

Es la aplicación a escala de arquitectura del principio de inversión de dependencias de SOLID: los módulos de alto nivel no dependen de los de bajo nivel, ambos dependen de abstracciones.

¿Encaja con microservicios?

Muy bien: cada microservicio puede ser un hexágono, y las llamadas a otros servicios son adaptadores de salida.

Sigue aprendiendo

La arquitectura hexagonal, DDD táctico y las reglas de ArchUnit son un bloque completo del máster de arquitecto Java y Spring Boot con IA, donde se aplican sobre un proyecto real. Para la base, repasa inversión de control en Spring y el patrón DTO.

arquitectura hexagonal puertos y adaptadores clean architecture java spring boot arquitectura de software

Newsletter Semanal de Java

Cada viernes recibe lo más nuevo del ecosistema Java: frameworks, herramientas y mejores prácticas.

Sin spam. Cancela cuando quieras.

Compartir artículo