Spring REST

El desarrollo de APIs REST representa uno de los pilares fundamentales de las aplicaciones web modernas. Spring Boot proporciona un conjunto de herramientas que simplifican enormemente la creación de servicios web RESTful, permitiendo a los desarrolladores centrarse en la lógica de negocio en lugar de la configuración compleja.

REST (Representational State Transfer) es un estilo arquitectónico que define cómo los sistemas distribuidos pueden comunicarse a través de HTTP. En el contexto de Spring Boot, esto se traduce en la capacidad de crear endpoints que respondan a peticiones HTTP y devuelvan datos en formato JSON de manera eficiente y escalable.

Fundamentos de REST en Spring Boot

Spring Boot integra Spring MVC de forma automática, proporcionando todas las funcionalidades necesarias para crear controladores REST sin configuración adicional. El framework maneja automáticamente la serialización y deserialización de objetos Java a JSON, la gestión de códigos de estado HTTP y el enrutamiento de peticiones.

Los controladores REST en Spring Boot se definen mediante anotaciones que indican al framework cómo debe procesar las peticiones entrantes. Estas anotaciones permiten mapear URLs específicas a métodos Java, definir qué tipos de peticiones HTTP acepta cada endpoint y especificar el formato de los datos de respuesta.

@RestController
@RequestMapping("/api/usuarios")
public class UsuarioController {
    
    @GetMapping
    public List<Usuario> obtenerUsuarios() {
        return Arrays.asList(
            new Usuario("Juan", "juan@email.com"),
            new Usuario("María", "maria@email.com")
        );
    }
}

Anotaciones principales para REST

La anotación @RestController combina @Controller y @ResponseBody, indicando que todos los métodos del controlador devuelven datos directamente en el cuerpo de la respuesta HTTP, típicamente en formato JSON. Esta anotación elimina la necesidad de anotar cada método individualmente.

@RequestMapping define la ruta base para todos los endpoints del controlador. Esta anotación puede especificar tanto la URL como el método HTTP, aunque es más común usar las anotaciones específicas para cada verbo HTTP.

@RestController
@RequestMapping("/api/productos")
public class ProductoController {
    
    @GetMapping("/{id}")
    public Producto obtenerProducto(@PathVariable Long id) {
        return new Producto(id, "Laptop", 999.99);
    }
    
    @PostMapping
    public Producto crearProducto(@RequestBody Producto producto) {
        // Lógica para guardar el producto
        return producto;
    }
}

Spring Data JPA

Spring Data JPA representa una de las herramientas más utilizadas en el ecosistema Spring Boot para simplificar el acceso a datos relacionales. Esta tecnología elimina gran parte del código repetitivo que tradicionalmente requiere la persistencia de datos, permitiendo a los desarrolladores centrarse en la lógica de negocio en lugar de en los detalles técnicos de acceso a la base de datos.

¿Qué es Spring Data JPA?

Spring Data JPA es una abstracción que se construye sobre JPA (Java Persistence API), el estándar de Java para el mapeo objeto-relacional. Mientras que JPA define las especificaciones, Spring Data JPA proporciona una implementación que reduce significativamente la cantidad de código necesario para realizar operaciones básicas de CRUD (Create, Read, Update, Delete).

La principal ventaja de esta tecnología radica en su capacidad para generar automáticamente implementaciones de repositorios basándose únicamente en interfaces. Esto significa que puedes definir métodos de acceso a datos sin escribir su implementación, ya que Spring Data JPA se encarga de generarla automáticamente.

Configuración básica en Spring Boot

Spring Boot facilita enormemente la configuración de Spring Data JPA. Con las dependencias correctas en el archivo pom.xml, la configuración se realiza de forma automática:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>runtime</scope>
</dependency>

La configuración básica en application.properties es mínima:

spring.datasource.url=jdbc:h2:mem:testdb
spring.jpa.hibernate.ddl-auto=create-drop
spring.jpa.show-sql=true

Esta configuración utiliza H2, una base de datos en memoria perfecta para desarrollo y pruebas, aunque en producción utilizarías bases de datos como PostgreSQL o MySQL.

Spring MVC representa el patrón arquitectónico Modelo-Vista-Controlador implementado dentro del ecosistema Spring Boot. Este enfoque separa claramente las responsabilidades de una aplicación web: el modelo gestiona los datos, la vista presenta la información al usuario, y el controlador coordina las interacciones entre ambos componentes.

La integración con Thymeleaf como motor de plantillas proporciona una solución completa para desarrollar aplicaciones web dinámicas. Thymeleaf permite crear páginas HTML que pueden procesarse tanto en el servidor como visualizarse directamente en el navegador durante el desarrollo, facilitando significativamente el proceso de creación de interfaces web.

Arquitectura MVC en Spring Boot

El patrón MVC organiza el código en tres capas bien diferenciadas. Los controladores reciben las peticiones HTTP y determinan qué lógica de negocio ejecutar. El modelo encapsula los datos y la lógica de la aplicación. Las vistas generan la respuesta HTML que se envía al navegador del usuario.

Spring Boot simplifica esta arquitectura mediante anotaciones que automatizan gran parte de la configuración. Un controlador básico se define utilizando la anotación @Controller:

@Controller
public class HomeController {
    
    @GetMapping("/")
    public String home(Model model) {
        model.addAttribute("mensaje", "Bienvenido a Spring MVC");
        return "index";
    }
}

El método home() maneja las peticiones GET a la ruta raíz. El parámetro Model permite pasar datos a la vista, mientras que el valor de retorno específica qué plantilla Thymeleaf debe renderizarse.

Configuración de Thymeleaf

Thymeleaf se integra automáticamente en Spring Boot sin necesidad de configuración adicional. Las plantillas se ubican por defecto en el directorio src/main/resources/templates/ y utilizan la extensión .html.

La configuración básica en application.properties permite personalizar el comportamiento:

spring.thymeleaf.cache=false
spring.thymeleaf.prefix=classpath:/templates/
spring.thymeleaf.suffix=.html

La propiedad cache=false resulta especialmente útil durante el desarrollo, ya que permite ver los cambios en las plantillas sin reiniciar la aplicación.

Sintaxis básica de Thymeleaf

Las expresiones Thymeleaf se integran directamente en el HTML utilizando atributos especiales. La sintaxis th:text reemplaza el contenido de un elemento:

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <title>Mi Aplicación</title>
</head>
<body>
    <h1 th:text="${mensaje}">Texto por defecto</h1>
    <p th:text="${descripcion}">Descripción por defecto</p>
</body>
</html>

El namespace xmlns:th habilita las funcionalidades de Thymeleaf en el documento HTML. Las expresiones ${variable} acceden a los datos pasados desde el controlador.

Testing con Spring Test

El testing es una práctica fundamental en el desarrollo de aplicaciones Spring Boot que garantiza la calidad y confiabilidad del código. Spring Framework proporciona un conjunto completo de herramientas de testing a través de Spring Test, que se integra perfectamente con el ecosistema de Spring Boot para facilitar la creación de pruebas efectivas.

Fundamentos del testing en Spring Boot

Spring Boot incluye por defecto el starter de testing que proporciona todas las dependencias necesarias para escribir pruebas. Este starter incluye JUnit 6, Mockito, AssertJ y las utilidades específicas de Spring Test, creando un entorno completo para diferentes tipos de pruebas.

La arquitectura de testing en Spring Boot se basa en el concepto de contexto de aplicación. Spring Test puede cargar un contexto completo o parcial de la aplicación, permitiendo probar componentes de forma aislada o en conjunto según las necesidades específicas de cada prueba.

@SpringBootTest
class ApplicationTests {
    
    @Test
    void contextLoads() {
        // Esta prueba verifica que el contexto de Spring se carga correctamente
    }
}

Tipos de pruebas en Spring Boot

Spring Boot facilita la implementación de diferentes niveles de testing mediante anotaciones especializadas. Cada tipo de prueba está diseñado para verificar aspectos específicos de la aplicación con el nivel de integración apropiado.

Pruebas unitarias

Las pruebas unitarias se centran en probar componentes individuales de forma aislada. Spring Test proporciona utilidades para crear mocks y configurar el contexto mínimo necesario.

@ExtendWith(MockitoExtension.class)
class UserServiceTest {
    
    @Mock
    private UserRepository userRepository;
    
    @InjectMocks
    private UserService userService;
    
    @Test
    void shouldCreateUser() {
        // Arrange
        User user = new User("Juan", "juan@email.com");
        when(userRepository.save(any(User.class))).thenReturn(user);
        
        // Act
        User result = userService.createUser("Juan", "juan@email.com");
        
        // Assert
        assertThat(result.getName()).isEqualTo("Juan");
        assertThat(result.getEmail()).isEqualTo("juan@email.com");
    }
}

Pruebas de integración

Las pruebas de integración verifican la interacción entre múltiples componentes. Spring Boot proporciona anotaciones específicas para cargar partes del contexto de aplicación según el tipo de integración que se desea probar.

@DataJpaTest
class UserRepositoryTest {
    
    @Autowired
    private TestEntityManager entityManager;
    
    @Autowired
    private UserRepository userRepository;
    
    @Test
    void shouldFindUserByEmail() {
        // Arrange
        User user = new User("Ana", "ana@email.com");
        entityManager.persistAndFlush(user);
        
        // Act
        Optional<User> found = userRepository.findByEmail("ana@email.com");
        
        // Assert
        assertThat(found).isPresent();
        assertThat(found.get().getName()).isEqualTo("Ana");
    }
}

Spring Boot 3, en combinación con Spring Security, proporciona un sólido marco para implementar seguridad en aplicaciones Java. Este módulo cubre cómo configurar y utilizar Spring Security en una aplicación Spring Boot 3 para asegurar endpoints, gestionar autenticación y autorización, y mucho más.

Configuración inicial

Para empezar, es necesario agregar las dependencias de Spring Security en tu archivo build.gradle o pom.xml. Aquí tienes un ejemplo utilizando Gradle:

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-security'
}

Gestión de usuarios

Para gestionar usuarios, puedes definir un UserDetailsService personalizado. A continuación, un ejemplo de cómo hacerlo:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.provisioning.InMemoryUserDetailsManager;

@Configuration
public class UserConfig {

    @Bean
    public UserDetailsService userDetailsService() {
        InMemoryUserDetailsManager manager = new InMemoryUserDetailsManager();
        manager.createUser(User.withUsername("user")
                .password(passwordEncoder().encode("password"))
                .roles("USER")
                .build());
        manager.createUser(User.withUsername("admin")
                .password(passwordEncoder().encode("admin"))
                .roles("ADMIN")
                .build());
        return manager;
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }
}

Protección de endpoints REST

Para asegurar endpoints REST, se puede utilizar la misma configuración de seguridad. Aquí un ejemplo de cómo proteger un controlador REST:

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
public class ApiController {

    @GetMapping("/public")
    public String publicEndpoint() {
        return "This is a public endpoint";
    }

    @GetMapping("/private")
    public String privateEndpoint() {
        return "This is a private endpoint";
    }
}

En la configuración de seguridad, se asegura que solo los usuarios autenticados puedan acceder al endpoint privado.

La integración de Spring Boot 3 con el frontend es una tarea esencial para desarrollar aplicaciones web completas. En este artículo, exploraremos cómo combinar Spring Boot 3 con tecnologías frontend modernas para crear aplicaciones eficientes y mantenibles.

Configuración inicial de Spring Boot 3

Para comenzar, necesitamos configurar un proyecto de Spring Boot 3. Asegúrate de tener instalado Spring Boot 3 y JDK 17 o superior. Puedes crear un nuevo proyecto utilizando Spring Initializr:

curl https://start.spring.io/starter.zip \
  -d dependencies=web \
  -d javaVersion=17 \
  -d bootVersion=3.0.0 \
  -d groupId=com.ejemplo \
  -d artifactId=integracion-spring-frontend \
  -d name=IntegracionSpringFrontend \
  -o integracion-spring-frontend.zip
unzip integracion-spring-frontend.zip -d integracion-spring-frontend
cd integracion-spring-frontend

Creación de un controlador REST

Una vez configurado el proyecto, crearemos un controlador REST para manejar las peticiones HTTP desde el frontend:

package com.ejemplo.integracionspringfrontend.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HolaMundoController {

    @GetMapping("/api/hola")
    public String holaMundo() {
        return "Hola, mundo!";
    }
}

Configuración de CORS

Para permitir que el frontend se comunique con el backend, es necesario configurar CORS (Cross-Origin Resource Sharing):

package com.ejemplo.integracionspringfrontend.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig {

    @Bean
    public WebMvcConfigurer corsConfigurer() {
        return new WebMvcConfigurer() {
            @Override
            public void addCorsMappings(CorsRegistry registry) {
                registry.addMapping("/api/**")
                        .allowedOrigins("http://localhost:3000")
                        .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS");
            }
        };
    }
}

Si necesitas manejar grandes flujos de datos, Apache Kafka es idóneo por su alta capacidad de procesamiento y su escalabilidad nativa. Con Spring Boot, la configuración se simplifica gracias a las dependencias que facilitan el acceso a los brokers y la creación de consumidores y productores de datos.

Requisitos previos

1. Tener Java (versión 17 o superior) instalado.
2. Contar con una instalación local de Apache Kafka funcionando.
3. Disponer de Maven o Gradle para gestionar dependencias.
4. Conocer las anotaciones básicas de Spring Boot y su ciclo de vida.

Es fundamental verificar que Kafka esté en ejecución antes de empezar a integrar las funcionalidades de Spring Boot.

Configuración de dependencias

Para añadir las librerías de Spring for Apache Kafka, utiliza la siguiente dependencia en el archivo pom.xml de Maven:

<dependency>
    <groupId>org.springframework.kafka</groupId>
    <artifactId>spring-kafka</artifactId>
</dependency>

En Gradle, se añade en build.gradle:

implementation 'org.springframework.kafka:spring-kafka'

Ambas dependencias habilitan la integración con Kafka y proporcionan clases para la creación de productores y consumidores.

Configuración básica

Para indicar a Spring Boot dónde se encuentra el broker, define las siguientes propiedades en application.properties o application.yml:

spring.kafka.bootstrap-servers=localhost:9092
spring.kafka.consumer.group-id=grupo-mensajeria
spring.kafka.consumer.auto-offset-reset=earliest
spring.kafka.template.default-topic=mensajes-topic

Estas directivas guían a Spring Boot para conectar con el broker de Kafka, establecer un grupo de consumidores y configurar un tópico por defecto.

Creando un productor

El productor envía mensajes a un tópico de Kafka de manera asíncrona. Un ejemplo sencillo utilizando KafkaTemplate:

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.kafka.core.KafkaTemplate;
import org.springframework.stereotype.Service;

@Service
public class MensajeriaProducer {

    @Autowired
    private KafkaTemplate<String, String> kafkaTemplate;

    public void enviarMensaje(String mensaje) {
        kafkaTemplate.send("mensajes-topic", mensaje);
        System.out.println("Mensaje enviado: " + mensaje);
    }
}

Este componente de Spring Boot facilita la interacción con Kafka mediante operaciones simples que permiten despachar mensajes hacia el tópico configurado.

Creando un consumidor

Para recibir mensajes, basta con anotar un método con @KafkaListener. Spring Boot creará el hilo de escucha y notificará al método cada vez que llegue un mensaje:

import org.springframework.kafka.annotation.KafkaListener;
import org.springframework.stereotype.Service;

@Service
public class MensajeriaConsumer {

    @KafkaListener(topics = "mensajes-topic", groupId = "grupo-mensajeria")
    public void escucharMensajes(String mensaje) {
        System.out.println("Mensaje recibido: " + mensaje);
        // Lógica de procesamiento
    }
}

De este modo, el grupo de consumidores en Kafka balancea la carga y gestiona la recepción de eventos.

Serialización y deserialización

Para manejar datos en formatos distintos a cadenas, es posible configurar la serialización y la deserialización en las propiedades de Spring Boot:

spring.kafka.producer.key-serializer=org.apache.kafka.common.serialization.StringSerializer
spring.kafka.producer.value-serializer=org.springframework.kafka.support.serializer.JsonSerializer
spring.kafka.consumer.key-deserializer=org.apache.kafka.common.serialization.StringDeserializer
spring.kafka.consumer.value-deserializer=org.springframework.kafka.support.serializer.JsonDeserializer
spring.kafka.consumer.properties.spring.json.trusted.packages=*

Con JsonSerializer y JsonDeserializer, se agiliza el envío y recepción de objetos en formato JSON sin necesidad de realizar conversiones manuales.

Manejo de errores y reintentos

Es fundamental configurar reintentos y tiempo de espera si un mensaje genera errores. En Spring Boot, se pueden definir ajustes como:

spring.kafka.listener.ack-mode=record
spring.kafka.listener.retry-attempts=3
spring.kafka.listener.backoff-interval=5000

En caso de fallar un proceso, estos ajustes controlan cuántas veces se intentará reconsumir el mensaje y el tiempo de espera entre reintentos, lo que mejora la fiabilidad de la mensajería.

Ventajas de integrar Kafka con Spring Boot

• Configuración intuitiva gracias a las propiedades de Spring Boot.
• Facilidad para estructurar aplicaciones de microservicios con comunicación asíncrona.
• Aumento de la escalabilidad al permitir múltiples productores y consumidores en paralelo.
• Posibilidad de supervisión y métricas integradas mediante herramientas del ecosistema Spring.

Mejores prácticas

• Definir tópicos con nombres claros y coherentes.
• Ajustar el número de particiones para maximizar la eficiencia en entornos distribuidos.
• Mantener un monitorización constante con Micrometer y otras soluciones de observabilidad.
• Implementar mecanismos de seguridad como SSL/SASL en entornos empresariales.
• Revisar la gestión de offsets para evitar pérdidas o duplicados de datos.

Casos de uso destacados

• Sistemas de e-commerce que requieran sincronizar inventarios en tiempo real.
• Aplicaciones IoT donde miles de dispositivos se comunican continuamente.
• Redes de microservicios que intercambian datos con baja latencia.
• Procesamiento de eventos en flujos de datos para analítica y toma de decisiones inmediatas.

Con estos pasos, la integración entre Spring Boot y Apache Kafka puede llevarse a cabo de manera eficiente, permitiendo desarrollar sistemas distribuidos de mensajería capaces de crecer y adaptarse a demandas cambiantes.

La programación reactiva aporta un modelo asíncrono y no bloqueante que mejora la capacidad de procesamiento de datos en aplicaciones que requieren alta concurrencia. Con Spring Boot, es posible habilitar WebFlux y aprovechar la librería Reactor para crear flujos de datos que se adaptan a demandas cambiantes.

Qué es WebFlux en Spring Boot

Spring WebFlux es una alternativa a Spring MVC, enfocada en operaciones no bloqueantes y en un uso eficiente de los recursos. Cuando se requiere procesar múltiples solicitudes simultáneas, este enfoque reduce la sobrecarga y la latencia, lo que marca la diferencia en aplicaciones de programación reactiva.

Requisitos previos

1. Conocer Java y su ecosistema.
2. Tener Spring Boot instalado o configurado en el proyecto.
3. Contar con experiencia en Maven o Gradle para gestionar dependencias.
4. Disponer de conocimientos básicos sobre threads y programación concurrente.

Cada uno de estos requisitos facilita la comprensión de WebFlux y su funcionamiento interno, especialmente en lo referente al manejo de flujos asíncronos.

Configuración de dependencias

Para habilitar WebFlux, es necesario incluir la dependencia en el archivo pom.xml si se trabaja con Maven:

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

En Gradle, se añaden las líneas correspondientes en build.gradle:

implementation 'org.springframework.boot:spring-boot-starter-webflux'

De esta forma, Spring Boot configura automáticamente el stack reactivo y pone a disposición las clases y anotaciones de WebFlux.

Fundamentos de la programación reactiva

La programación reactiva gira en torno a la idea de suscribirse a flujos de datos que se van emitiendo con el tiempo. Los conceptos clave son Publisher, Subscriber, Subscription y Processor, tal como se define en la especificación Reactive Streams. En Spring Boot, se aprovecha el proyecto Reactor, que proporciona tipos como Flux y Mono para representar secuencias de datos.

Ejemplo de controlador reactivo

En WebFlux, un controlador se implementa con anotaciones similares a las de Spring MVC, pero retornando tipos reactivos como Mono y Flux. Un ejemplo sencillo sería:

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Flux;

@RestController
public class ProductoController {

    @GetMapping("/productos")
    public Flux<String> listarProductos() {
        return Flux.just("Producto A", "Producto B", "Producto C");
    }
}

Este controlador devuelve un Flux de cadenas, permitiendo a la aplicación entregar datos a medida que estén disponibles, sin necesidad de bloquear el hilo principal.

Manejo de datos con Mono y Flux

Un Mono representa una secuencia reactiva que emitirá un único elemento o un vacío. Un Flux, por su parte, emitirá cero o múltiples elementos. Estas estructuras permiten gestionar la programación reactiva a partir de un set de operadores que transforman, combinan o filtran los datos según sea necesario.

Características de WebFlux

• Enfoque asíncrono que evita bloqueos en el hilo principal.
• Uso de Netty o servidores reactivos similares que facilitan el manejo de peticiones.
• Integración con anotaciones de Spring Boot para simplificar la configuración.
• Posibilidad de extender la aplicación con librerías reactivas externas.

Estas particularidades convierten a WebFlux en una opción interesante para servicios que necesitan una latencia reducida.

Configuración adicional en application.properties

Cuando se trabaja con WebFlux y se necesita ajustar propiedades, es posible usar application.properties para definir parámetros en tiempo de ejecución:

spring.main.web-application-type=reactive
server.port=8080

Al indicar reactive como tipo de aplicación web, Spring Boot habilita el stack no bloqueante por defecto, sin necesidad de un contenedor de servlets tradicional.

Integración con bases de datos reactivas

Para un enfoque completamente reactivo, es recomendable utilizar bases de datos que cuenten con drivers no bloqueantes. PostgreSQL, MongoDB y otros sistemas proporcionan controladores que se integran con Reactor, lo que garantiza que la aplicación mantenga la coherencia de la programación reactiva.

Buenas prácticas

• Utilizar operadores de Reactor con moderación y claridad.
• Evitar transformaciones innecesarias en cadenas reactivas.
• Manejar correctamente los errores y las señales de cancelación en flujos.
• Monitorear el rendimiento con herramientas enfocadas en programación reactiva.
• Revisar la documentación oficial de Spring Boot y WebFlux para profundizar en configuraciones avanzadas.

Casos de uso destacados

• Servicios que necesitan responder a miles de peticiones simultáneas, como en entornos IoT.
• Aplicaciones de notificaciones en tiempo real con WebFlux, donde se emiten eventos constantes.
• Microservicios que se comunican por flujos de datos para coordinar operaciones complejas.
• Sistemas de análisis en streaming con una gran demanda de programación reactiva.

Observabilidad en Spring Boot

La observabilidad se ha convertido en un pilar fundamental para el desarrollo de aplicaciones empresariales modernas. En el ecosistema de Spring Boot, dominar las técnicas de observabilidad significa tener visibilidad completa sobre el comportamiento, rendimiento y salud de tus aplicaciones en producción.

Este módulo te enseña a implementar una estrategia integral de observabilidad que incluye métricas, logs estructurados y trazas distribuidas. Aprenderás a utilizar las herramientas nativas de Spring Boot junto con frameworks especializados para crear aplicaciones que no solo funcionen correctamente, sino que también proporcionen información valiosa sobre su estado interno.

Conceptos clave que aprenderás

Spring Boot Actuator

Descubrirás cómo configurar y personalizar Spring Boot Actuator para exponer endpoints de salud, métricas y información de la aplicación. Aprenderás a crear endpoints personalizados y a securizar el acceso a información sensible.

Métricas con Micrometer

Dominarás el framework Micrometer para recopilar métricas personalizadas de tu aplicación. Implementarás contadores, temporizadores, medidores y distribuciones para monitorizar aspectos específicos de tu lógica de negocio.

Logging estructurado

Aprenderás a configurar logging estructurado utilizando Logback y SLF4J, implementando patrones como MDC (Mapped Diagnostic Context) para correlacionar logs entre diferentes componentes de la aplicación.

Trazas distribuidas

Implementarás trazas distribuidas usando Spring Cloud Sleuth o Micrometer Tracing para seguir el flujo de peticiones a través de múltiples servicios y componentes.

Integración con sistemas de monitorización

Configurarás la integración con sistemas populares como Prometheus, Grafana, ELK Stack y Jaeger para visualizar y analizar los datos de observabilidad recopilados.

Aplicaciones prácticas

En el desarrollo de microservicios, la observabilidad permite identificar cuellos de botella entre servicios y diagnosticar problemas de latencia. Las métricas personalizadas ayudan a monitorizar KPIs de negocio como tasas de conversión o tiempos de procesamiento de pedidos.

Los logs estructurados facilitan la búsqueda y análisis automatizado de eventos, especialmente útil para detectar patrones de error o comportamientos anómalos en aplicaciones de alto tráfico.

Las trazas distribuidas son esenciales para debugging en arquitecturas complejas, permitiendo seguir una petición desde el API Gateway hasta la base de datos, identificando exactamente dónde se producen los retrasos.

Prerrequisitos y nivel

Este módulo requiere conocimientos sólidos de Spring Boot y familiaridad con conceptos de desarrollo web. Es recomendable tener experiencia previa con anotaciones de Spring, configuración de aplicaciones y manejo de dependencias con Maven o Gradle.

El nivel es intermedio-avanzado, diseñado para desarrolladores que ya han creado aplicaciones Spring Boot básicas y buscan implementar prácticas profesionales de monitorización y debugging.

Spring Cloud es el ecosistema canónico para construir arquitecturas de microservicios en el stack Java moderno. Sobre Spring Boot 4 y Java 25 LTS, ofrece piezas listas para producción que resuelven los retos del sistema distribuido: configuración centralizada, descubrimiento de servicios, gateway de entrada, comunicación inter-servicios, patrones de resiliencia y mensajería asíncrona con Kafka.

En este módulo recorres los componentes esenciales del stack actual y descartas las piezas Netflix OSS legacy (Hystrix, Ribbon, Zuul) que ya no se mantienen.

Stack moderno (versiones vigentes en 2026)

Las dependencias actuales se gestionan vía Spring Cloud BOM 2025.0.x, alineado con Spring Boot 4.

Bootstrap de un microservicio con Spring Cloud

Cada microservicio es una aplicación Spring Boot independiente con sus propios starters. Una topología mínima incluye al menos cuatro procesos:

1. Un Config Server que sirve configuración versionada desde Git.
2. Un Eureka Server que actúa como registro de servicios.
3. Un Spring Cloud Gateway que expone el punto de entrada externo.
4. Una o varias aplicaciones de lógica de negocio registradas como Eureka clients, leyendo configuración del Config Server y comunicándose entre sí con OpenFeign o RestClient.

Las dependencias mínimas de un microservicio de negocio con Maven quedan así:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-config</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-openfeign</artifactId>
</dependency>

La clase principal del microservicio activa OpenFeign declarando @EnableFeignClients; el registro automático en Eureka ya no necesita anotación explícita desde Spring Cloud 2020+, basta con incluir el starter.

@SpringBootApplication
@EnableFeignClients
public class CatalogoServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(CatalogoServiceApplication.class, args);
    }
}

El cliente OpenFeign se define como interfaz declarativa, resolviendo el nombre lógico del servicio a través de Eureka y delegando el balanceo de carga en Spring Cloud LoadBalancer:

@FeignClient(name = "pedidos-service")
public interface PedidosClient {

    @GetMapping("/api/pedidos/{id}")
    Pedido obtenerPedido(@PathVariable("id") Long id);
}

A partir de este esqueleto, cada lección del módulo añade una pieza: configuración centralizada, registro y descubrimiento, gateway, resiliencia, mensajería y observabilidad. Al final del módulo aplicas todo en un proyecto integrador con tres microservicios reales sobre Docker Compose.

Este módulo conecta los conceptos de arquitectura hexagonal con el ecosistema Spring Boot. Repasarás muy brevemente la formulación canónica de Alistair Cockburn (puertos y adaptadores, regla de dependencia) y pasarás de inmediato a ver cómo se traducen esas piezas a un proyecto Spring Boot 4 sobre Java 25 LTS.

El objetivo no es repetir teoría agnóstica, sino fijar el vocabulario de equivalencias que usarás en los siguientes ocho módulos: qué Spring beans implementan los puertos, qué adaptadores aparecen de forma natural en Spring (REST, JPA, Kafka, RestClient), cuándo conviene aplicar el patrón en un microservicio real y cuándo es sobre-ingeniería para un CRUD pequeño.

Lo que aprenderás

Hexagonal en cuatro frases para tu equipo

El patrón ports and adapters propone aislar la lógica de negocio en un núcleo libre de Spring, JPA y dependencias técnicas. Los puertos primarios son las interfaces que el exterior invoca para pedir cosas al negocio. Los puertos secundarios son las interfaces que el negocio invoca para hablar con infraestructura. Los adaptadores implementan ambos lados respetando esas interfaces.

Regla de dependencia traducida a paquetes Spring

En un proyecto Spring Boot la regla se traduce en paquetes concretos: domain no puede importar nada de application ni de infrastructure. application puede importar de domain y nada más. infrastructure puede importar de application y de domain. ArchUnit codifica esa regla como tests JUnit 6 que fallan el pipeline.

Hexagonal frente a Controller, Service, Repository

La arquitectura por capas tradicional acaba acoplando la entidad JPA al controller a través del servicio. Cuando cambias el ORM o el motor de base de datos, las grietas aparecen en todos los servicios. Hexagonal coloca un puerto secundario entre el servicio (caso de uso) y el JPA adapter, de forma que sustituir Hibernate por MongoDB toca solo el adaptador.

Cuándo aplicarlo en un proyecto Spring

Hexagonal aporta valor cuando hay reglas de negocio reales (precios, descuentos, validaciones, eventos), múltiples canales de entrada o salida y plazos largos de mantenimiento. En un CRUD pequeño con un único frontend y un único motor de persistencia el coste de los puertos extra supera al beneficio. Este módulo te da los criterios para decidir.

Por qué importa

Muchos equipos copian la estructura hexagonal de un blog post sin entender el porqué. El resultado es código con Port, Adapter y UseCase en los nombres pero con dependencias cruzadas que rompen la regla. Este módulo te da el modelo mental para que cada paquete y cada bean tenga su sitio razonado, no decorativo. Es la base sobre la que los ocho módulos siguientes construyen un microservicio Spring Boot 4 hexagonal completo, listo para producción y para auditorías de arquitectura.

Aquí pasas del diagrama hexagonal a la estructura real de un proyecto Spring Boot 4. Verás dos plantillas de partida totalmente funcionales: una en monomódulo Maven ideal para microservicios pequeños y otra en multimódulo Maven o Gradle para proyectos más grandes donde el dominio merece estar en un artefacto independiente.

El módulo te enseña dónde colocar @SpringBootApplication, cómo configurar @ComponentScan para que domain no se vea afectado por la autoconfiguración, qué dependencias permite cada módulo y cómo organizar los pom.xml o los build.gradle.kts para que el compilador rompa la build si alguien intenta saltarse la regla de dependencia desde un import.

Lo que aprenderás

Estructura de paquetes domain, application, infrastructure

La convención es un único groupId con tres paquetes hermanos: com.empresa.servicio.domain, com.empresa.servicio.application y com.empresa.servicio.infrastructure. Cada uno con subpaquetes coherentes (domain.model, application.usecase, application.port.in, application.port.out, infrastructure.adapter.in.web, infrastructure.adapter.out.persistence).

Configuración del escaneo de beans

@SpringBootApplication arranca el escaneo desde su paquete y todos los hijos. Eso vale para monomódulo, pero exige que la clase main viva en el paquete raíz, no dentro de infrastructure. Verás el patrón canónico y los errores típicos cuando alguien mueve la clase main "porque era infraestructura".

Multimódulo Maven con dependencias acotadas

En proyectos grandes el dominio merece estar en un módulo Maven aparte que no depende de Spring Boot. La build te garantiza la regla de dependencia a nivel de compilador, sin necesidad de tests de arquitectura: el módulo domain ni siquiera tiene spring-context en el classpath.

Multimódulo Gradle con includeBuild

Para Gradle el patrón equivalente usa subprojects o composite builds. Verás el settings.gradle.kts canónico, la configuración de Spring Boot 4 con Gradle y cómo aplicar versionado centralizado desde la raíz.

Por qué importa

Una estructura de paquetes mal pensada se nota a los seis meses, cuando aparecen los primeros refactors. Si el dominio tiene Spring en el classpath, alguien acabará anotándolo con @Component. Si el escaneo de beans toca el paquete domain, los tests de unidad arrastran el contexto completo. Si los módulos del multimódulo no tienen dependencias acotadas, los pull requests acaban añadiendo imports prohibidos sin que nadie los detecte. Este módulo previene esos tres síntomas con plantillas reales que puedes copiar al primer microservicio.

Este módulo te enseña a modelar el dominio de un microservicio Spring Boot 4 usando exclusivamente Java 25 LTS y la librería estándar. Verás cómo aprovechar records para value objects, sealed types para resultados algebraicos, pattern matching para procesar variantes y constructores compactos para validar invariantes sin contaminar el modelo con anotaciones del framework.

El dominio que construyes aquí compila y se ejecuta aunque borres todas las dependencias del pom.xml excepto el JDK. Esa es la propiedad clave que mantiene los tests de dominio en milisegundos y permite que el negocio sobreviva a cambios de ORM, de framework o de motor de persistencia.

Lo que aprenderás

Dominio puro sin anotaciones JPA ni Spring

El paquete domain solo importa java.*, sus propias clases y, como mucho, librerías neutras como SLF4J. Nada de @Entity, @Component, @Transactional ni Lombok agresivo. Verás cómo eliminar la dependencia de Lombok cuando los records hacen ese trabajo y por qué @Data en una entidad de dominio es un olor.

Value objects con records y constructores compactos

Los value objects representan conceptos con identidad por valor (Dinero, Email, IBAN, Coordenadas). Los implementarás como records de Java 25 con constructores compactos que validan invariantes en la creación, evitando que existan instancias inválidas. Comparativa con la implementación pre-records y por qué los records resuelven el patrón de forma idiomática.

Entidades y agregados como límite de consistencia

La entidad Pedido o Cuenta mantiene identidad por id, no por valor. Verás patrones de fábrica estáticos, validación de invariantes en cada transición y por qué un agregado se diseña alrededor de la invariante de consistencia transaccional. Modelado del agregado Pedido con líneas, descuentos e importes en una banca o e-commerce real.

Domain services y domain events

Los domain services alojan lógica entre entidades que no encaja en ninguna sola (calculador de impuestos, motor de promociones). Los domain events modelan hechos que han ocurrido en el negocio (PedidoConfirmado, PagoRechazado) y se materializan como records inmutables que el agregado expone para que el caso de uso los publique fuera.

Por qué importa

Un dominio acoplado a Spring obliga a arrancar el contexto para cualquier test, los tests duran minutos, las refactorizaciones se vuelven caras y el negocio queda atrapado en decisiones técnicas tomadas en 2018. Un dominio puro modelado con Java 25 idiomático mantiene tests en milisegundos, deja el negocio expresivo y aísla las decisiones de infraestructura para que el equipo pueda iterar sin miedo. Este módulo te entrega las cinco piezas (value objects, entidades, agregados, domain services, domain events) listas para combinarse con los casos de uso del módulo siguiente.

La capa application es la que orquesta el dominio. Recibe un comando desde un adaptador primario (un REST controller, un listener Kafka), invoca los métodos del dominio para aplicar la regla de negocio y persiste los cambios a través de un output port que infraestructura implementa.

Este módulo te enseña a diseñar application services como beans @Service que dependen exclusivamente de tipos del dominio y de interfaces de output port, nunca de Spring Data, Hibernate ni ningún detalle técnico. Verás el patrón command/query, cuándo conviene anotar con @Transactional, cómo modelar resultados algebraicos con sealed types y cómo evitar las dos trampas habituales: la capa application anémica y la capa application gorda con lógica de negocio.

Lo que aprenderás

Application services como orquestadores

Un application service es un bean @Service con un método público por caso de uso. Recibe un command record inmutable, valida estructuralmente, carga agregados a través de un output port, invoca métodos del dominio y persiste el resultado. No contiene lógica de negocio, no decide reglas, no calcula precios: la lógica vive en el dominio.

Input ports y casos de uso explícitos

Los input ports son interfaces declaradas en application/port/in/ que el adaptador primario invoca. Un input port por caso de uso (CrearPedidoUseCase, ConfirmarPagoUseCase) hace que el código se autodocumente y permite testear cada caso de forma aislada. Comparativa con el patrón *Service Spring clásico y por qué un service con quince métodos es un olor.

Command y query separados

Los commands modifican estado y devuelven mínima información (id generado, resultado algebraico de éxito o fracaso). Las queries solo leen, pueden saltarse el agregado y devolver DTOs directamente desde un proyección JPA. Aplicarás CQS (no CQRS completo) para mantener cada método con un único propósito.

Output ports y transacciones

Los output ports son interfaces que el caso de uso declara para sus necesidades (persistir un agregado, publicar un evento, enviar un email). Verás dónde anotar @Transactional (en el application service, nunca en el dominio), cómo gestionar transacciones que cruzan múltiples output ports y por qué el aislamiento de transacciones debe vivir aquí, no en infraestructura.

Por qué importa

La capa application es donde se rompe la mayoría de las implementaciones hexagonales que ves en blogs. El antipatrón típico mete lógica de negocio en @Service y deja el dominio como bolsa de DTOs. El resultado: tests lentos, refactorizaciones imposibles y un dominio que no expresa nada. Este módulo te entrega el patrón canónico que mantiene el application service delgado, expresivo y testeable con mocks de output ports en milisegundos. Es la pieza que conecta el dominio puro del módulo anterior con los adaptadores REST, JPA y Kafka de los módulos siguientes.

Los adaptadores primarios son las puertas de entrada de tu microservicio. Cuando el mundo exterior quiere hacer algo en el dominio (crear un pedido, consultar un saldo, confirmar un pago) lo hace a través de un adaptador primario que recibe el formato externo (JSON HTTP, mensaje Kafka, llamada gRPC) y lo traduce a un command que invoca el input port del caso de uso.

Este módulo cubre los tres adaptadores primarios más habituales en Spring Boot 4: REST controller con ProblemDetails RFC 7807 y Bean Validation, gRPC service con grpc-spring-boot-starter y listener Kafka con @KafkaListener. En todos los casos verás el patrón canónico: el adaptador no conoce el dominio entero, solo el input port que necesita.

Lo que aprenderás

REST controller como adaptador primario

El controller recibe un DTO de entrada (anotado con @Valid), lo mapea a un command del dominio, invoca el input port y devuelve un DTO de salida o un ProblemDetail. El controller no anota @Transactional, no usa repositorios, no conoce entidades JPA. Verás patrones de mapeo manual y con MapStruct, y por qué los DTOs viven en infrastructure.adapter.in.web.dto, no en domain.

DTO mapping bidireccional sin frameworks pesados

El mapeo entre DTO y command es donde más se cuela el acoplamiento. Verás cómo modelar DTOs como records, mapear con métodos estáticos from() y to() que conviven en el propio DTO y cuándo introducir MapStruct sin perder claridad. Antipatrones: usar la entidad JPA como DTO de salida y exponerla con @JsonIgnore.

Manejo de errores con ProblemDetails RFC 7807

Spring Boot 4 incorpora ProblemDetails (RFC 7807) como formato canónico de errores HTTP. Verás cómo capturar excepciones del dominio con @RestControllerAdvice, traducirlas a ProblemDetail con código HTTP semántico, incluir type, title, detail y instance y por qué este formato es superior al payload propietario { error: "..."}. Errores de validación de Bean Validation también con ProblemDetails.

Listeners Kafka como adaptador primario

Cuando un mensaje Kafka activa un caso de uso (confirmar-pago, cancelar-pedido), el @KafkaListener se comporta como un controller: deserializa el mensaje, lo mapea a un command, invoca el input port y gestiona el ack o el reintento. Verás el patrón canónico, manejo de errores con dead letter topic y por qué este adaptador permite que el mismo caso de uso reciba tráfico HTTP y mensajes Kafka sin cambiar el dominio.

Por qué importa

Los adaptadores primarios son la frontera entre el negocio y el mundo. Si los implementas como hace un proyecto Controller-Service-Repository tradicional, el dominio acaba contaminado con DTOs, anotaciones HTTP y dependencias de Jackson. Si los mantienes finos y delegas todo en los input ports, conseguirás añadir un canal gRPC junto al REST en pocas horas, sin tocar ni una línea del dominio. Este módulo te enseña a mantener esa disciplina con patrones reales de microservicios bancarios y de logística.

Los adaptadores secundarios son las puertas de salida del dominio: persistir un agregado, llamar a un servicio externo, publicar un evento. Cada uno implementa un output port que el caso de uso declaró en el módulo anterior, y se inyecta como @Component o @Service cuando arranca el contexto Spring.

Este módulo cubre los adaptadores secundarios más habituales en proyectos Spring Boot 4: JPA adapter con entidades de persistencia separadas del dominio, MongoDB adapter para repositorios documentales, HTTP client adapter con el nuevo RestClient de Spring Framework 7 y Kafka producer adapter integrado con domain events. La regla de oro: el adaptador conoce el dominio (porque mapea hacia y desde él), pero el dominio no conoce el adaptador.

Lo que aprenderás

JPA adapter con entidades de persistencia separadas

Lo más fácil es anotar la entidad del dominio con @Entity y reutilizarla. Lo correcto es declarar una entidad de persistencia distinta (PedidoJpaEntity) en infrastructure.adapter.out.persistence.jpa y mapearla a la entidad del dominio (Pedido) en el adaptador. Verás los dos enfoques, sus implicaciones y por qué la separación se paga sola a partir del segundo refactor.

Mapeo dominio-entidad bidireccional

El mapeo se concentra en un único punto: una clase PedidoJpaMapper que toma un Pedido del dominio y devuelve un PedidoJpaEntity y viceversa. Usa MapStruct, conversión manual con records o el patrón funcional. Verás cuándo conviene cada uno y cómo evitar el N+1 cuando el agregado contiene colecciones.

MongoDB adapter para dominios documentales

Cuando el agregado tiene una estructura naturalmente documental (un pedido con líneas anidadas, un perfil de usuario con preferencias) MongoDB encaja mejor que el ORM relacional. Verás cómo declarar la entidad @Document, mapearla al dominio y por qué la separación dominio-entidad es aún más importante aquí, donde el documento puede evolucionar sin necesidad de migraciones DDL.

HTTP client adapter con RestClient

Spring Framework 7 introduce RestClient como reemplazo idiomático de RestTemplate. El adaptador HTTP encapsula la llamada al servicio externo (pasarela de pagos, calculador de IVA, AEAT), traduce errores de red a excepciones del dominio o resultados algebraicos, y aplica timeouts y reintentos con Resilience4j cuando procede.

Kafka producer adapter y domain events

Cuando el agregado publica un domain event, el adaptador secundario lo serializa y lo manda a Kafka. Verás el patrón outbox para garantizar consistencia entre BD y broker, cómo evitar la publicación de eventos huérfanos en caso de rollback transaccional y cómo separar el formato del evento de dominio del formato del mensaje Kafka externo (CloudEvents, Avro, JSON Schema).

Por qué importa

Los adaptadores secundarios son donde la mayoría de proyectos Spring Boot acaban acoplándose. Una vez la entidad JPA es la entidad del dominio, ya no hay forma de cambiar de motor de persistencia ni de escribir tests rápidos. Una vez el RestTemplate vive en el caso de uso, la lógica de negocio depende del servicio externo. Este módulo te enseña a colocar cada llamada técnica detrás de un output port y a mantener el dominio limpio mientras infraestructura evoluciona con libertad.

La arquitectura hexagonal en Spring Boot solo paga sus dividendos cuando la pirámide de testing se alinea con la estructura del proyecto. Cada capa se prueba con la herramienta adecuada: el dominio sin Spring, el application service con mocks de output ports, los adaptadores con slices y el stack completo con Testcontainers.

Este módulo te enseña a diseñar y ejecutar esa pirámide en JUnit 6 sobre Spring Boot 4: tests de dominio que corren en milisegundos sin levantar contexto, tests de aplicación que mockean output ports con Mockito 5, tests de adaptadores REST con @WebMvcTest y @MockitoBean, tests de adaptadores JPA con @DataJpaTest y PostgreSQL real con Testcontainers, e integraciones end-to-end con todo el stack. Cierra con contract testing con Pact para microservicios.

Lo que aprenderás

Tests de dominio sin Spring en milisegundos

El dominio puro no necesita Spring para probarse. Los tests viven en domain/src/test/java, no anotan nada de Spring y se ejecutan en milisegundos. Verás cómo cubrir invariantes, transiciones de estado y domain services con tests parametrizados de JUnit 6, sin Mockito si la lógica es funcional.

Application services con mocks de output ports

Cada caso de uso recibe sus output ports por constructor. En el test los sustituyes por mocks de Mockito 5 (o fakes a mano, que suelen ser más expresivos) y verificas la orquestación: que el caso de uso carga el agregado, invoca el método de negocio correcto, persiste el resultado y publica el evento. Tampoco aquí necesitas Spring.

Slice tests con @WebMvcTest y @DataJpaTest

Los adaptadores primarios REST se prueban con @WebMvcTest y @MockitoBean para mockear el input port. Los adaptadores secundarios JPA se prueban con @DataJpaTest apuntando a Testcontainers PostgreSQL real, evitando H2 cuando producción es PostgreSQL. Verás patrones para validar el mapeo dominio-entidad y para detectar problemas N+1 con assertSelectCount de spring-test.

Testcontainers para integración del stack completo

Un test de integración levanta Spring Boot real con @SpringBootTest, conecta contra PostgreSQL, Kafka y servicios externos a través de Testcontainers (incluido WireMock). Verás cómo organizar perfiles Spring para test, cómo reutilizar containers entre tests con @Testcontainers(parallel = true) y cómo evitar que la suite de integración se vuelva la suite "lenta y frágil" del proyecto.

Contract testing con Pact entre microservicios

Cuando dos microservicios hexagonales se hablan, los tests de integración no bastan: necesitas garantía contractual. Pact permite que el consumer declare el contrato esperado en un test JUnit y que el provider lo verifique en su pipeline. Verás el flujo completo con Pact Broker, integración con Spring Cloud Contract y por qué este testing complementa a Testcontainers.

Por qué importa

Sin pirámide de testing, una arquitectura hexagonal acaba con los mismos tests que un monolito tradicional: pocos, lentos y frágiles. Sin tests rápidos del dominio el equipo deja de refactorizar. Sin tests de integración con Testcontainers los bugs reales se descubren en producción. Sin contract testing los breaking changes entre microservicios rompen el sistema cada deploy. Este módulo te entrega la disciplina y los patrones para que la pirámide funcione en proyectos reales con dependencias externas, transacciones y mensajería asíncrona.

ArchUnit traduce las reglas de la arquitectura hexagonal a tests JUnit 6 que se ejecutan en CI y bloquean cualquier pull request que las rompa. Sin ArchUnit la regla de dependencia se mantiene "por disciplina" y al sexto mes alguien acaba importando infrastructure desde domain "porque era más fácil".

Este módulo te enseña a definir reglas concretas para un proyecto Spring Boot 4 hexagonal: capas con layeredArchitecture(), naming conventions (Port, UseCase, Adapter), prohibiciones de imports (org.springframework.* en domain), detección de ciclos entre paquetes y frozenRules para adoptar ArchUnit en código legacy sin romper la build. Verás cómo integrar todo en GitHub Actions y GitLab CI para que el pipeline falle el merge antes de que el código llegue a main.

Lo que aprenderás

Reglas básicas con classes().that().should()

ArchUnit ofrece una DSL fluida en Java para expresar reglas: noClasses().that().resideInAPackage("..domain..").should().dependOnClassesThat().resideInAnyPackage("org.springframework..", "jakarta.persistence.."). Empezarás con este patrón y verás cómo expandirlo a casos del proyecto real.

LayeredArchitecture y OnionArchitecture

Para arquitecturas con capas claras, ArchUnit incluye DSLs específicas: layeredArchitecture() para capas tradicionales y onionArchitecture() para hexagonal/clean. Verás cómo declarar las capas Domain, Application, Infrastructure y forzar que Domain no sea accesible desde fuera más que con sus propios tipos.

Naming conventions exigibles

Cualquier interfaz que termine en UseCase debe vivir en application.port.in. Cualquier clase que termine en Adapter debe vivir en infrastructure.adapter.*. Cualquier clase anotada con @Component no debe vivir en domain. Verás cómo declarar esas reglas con la DSL y por qué la coherencia de naming es la primera línea de defensa frente al code rot.

Frozen rules para adoptar ArchUnit en legacy

En un proyecto greenfield ArchUnit pasa desde el commit cero. En un proyecto legacy las reglas fallan con cientos de violaciones. FreezingArchRule.freeze() captura el estado actual de violaciones en un fichero y solo falla ante violaciones nuevas, permitiendo adopción gradual sin big bang.

Por qué importa

Una arquitectura hexagonal sin tests de arquitectura es decorativa. Funciona el primer mes, se degrada en el segundo, y al sexto el proyecto vuelve a tener el mismo acoplamiento que un monolito tradicional. ArchUnit convierte las reglas en contrato exigible: cada PR ejecuta los tests de arquitectura y si alguien intenta importar jakarta.persistence desde domain, la build falla con un mensaje claro que apunta a la clase exacta. Este módulo te entrega el catálogo de reglas que defienden la regla de dependencia en proyectos Spring Boot reales y la integración con GitHub Actions y GitLab CI lista para copiar.

La mayoría de equipos no parten de cero. Tienen un monolito Spring Boot maduro con Controller, Service y Repository acoplados a JPA, miles de tests integrados y una deuda técnica acumulada en cinco o seis años de añadir features. Este módulo te enseña a migrarlo a arquitectura hexagonal sin big bang, sin parar entregables y sin perder la confianza del negocio.

Verás el método en tres fases: diagnóstico con métricas reales (acoplamiento entre paquetes, tiempo de los tests, cobertura por capa), patrón strangler fig para extraer bounded contexts uno a uno, y plan de rollout incremental con criterios objetivos para decidir cuándo seguir y cuándo parar. Casos reales de banca, telco y sector público donde la migración aportó valor en seis meses.

Lo que aprenderás

Diagnóstico del monolito

No migras a hexagonal porque "está de moda". Migras cuando hay síntomas concretos: tests de minutos, refactors que rompen módulos no relacionados, miedo a cambiar el ORM, dificultad para añadir nuevos canales de entrada (gRPC, eventos Kafka). Verás cómo medir esos síntomas con herramientas reales (jdepend, Sonar, ArchUnit en modo informativo) para defender la inversión ante stakeholders.

Strangler fig: extracción progresiva

El patrón strangler fig (popularizado por Martin Fowler) consiste en construir la nueva arquitectura junto a la vieja, redirigir tráfico progresivamente y eliminar la vieja cuando el nuevo módulo cubre toda la funcionalidad. Aplicado a hexagonal, significa elegir un bounded context con bajo acoplamiento, extraer su dominio puro y sus casos de uso, dejar los adaptadores REST y JPA conectados al código existente, y reescribir el feature por feature.

Migración por bounded contexts

No migras módulos arbitrarios. Migras bounded contexts identificados con sesiones de event storming con el equipo de negocio. Cada bounded context tiene su propio lenguaje ubicuo, sus propios agregados y suele tener bajo acoplamiento con los demás. Verás cómo planificar el orden de migración para maximizar el aprendizaje y minimizar el riesgo.

Métricas de cobertura por capa y plan de rollout

Cada bounded context migrado se mide: tiempo de los tests, cobertura del dominio sin Spring, número de imports prohibidos, tiempo medio de añadir un feature. Esas métricas alimentan el cuadro de mando que muestras al CTO o al stakeholder responsable de la inversión. Verás los KPIs que funcionan en consultoras IT y cuáles son demasiado abstractos para defender la migración.

Por qué importa

Un monolito Spring Boot sin estrategia de migración acaba en uno de tres lugares: reescritura desde cero (carísima, casi siempre fallida), bloqueo de las grandes refactorizaciones (deuda crece exponencialmente) o migración caótica feature a feature sin patrón (acaba peor que el original). El método strangler fig + bounded contexts es la única forma que funciona consistentemente en consultoras IT españolas con presupuestos reales y deadlines de negocio. Este módulo te entrega el playbook completo para arrancar mañana mismo, con criterios objetivos para defender cada paso y un microservicio piloto que sirva como prueba de concepto interna.