Arquitectura Hexagonal en Spring Boot 3 con Java 21: Guía Práctica de Ports & Adapters y DDD

March 15, 2026 (8mo ago)

Durante años, la arquitectura en capas tradicional (Controller → Service → Repository) ha sido el estándar predeterminado en proyectos empresariales con Spring Boot. Sin embargo, a medida que la lógica de negocio se complejiza, surgen síntomas conocidos: anotaciones de JPA invadiendo entidades del negocio, servicios inflados con lógica de infraestructura y pruebas unitarias que requieren levantar un contexto completo de Spring (@SpringBootTest), volviendo el ciclo de desarrollo lento y frágil.

En este artículo exploramos cómo implementar la Arquitectura Hexagonal (Puertos y Adaptadores) formulada por Alistair Cockburn, combinada con conceptos tácticos de Domain-Driven Design (DDD), aprovechando las características modernas de Java 21 y Spring Boot 3.

1. El Principio de Inversión de Dependencias (DIP)

El objetivo central de la Arquitectura Hexagonal es colocar el Dominio en el centro. El núcleo del negocio no debe saber si los datos provienen de MySQL, PostgreSQL, una API REST externa o un archivo en memoria, ni tampoco debe depender de anotaciones de @Entity, @Table o @Autowired.

                    ┌─────────────────────────────────────────┐
                    │          ADAPTADORES DE ENTRADA          │
                    │   (REST Controller, CLI, Consumer Kafka)│
                    └────────────────────┬────────────────────┘
                                         │ invoca
                                         ▼
                    ┌─────────────────────────────────────────┐
                    │             PUERTO DE ENTRADA            │
                    │          (Interfaz de Caso de Uso)      │
                    ├─────────────────────────────────────────┤
                    │             NÚCLEO DE DOMINIO            │
                    │       (Entidades, Value Objects, Reglas) │
                    ├─────────────────────────────────────────┤
                    │             PUERTO DE SALIDA             │
                    │         (Interfaz de Repositorio)       │
                    └────────────────────┬────────────────────┘
                                         ▲ implementa
                                         │
                    ┌────────────────────┴────────────────────┐
                    │          ADAPTADORES DE SALIDA          │
                    │     (Spring Data JPA, PayPal, Correo)   │
                    └─────────────────────────────────────────┘

La regla de oro es simple: las dependencias apuntan siempre hacia el interior. El dominio no importa nada de los adaptadores ni del framework.

2. Estructura de Paquetes Modular

En proyectos como SIGOC Web (plataforma de gestión de obras civiles y presupuestos), estructuramos los módulos por contexto delimitado (Bounded Context):

com.ematevar.sigoc.project
├── domain/                  # Lógica pura de negocio (Sin dependencias externas)
│   ├── model/               # Entidades y Value Objects (Java Records)
│   │   ├── Project.java
│   │   ├── ProjectId.java
│   │   └── ProjectStatus.java
│   ├── exception/           # Excepciones de dominio
│   │   └── ProjectBudgetExceededException.java
│   └── port/                # Contratos agnósticos a la tecnología
│       ├── in/              # Casos de uso
│       │   └── CreateProjectUseCase.java
│       └── out/             # Puertos de persistencia y externos
│           └── ProjectRepositoryPort.java
├── application/             # Orquestación de Casos de Uso
│   └── service/
│       └── ProjectApplicationService.java
└── infrastructure/          # Detalles técnicos y adaptadores
    ├── adapter/
    │   ├── in/web/          # Spring MVC Controllers y DTOs
    │   │   ├── ProjectRestController.java
    │   │   └── request/CreateProjectRequest.java
    │   └── out/persistence/ # Implementación JPA + Mapeadores
    │       ├── ProjectJpaEntity.java
    │       ├── SpringDataProjectRepository.java
    │       └── ProjectPersistenceAdapter.java
    └── config/              # Bean configuration de Spring
        └── ProjectBeanConfig.java

3. Implementación Paso a Paso con Java 21

3.1. Entidades de Dominio Inmutables y Value Objects

Aprovechamos los Java Records para crear Value Objects inmutables con validación en el constructor compacto:

package com.ematevar.sigoc.project.domain.model;
 
import java.math.BigDecimal;
import java.util.UUID;
 
public record ProjectId(UUID value) {
    public ProjectId {
        if (value == null) {
            throw new IllegalArgumentException("El ProjectId no puede ser nulo.");
        }
    }
 
    public static ProjectId newUnique() {
        return new ProjectId(UUID.randomUUID());
    }
}

La entidad de dominio encapsula las invariantes de negocio:

package com.ematevar.sigoc.project.domain.model;
 
import com.ematevar.sigoc.project.domain.exception.ProjectBudgetExceededException;
import java.math.BigDecimal;
 
public class Project {
    private final ProjectId id;
    private final String title;
    private BigDecimal allocatedBudget;
    private ProjectStatus status;
 
    public Project(ProjectId id, String title, BigDecimal allocatedBudget) {
        if (title == null || title.isBlank()) {
            throw new IllegalArgumentException("El título del proyecto es obligatorio.");
        }
        if (allocatedBudget == null || allocatedBudget.compareTo(BigDecimal.ZERO) <= 0) {
            throw new IllegalArgumentException("El presupuesto inicial debe ser mayor a cero.");
        }
        this.id = id;
        this.title = title;
        this.allocatedBudget = allocatedBudget;
        this.status = ProjectStatus.DRAFT;
    }
 
    // Regla de negocio pura
    public void executeExpense(BigDecimal amount) {
        if (amount.compareTo(this.allocatedBudget) > 0) {
            throw new ProjectBudgetExceededException(
                "El gasto (" + amount + ") supera el presupuesto disponible (" + this.allocatedBudget + ")"
            );
        }
        this.allocatedBudget = this.allocatedBudget.subtract(amount);
    }
 
    public ProjectId getId() { return id; }
    public String getTitle() { return title; }
    public BigDecimal getAllocatedBudget() { return allocatedBudget; }
    public ProjectStatus getStatus() { return status; }
}

3.2. Definición de Puertos de Entrada y Salida

El Puerto de Entrada define la interfaz del caso de uso:

package com.ematevar.sigoc.project.domain.port.in;
 
import com.ematevar.sigoc.project.domain.model.ProjectId;
import java.math.BigDecimal;
 
public interface CreateProjectUseCase {
    record Command(String title, BigDecimal initialBudget) {}
 
    ProjectId execute(Command command);
}

El Puerto de Salida define el contrato para almacenar o consultar la entidad:

package com.ematevar.sigoc.project.domain.port.out;
 
import com.ematevar.sigoc.project.domain.model.Project;
import com.ematevar.sigoc.project.domain.model.ProjectId;
import java.util.Optional;
 
public interface ProjectRepositoryPort {
    void save(Project project);
    Optional<Project> findById(ProjectId id);
}

3.3. Servicio de Aplicación (Orquestador Puro)

El servicio de aplicación coordina la interacción entre el dominio y los puertos, sin saber nada sobre HTTP o bases de datos específicas:

package com.ematevar.sigoc.project.application.service;
 
import com.ematevar.sigoc.project.domain.model.Project;
import com.ematevar.sigoc.project.domain.model.ProjectId;
import com.ematevar.sigoc.project.domain.port.in.CreateProjectUseCase;
import com.ematevar.sigoc.project.domain.port.out.ProjectRepositoryPort;
 
public class ProjectApplicationService implements CreateProjectUseCase {
 
    private final ProjectRepositoryPort repositoryPort;
 
    public ProjectApplicationService(ProjectRepositoryPort repositoryPort) {
        this.repositoryPort = repositoryPort;
    }
 
    @Override
    public ProjectId execute(Command command) {
        ProjectId newId = ProjectId.newUnique();
        Project project = new Project(newId, command.title(), command.initialBudget());
        
        repositoryPort.save(project);
        return newId;
    }
}

3.4. Adaptador de Salida: Persistencia con Spring Data JPA

En la capa de infraestructura, implementamos el adaptador concreto y mapeamos entre el modelo de base de datos (ProjectJpaEntity) y la entidad de dominio (Project):

package com.ematevar.sigoc.project.infrastructure.adapter.out.persistence;
 
import com.ematevar.sigoc.project.domain.model.Project;
import com.ematevar.sigoc.project.domain.model.ProjectId;
import com.ematevar.sigoc.project.domain.port.out.ProjectRepositoryPort;
import org.springframework.stereotype.Component;
 
import java.util.Optional;
 
@Component
public class ProjectPersistenceAdapter implements ProjectRepositoryPort {
 
    private final SpringDataProjectRepository jpaRepository;
 
    public ProjectPersistenceAdapter(SpringDataProjectRepository jpaRepository) {
        this.jpaRepository = jpaRepository;
    }
 
    @Override
    public void save(Project project) {
        ProjectJpaEntity entity = ProjectJpaEntity.fromDomain(project);
        jpaRepository.save(entity);
    }
 
    @Override
    public Optional<Project> findById(ProjectId id) {
        return jpaRepository.findById(id.value().toString())
            .map(ProjectJpaEntity::toDomain);
    }
}

3.5. Configuración de Inyección en Spring Boot

Para mantener el servicio de aplicación desacoplado de @Service de Spring, lo instanciamos en una clase de configuración:

package com.ematevar.sigoc.project.infrastructure.config;
 
import com.ematevar.sigoc.project.application.service.ProjectApplicationService;
import com.ematevar.sigoc.project.domain.port.in.CreateProjectUseCase;
import com.ematevar.sigoc.project.domain.port.out.ProjectRepositoryPort;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
 
@Configuration
public class ProjectBeanConfig {
 
    @Bean
    public CreateProjectUseCase createProjectUseCase(ProjectRepositoryPort repositoryPort) {
        return new ProjectApplicationService(repositoryPort);
    }
}

4. Pruebas Unitarias Ultra-Rápidas

Una de las mayores victorias de la Arquitectura Hexagonal es la velocidad de testing. Para probar la lógica de dominio y los casos de uso, no necesitas cargar ningún contexto de Spring ni levantar un contenedor de Docker:

class ProjectTest {
 
    @Test
    void shouldThrowExceptionWhenExpenseExceedsAllocatedBudget() {
        Project project = new Project(ProjectId.newUnique(), "Construcción Puente", new BigDecimal("10000.00"));
 
        assertThrows(ProjectBudgetExceededException.class, () -> {
            project.executeExpense(new BigDecimal("15000.00"));
        });
    }
}

Esta prueba se ejecuta en menos de 5 milisegundos. Puedes ejecutar cientos de casos de prueba de dominio en una fracción de segundo en tu pipeline de CI/CD.

5. Cuándo Usar y Cuándo Evitar

EscenarioRecomendación
Sistemas Core / Misión Crítica (Gestión de Obras, Facturación, POS)Indispensable: Protege el negocio frente a cambios tecnológicos.
Aplicaciones con Múltiples Adaptadores (REST, CLI, Jobs, Webhooks)Ideal: Reutilizas el mismo caso de uso sin duplicar lógica.
CRUDs Simples y Prototipos RápidosEvitar o simplificar: El overhead de mapeo de DTOs/Entidades puede ser excesivo.

Conclusión

La Arquitectura Hexagonal no es una moda pasajera; es una inversión de ingeniería en sistemas que perduran. En proyectos como SIGOC Web, aplicar esta separación nos permitió integrar la pasarela de PayPal Sandbox y la exportación de reportes de Curva S sin tocar una sola línea de las reglas del negocio de obras civiles.

Si estás construyendo software empresarial en Perú o a nivel global con Java 21 y Spring Boot 3, adoptar este enfoque garantiza que tu aplicación sea testeable, modular y esté lista para evolucionar ante cualquier cambio de infraestructura.