Migración a Spring Boot 3 y Java 21: Guía técnica para entornos empresariales
Descubre cómo modernizar las aplicaciones empresariales migrando a Spring Boot 3 y Java 21 para lograr un mayor rendimiento y escalabilidad
Artículo elaborado por:
Desarrollador especializado en backend con tecnologías como Java y Spring. Graduado de Ingeniería informática del Software por la Universidad de Sevilla y en constante formación de nuevas tecnologías desde entonces, enfocandome más en un perfil devOps. Mis principales hobbies son la natación, los videojuegos y el tiro con arco.
Doctor en informática por la Universidad Politécnica de Valencia con mención Internacional y Cum Laude en Abril de 2026. Investigaciones sobre temas relacionados con Machine Learning aplicado a la arquitectura de los procesadores. Diseño y análisis de sistemas de memoria hibrida en simuladores. Implementación de técnicas de prefetch. Diseño de planificadores dinámicos en sistemas con procesadores heterogéneos Intel
Scrum Master e ingeniero de software Backend especializado en Java y Spring. Graduado en Ingeniería Informática y Máster en Ingeniería y Tecnología de Sistemas Software. Autor de una publicación internacional en testing automatizado.
Analista Programador especializado en Java y Python. Apasionado de los gráficos 3D y con gran interés en Machine Learning e Inteligencia Artificial.
Ingeniero de software sénior, especializado en el desarrollo de aplicaciones EDI con Java y Spring Boot. Tras estudiar Ingeniería del Software en la Universidad de Sevilla, me incorporé al equipo de I+D de EDICOM. Me interesa especialmente la calidad y la mantenibilidad del código, así como debatir distintos enfoques técnicos con mis compañeros para tomar las mejores decisiones de arquitectura.
En mi tiempo libre, disfruto programando y explorando nuevas tecnologías, jugando al pádel y bailando bachata.
Contenidos
- Introducción
- Beneficios de la migración
- Pasos previos y planificación
- Herramientas de apoyo para la migración
- Empaquetado y despliegue
- Librerías y dependencias
- Configuración inicial en Spring Boot
- Gestión de dependencias circulares
- Interfaz REST
- Buenas prácticas
- Conclusión
1. Introducción
En entornos empresariales donde la escalabilidad, la seguridad y la eficiencia son factores críticos, mantener la infraestructura tecnológica actualizada es una necesidad estratégica. Este artículo aborda el proceso de migración desde un stack tradicional basado en Apache Tomcat 7 y Java JDK 8 hacia una arquitectura moderna con Spring Boot 3 y Java 21, una transición que es una mejora sustancial en rendimiento, mantenibilidad y preparación para el cloud.
El punto de partida habitual en muchas organizaciones es un ecosistema monolítico, con servidores de aplicaciones externos y configuraciones manuales que dificultan la agilidad. El objetivo de la migración es claro: adoptar un modelo más flexible y robusto, donde las aplicaciones se empaqueten como JAR ejecutables, integren un Tomcat embebido y aprovechen las ventajas de Java 21, incluyendo nuevas características del lenguaje y optimizaciones en la máquina virtual.
Esta evolución no solo responde a tendencias tecnológicas, sino a la necesidad de soportar arquitecturas cloud-native, despliegues en contenedores y prácticas modernas como microservicios.
2. Beneficios de la migración
Migrar a Java 21 y Spring Boot 3 es una apuesta por un ecosistema más seguro, eficiente y preparado para los retos actuales. A continuación, se detallan las ventajas más relevantes:
2.1 Mejoras en Java 21 frente a Java 8
La evolución del lenguaje y la plataforma Java en los últimos años ha sido significativa. Entre las mejoras más destacadas:
- Rendimiento y eficiencia
- Nuevos algoritmos de garbage collector como ZGC y mejoras en G1, reduciendo la latencia y optimizando el uso de memoria.
- Optimizaciones en el compilador JIT y en el tiempo de ejecución para acelerar la ejecución.
- Nuevas características del lenguaje
- Records: clases inmutables con menos código boilerplate.
- Pattern Matching: simplificación en el uso de instanceof y estructuras switch.
- Text Blocks: manejo más sencillo de cadenas multilínea. Por ejemplo, para JSON o SQL.
- Sealed Classes: control granular sobre la herencia.
- Virtual Threads (Project Loom): simplifican el desarrollo de aplicaciones concurrentes y reducen el coste de gestionar grandes volúmenes de tareas bloqueantes, especialmente en operaciones de entrada/salida.
- Mayor seguridad
- Mejoras continuas en TLS, criptografía, algoritmos soportados y actualizaciones de seguridad de la plataforma.
- Soporte a largo plazo (LTS)
- Java 21 es una versión LTS, lo que garantiza actualizaciones y soporte durante varios años.
2.2 Ventajas de Spring Boot 3
La adopción de Java 21 encaja de forma natural con Spring Boot 3, ya que esta versión requiere Java 17 o superior y está alineada con el ecosistema actual de Spring Framework 6 y Jakarta EE. Esta versión incorpora mejoras sustanciales en el framework que habilitan la implementación de arquitecturas modernas. Algunas de estas ventajas son:
- Compatibilidad con Java 17+. Permite aprovechar todas las mejoras del lenguaje y la plataforma.
- Basado en Spring Framework 6. Soporte para Jakarta EE 10 y mejor integración con tecnologías como WebFlux, Reactive Programming y Kotlin.
- Observabilidad mejorada. Integración nativa con Micrometer, Prometheus y OpenTelemetry, facilitando el monitoreo y la trazabilidad.
- Configuración simplificada. Uso flexible de application.yml o application.properties y autoconfiguración más inteligente.
2.3 Tomcat embebido y despliegue cloud-ready
Spring Boot 3 incluye un servidor Apache Tomcat embebido en la aplicación. Esto aporta las siguientes ventajas:
- Despliegue más sencillo. No es necesario instalar ni configurar Tomcat por separado.
- Empaquetado como JAR ejecutable. Simplifica la distribución y reduce la complejidad operativa.
- Preparado para contenedores. Ideal para entornos Docker, Kubernetes y serverless.
- Menor dependencia del sistema operativo. Todo está contenido en un único artefacto, lo que facilita la replicación y escalabilidad.
3. Pasos previos y planificación
Antes de iniciar la migración, es recomendable analizar los cambios necesarios y las partes críticas implicadas para minimizar riesgos y garantizar un proceso ordenado. A continuación, se exponen los diferentes puntos a considerar.
3.1 Crear un equipo dedicado
Debido a la magnitud y ámbito de la migración, se recomienda formar un equipo especializado, con experiencia en versiones recientes de Java y Spring Boot, que se dedique exclusivamente a este proyecto. De ello se derivan beneficios como:
- Foco total en la migración. Permite mantener el foco en la migración evitando distracciones de otras tareas.
- Reducción de errores por falta de contexto. Al ser todos conscientes de los cambios se evitan errores por falta de contexto.
- Mejor coordinación entre miembros. Los miembros del equipo estarán al tanto de los cambios realizados.
- Agilidad en la toma de decisiones. Gracias a la mejor coordinación y contexto compartido, la toma de decisiones es más fácil y rápida.
3.2 Proteger el código
Durante la transición, el control del código es necesario para evitar conflictos y errores accidentales. Para evitar esto, se recomiendan las siguientes prácticas entre otras:
- Crear una rama exclusiva para la migración.
- Bloquear commits de personas ajenas a ese equipo.
- Restringir permisos de merge para evitar que se integre código no validado en la rama principal.
3.3 Consideraciones técnicas iniciales
Un proceso de migración también requiere prever:
- Cambios estructurales en el proyecto.
- Dependencias y librerías que requieren actualización o exclusión debido a incompatibilidad entre versiones de Java.
- Ajustes en la configuración de ejecución, especialmente por el sistema modular introducido en Java 9.
- Código legacy o que requiera de unas dependencias específicas y no se puedan actualizar. En estos casos, habrá que revisar cuál es la mejor opción para esas partes del código:
- Eliminarse por obsolescencia.
- Migrarse a microservicios para mejorar escalabilidad y poder mantener las versiones de dependencias que necesiten.
4. Herramientas de apoyo para la migración
La migración a Spring Boot 3 y Java 21 implica cambios estructurales, refactorizaciones y ajustes en dependencias. Para facilitar este proceso, existen herramientas que ayudan a automatizar parte del trabajo, identificar incompatibilidades y librerías incompatibles por cambios en la paquetería.
A continuación, se mencionan las más útiles, junto con enlaces a documentación oficial para ampliar información.
4.1 OpenRewrite
Motor de refactorización que permite aplicar recetas para actualizar dependencias, paquetes y anotaciones.
Documentación: https://docs.openrewrite.org/
4.2 IntelliJ IDEA Ultimate
IntelliJ IDEA Ultimate ofrece un conjunto de herramientas avanzadas que facilitan el proceso de migración a Spring Boot 3 y Java 21. El IDE ayuda a identificar código obsoleto, aplicar refactorizaciones seguras y detectar incompatibilidades tras actualizar dependencias, anotaciones o versiones del JDK.
Incluye inspecciones automáticas, sugerencias de corrección y asistentes de migración que simplifican tareas como actualizar APIs antiguas, mejorar configuraciones de Spring y adaptar el proyecto a las nuevas versiones del framework y del lenguaje.
Documentación: https://www.jetbrains.com/guide/java/
5. Empaquetado y despliegue
La migración a Spring Boot 3 y Java 21 implica cambios profundos en empaquetado, despliegue y configuración. Los puntos más relevantes se exponen a continuación.
5.1 Ajustes de modularidad del JDK Java 9+
Desde Java 9, el sistema modular (Project Jigsaw) introducido afecta la visibilidad de clases internas. Esto puede generar errores en librerías que usan reflexión.
En algunos casos puede ser necesario añadir parámetros específicos en la JVM, como – – add-exports o – – add-opens, especialmente cuando una librería legacy accede mediante reflexión a APIs internas. Conviene tratarlos como ajustes excepcionales y documentarlos, no como una solución general. Siempre que sea posible, resulta preferible actualizar dichas librerías a versiones más recientes que ya se hayan adaptado al sistema modular de Java y no requieran este tipo de parámetros para su funcionamiento.
5.2 Cambio en el empaquetado
Con Spring Boot 3, el proyecto se empaqueta como un JAR ejecutable, lo que elimina la necesidad de utilizar archivos WAR y servidores Tomcat externos. Este enfoque simplifica los despliegues, reduce la complejidad operativa y permite crear réplicas idénticas para entornos de integración y producción.
Ventajas:
- Un único artefacto para todo el servicio.
- Ideal para entornos cloud-native.
5.3 Dockerización y despliegue en Kubernetes
- Docker: empaquetar la aplicación en una imagen ligera.
- Kubernetes: orquestación y escalabilidad automática.
- Integración con herramientas como Spring Boot Buildpacks para generar imágenes sin necesidad de Dockerfile manual.
Ejemplo de comando con Buildpacks:
6. Librerías y dependencias
La migración implica revisar todas las dependencias que ya tuviera el proyecto, además de añadir las nuevas dependencias necesarias para el arranque a través de Spring Boot.
6.1 Añadir las dependencias de Spring Boot
A la hora de incluir las dependencias necesarias para el uso de Spring Boot, se considera conveniente:
- Incluir la paquetería Spring Boot Starter: Esta librería permite iniciar un proyecto con Spring Boot de forma rápida y sencilla, evitando configuraciones complejas y reduciendo el tiempo de preparación del entorno. Eliminar dependencias previas de Spring Framework: No es necesario declarar explícitamente las librerías de Spring, ya que los paquetes starters las incorporan.
- Quitar librerías redundantes mediante exclusiones: Algunas librerías de Spring pueden ser arrastradas por otras dependencias. Es importante aplicar exclusiones en el pom.xml para evitar conflictos.
6.2 Conflictos con Javax
A partir de Spring Boot 3, el framework adopta Jakarta EE 10, lo que implica la migración completa desde los paquetes javax.* hacia jakarta.*. En una aplicación Spring Boot 3 conviene evitar la mezcla de APIs equivalentes basadas en javax.* y jakarta.*, ya que las dependencias que sigan arrastrando clases antiguas pueden provocar incompatibilidades en compilación o en tiempo de ejecución.
Por este motivo, es necesario revisar tanto el proyecto principal como todas las librerías externas que utilice, especialmente aquellas que generen código o gestionen servicios REST o SOAP. En muchos casos, puede ser útil apoyarse en herramientas mencionadas en el apartado 4 para automatizar parte de la detección y la migración.
6.2.1 Ejemplo habitual: conflictos con librerías externas
Durante la transición a Jakarta, algunas librerías externas no estaban todavía alineadas con las versiones requeridas por Spring Boot 3, lo que podía provocar incompatibilidades. Un ejemplo representativo fue Apache CXF. En el momento de la migración, la versión más reciente disponible pertenecía a la serie 4.0.x, que arrastraba dependencias Jakarta no alineadas con las utilizadas por Spring Boot 3 y Jakarta EE 10. Esto generaba conflictos de clases al ejecutar el proyecto.
Dado que en ese momento aún no existía una versión de CXF plenamente compatible para nuestro caso, la solución temporal consistió en excluir la dependencia transitiva incompatible y fijar explícitamente la versión adecuada. Meses más tarde, con la aparición de la serie CXF 4.1.x, el problema pudo resolverse de forma más natural actualizando la librería a una versión ya alineada con Jakarta EE 10.
Este ejemplo ilustra que, además del propio código del proyecto, es importante revisar todas las dependencias externas y su árbol transitivo. En una migración a Spring Boot 3 y Java 21, cualquier librería que no haya completado su adaptación a jakarta.* o que arrastre versiones no alineadas de APIs Jakarta puede provocar errores en compilación o en tiempo de ejecución.
6.3 Actualización a JUnit5
Si se quiere utilizar JUnit 5 en la migracion, es importante saber que el starter spring-boot-starter-test incluye todas las dependencias necesarias para configurar y ejecutar tests con esta versión. Si no es posible abordar la migración ahora, se puede recurrir a la librería JUnit Vintage para mantener la compatibilidad con JUnit 4 de forma temporal.
7. Configuración inicial en Spring Boot
La configuración en un proyecto en Spring Boot comienza definiendo una clase principal que actuará como punto de entrada de la aplicación. Esta clase incluye la anotación @SpringBootApplication, que habilita la autoconfiguración, el escaneo de componentes y otras funciones básicas del framework, tal y como se muestra en el Código 1.
@SpringBootApplication(scanBasePackages = "com.edicom")
public class MsApp {
public static void main(String[] args) {
SpringApplication.run(MsApp.class, args);
}
}
Código 1
A continuación, es habitual crear una clase de configuración adicional anotada con @Configuration, donde se pueden definir beans personalizados, añadir utilidades comunes o adaptar el comportamiento por defecto de Spring Boot. En el Código 2 se muestra un ejemplo de clase con dos beans ficticios.
@Configuration
public class AppConfig {
@Bean
public BeanOne beanOne() {
return new BeanOne(beanTwo());
}
@Bean
public BeanTwo beanTwo() {
return new BeanTwo();
}
}
Código 2
Uno de los beans más útiles de personalizar es el ObjectMapper. Spring Boot proporciona uno por defecto, pero ajustarlo de acuerdo con las necesidades del proyecto permite controlar aspectos como el formato de fechas, la serialización de valores nulos o la compatibilidad con estándares concretos. En el Código 3, se muestra un ejemplo de ObjectMapper donde se ha configurado algunas de estas propiedades.
@Bean(name = "JSON_MAPPER")
@Primary
public ObjectMapper jsonMapper () {
ObjectMapper jsonMapper = new ObjectMapper();
//Configuracion parser JSON
jsonMapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);
jsonMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
jsonMapper.configure(DeserializationFeature.READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE, true);
jsonMapper.setDateFormat(new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSZ"));
return jsonMapper;
}
Código 3
- Aspectos (@EnableAspectJAutoProxy): para lógica transversal como logging o auditoría
- Asincronía (@EnableAsync): para tareas en segundo plano.
- Tareas programadas (@EnableScheduling): para ejecuciones periódicas.
- Cachés (@EnableCaching): para poder utilizar cachés de Spring.
- Seguridad (@EnableMethodSecurity): para aplicar control de acceso a nivel de métodos.
En conjunto, estas clases y anotaciones constituyen la base de la configuración inicial de una aplicación Spring Boot 3. Cada figura representa un bloque funcional que, integrado correctamente, permite construir un punto de partida sólido antes de abordar configuraciones más específicas como interceptores, filtros o personalización de componentes del framework.
8. Gestión de dependencias circulares
Spring Boot 3 no permite por defecto las dependencias circulares, un comportamiento que en versiones anteriores podía pasar más desapercibido o resolverse de forma más permisiva. Una dependencia circular aparece cuando dos o más beans se necesitan mutuamente durante la inicialización del contexto, lo que impide a Spring determinar un orden válido de creación.
8.1 ¿Qué es una dependencia circular?
El caso más sencillo es el ciclo directo:
- A depende de B y
- B depende de A.
@Component
class A {
@Autowired
private B b;
}
@Component
class B {
@Autowired
private A a;
}
Código 4
El Código 4 muestra un ejemplo de dependencia cíclica. Este patrón (A ↔ B) obliga a Spring a crear simultáneamente ambos beans, lo cual ya no es posible en Spring Boot 3, provocando un error de arranque.
Sin embargo, las dependencias circulares también pueden aparecer de forma indirecta, a través de una cadena más larga (ver Figura 1).
A → B → C → D → A
Este tipo de ciclo es más difícil de detectar, porque ninguna clase “ve” explícitamente a la siguiente, pero el resultado es el mismo: el contexto no puede inicializarse.
Spring Boot detiene el arranque en cuanto detecta un ciclo, obligando a resolverlo antes de continuar. Aunque existe un parámetro para reactivar la tolerancia, no se recomienda:
spring.main.allow-circular-references=true
Este ajuste solo debería usarse como medida temporal y nunca en entornos de producción.
8.2 Soluciones a las dependencias circulares
En la mayoría de los casos, una dependencia circular no debe considerarse un problema de Spring, sino una señal de que el diseño de la aplicación puede mejorarse. Aunque existen diferentes mecanismos para romper temporalmente estos ciclos, la solución recomendada consiste en revisar la arquitectura y reducir el acoplamiento entre componentes. Las técnicas mostradas a continuación se presentan en orden aproximado de preferencia, desde las más recomendables hasta las más excepcionales.
8.2.1 Patrón DAO / reorganización de responsabilidades
Cuando dos clases dependen mutuamente entre sí, en la mayoría de los casos no se trata de un problema técnico del lenguaje o del framework, sino de un problema de diseño. Este tipo de dependencia circular suele ser un síntoma claro de que las responsabilidades no están bien delimitadas y que distintas capas de la aplicación se están mezclando indebidamente.
Normalmente, esta situación aparece cuando una clase encargada de la lógica de negocio comienza a asumir tareas de acceso a datos, o cuando un objeto de acceso a datos (DAO) incorpora decisiones de negocio que no le corresponden. El resultado es un acoplamiento innecesario que dificulta la evolución del código y favorece la aparición de ciclos directos o indirectos entre clases, como se ilustra en la Figura 2.
La solución pasa por reforzar la separación de responsabilidades y respetar una arquitectura clara por capas:
- El acceso a datos debe permanecer exclusivamente en el DAO. Su responsabilidad debe limitarse a interactuar con la base de datos o la fuente de persistencia, sin contener lógica de negocio ni depender de otras capas superiores.
- La lógica de negocio debe residir en el manager o servicio. Esta capa es la encargada de orquestar las operaciones, aplicar reglas de negocio y decidir qué datos se necesitan y cuándo.
- Cualquier clase que necesite acceder a datos debe hacerlo siempre a través del manager o servicio, y nunca directamente mediante el DAO. De este modo, el flujo de dependencias se mantiene unidireccional y coherente con la arquitectura definida.
Aplicando estas reglas, se logra eliminar gran parte de los ciclos de dependencias indirectos, se reduce el acoplamiento entre componentes y se mejora notablemente la mantenibilidad, los testeos y la claridad del sistema. Además, el diseño resultante suele ser más flexible frente a cambios futuros y más sencillo de comprender para nuevos desarrolladores. La Figura 3 muestra una posible reorganización del código siguiendo este enfoque.
A diferencia de otras alternativas que simplemente permiten retrasar o evitar la resolución del ciclo durante el arranque, este enfoque elimina la causa raíz del problema y suele producir diseños más mantenibles y fáciles de evolucionar.
8.2.2 Uso de @Lazy
@Lazy permite retrasar la creación del bean hasta el momento en que realmente se necesita.
Es útil cuando una de las dos dependencias no es necesaria durante la construcción inicial.
@Component
class A {
@Autowired
@Lazy
private B b;
}
Código 5
En el Código 5, se muestra un ejemplo de uso de la anotación @Lazy para una de las propiedades de la clase. Esta solución es adecuada cuando la dependencia es real pero no inmediata.
No resuelve ciclos complejos, pero sí ciclos simples A ↔ B.
8.2.3 @PostConstruct y setter injection
Esta solución persigue el mismo objetivo que el uso de @Lazy descrito en el punto anterior: retrasar la resolución completa de una dependencia para evitar que Spring tenga que crear dos beans mutuamente dependientes durante el arranque. La diferencia es que, en este caso, la relación se completa de forma explícita una vez que el contexto ya ha inicializado los componentes principales.
Para ello, puede utilizarse un setter junto con @PostConstruct. De esta forma, la dependencia ya no se resuelve durante la construcción inicial del bean, sino en una fase posterior del ciclo de vida. En el Código 6 se muestra un ejemplo de este enfoque.
@Component
class A {
@Autowired
private B b;
@PostConstruct
public void init() {
b.setA(this);
}
}
@Component
class B {
private A a;
public void setA(A a) {
this.a = a;
}
}
Código 6
8.2.4 Métodos estáticos
A veces la dependencia solo existe porque un método utilitario está dentro de una clase gestionada por Spring.
En estos casos, convertir ese método en static elimina la necesidad de inyección, como se aprecia en el siguiente ejemplo, en el Código 7.
@Component
public class LoggerUtil {
//Before
public void log(String message) {
System.out.println("[LOG] " + message);
}
//After
public static void log(String message) {
System.out.println("[LOG] " + message);
}
}
Código 7
No debe usarse para ocultar una dependencia real entre componentes, sino únicamente cuando se trata de una función pura sin estado ni dependencia del contexto de Spring. Por lo tanto, su uso debe limitarse a casos concretos:
✔ válido si el método no necesita estado
✘ inválido si el método depende del contexto o de anotaciones de Spring
8.2.5 Obtener el bean manualmente con ApplicationContext
Obtener un bean manualmente del ApplicationContext consiste en solicitar explícitamente a Spring una dependencia, en lugar de recibirla mediante inyección. Es decir, la propia clase accede al contexto y llama a getBean() para recuperar la dependencia que necesita.
En el Código 8 se muestra un ejemplo en el que la clase A obtiene manualmente el bean B desde el ApplicationContext cuando lo necesita.
No obstante, hay que tener en cuenta que esta solución rompe el principio de inyección de dependencias, ya que la clase deja de recibir sus dependencias de forma explícita y controlada, y pasa a obtenerlas por su cuenta. Esto va en contra de los principios de diseño orientado a objetos, dificultando la comprensión y el mantenimiento del código.
Además, acopla fuertemente la clase al contexto de Spring. La clase ya no es independiente ni reutilizable en otros contextos sin dicho contexto, lo que limita su portabilidad y aumenta la dependencia de la infraestructura concreta utilizada en el proyecto.
Otro efecto negativo es que dificulta significativamente la escritura de pruebas unitarias. Al no poder sustituir fácilmente las dependencias por dobles de prueba (mocks o stubs), las pruebas se vuelven más complejas, frágiles o directamente inviables, reduciendo la calidad y la fiabilidad del proceso de testing.
@Component
class A {
private B b;
@Autowired
private ApplicationContext context;
public B getB() {
if (b == null) {
b = context.getBean(B.class);
}
return b;
}
}
Código 8
Por todo ello, esta práctica debe considerarse generalmente un anti‑patrón dentro del desarrollo de software. Aunque puede resultar funcional y resolver un problema inmediato, sacrifica principios de diseño y mantenibilidad a cambio de una solución rápida.
En consecuencia, su utilización debe limitarse a situaciones excepcionales, en las que no exista una alternativa razonable sin acometer una reestructuración significativa del módulo o del diseño existente. En tales casos, su uso deberá documentarse de forma explícita y considerarse estrictamente como una solución temporal.
9. Interfaz REST
La migración también supone cambios en las interfaces REST que se tengan definidas en la aplicación. En general, se trata de cambios de nomenclatura o de anotaciones usadas y no resultan muy complejos, deben considerarse para evitar la necesidad de introducir modificaciones en el funcionamiento de la interfaz de manera no intencionada afectando a quién la consuma.
9.1 Cambio de anotaciones
En aquellos proyectos que exponen servicios REST mediante Apache CXF o tecnologías basadas en JAX-RS, la migración a Spring Boot 3 suele implicar también la adopción del modelo de controladores de Spring MVC. Aunque la funcionalidad ofrecida por la interfaz puede mantenerse sin cambios, es necesario adaptar anotaciones, parámetros y mecanismos de configuración asociados a los servicios REST.
@Path("/documents")
@POST
@Consumes("application/json")
@Produces("application/json")
Código 9
Antes era necesario usar varias anotaciones distintas, como se aprecia en el Código 9, mientras que ahora es suficiente con una sola, resultando en ahorro de líneas y una interfaz más clara y limpia, como se puede observar en el Código 10.
@PostMapping(value = "/documents", consumes = "application/json", produces = "application/json")Código 10
En algunos entornos legacy, la validación del tipo de contenido podía ser más permisiva. Tras la migración, Spring MVC puede aplicar de forma más estricta el valor declarado en consumes, por lo que los clientes deben enviar correctamente el header Content-Type, o de lo contrario es probable que se presenten inconvenientes al realizar una solicitud. Como medida temporal, mientras los usuarios de la interfaz revisan sus llamadas a fin de adaptar el tipo de contenido, se podrá utilizar el carácter “*” en el atributo “consumes”, permitiendo la aceptación de cualquier tipo de contenido.
Los parámetros también han tenido cambios, de modo que la anotación @QueryParam ahora es @RequestParam, la anotación @PathParam ahora pasa a ser @PathVariable y en las llamadas POST, se debe definir el parámetro que viene en el cuerpo con la anotación @RequestBody. En el Código 11 se ejemplifica cómo quedaría una petición tras realizar todos estos cambios mencionados.
@PostMapping(value = "/request", produces = "application/json", consumes = "application/json")
public ResponseEntity<Object> request(@RequestParam(value="param") String param, @RequestBody Object body){
//implementation
} Código 11
9.2 Parámetros REST
En la migración a Spring Boot 3 y Jakarta, el uso de DataHandler en interfaces REST deja de ser una opción natural dentro del modelo de controladores Spring MVC. En su lugar, resulta más adecuado trabajar con byte[], Resource o MultipartFile, según el tipo de operación. Es importante tener en cuenta que, en producción, MultipartFile solo está pensado para ser generado por Spring al procesar la petición. Sus implementaciones son internas, por lo que no podemos crear instancias manualmente a menos que implementemos nosotros la interfaz. Esto significa que MultipartFile es útil como parámetro de entrada en un controlador, pero no como objeto que podamos manipular o construir de forma programática en la aplicación.
10. Buenas prácticas
Una migración exitosa no termina cuando el proyecto compila. Es necesario realizar una verificación exhaustiva y un control continuo para asegurar que el comportamiento de la aplicación se mantiene estable. Resulta útil preparar una checklist previa a la migración y mantenerla actualizada conforme avanza el trabajo. Esta lista debería recoger pruebas funcionales, unitarias, de integración, rendimiento y seguridad, de forma que cualquier cambio involuntario pueda detectarse de inmediato y evitar regresiones.
A medida que el proceso avanza, es importante documentar tanto las decisiones técnicas como los obstáculos encontrados y su solución. Esta documentación no solo sirve durante la propia migración: también actúa como base de conocimiento para futuras actualizaciones y como referencia para nuevos miembros del equipo.
En paralelo, conviene mantener un control cuidadoso del repositorio, realizando commits pequeños y con granularidad fina que permitan identificar con claridad cada paso realizado. También es recomendable registrar explícitamente los commits relevantes —ya sea por un cambio de diseño, una actualización delicada o una decisión estructural— ya que facilita en gran medida la trazabilidad y simplifica posibles rollbacks si aparece un problema.
Una vez completada la migración, es recomendable planificar actualizaciones periódicas, evitando que el proyecto vuelva a quedar anclado en versiones obsoletas. Adoptar un ritmo de mantenimiento continuo permite reducir el esfuerzo de las futuras migraciones y mantener el ecosistema de dependencias en un estado saludable. Por último, para que todo este proceso resulte sostenible, es fundamental que el equipo disponga del tiempo y la formación adecuados.
Las migraciones de esta magnitud requieren que los desarrolladores se adapten a nuevas herramientas, nuevas APIs y nuevas prácticas; imponer urgencias artificiales suele traducirse en errores, sobrecostes y un aprendizaje incompleto. Dar margen suficiente al equipo es parte esencial del éxito de la transición.
11. Conclusión
Migrar a Spring Boot 3 y Java 21 además de actualizar versiones o seguir una tendencia tecnológica, supone un paso importante hacia una forma más moderna, eficiente y sostenible de desarrollar aplicaciones. Esta transición permite dejar atrás limitaciones propias de entornos más antiguos y adoptar un ecosistema mejor preparado para las necesidades actuales y futuras.
Gracias a las mejoras incorporadas en Java 21, las aplicaciones pueden aprovechar mejor los recursos, ser más rápidas y manejar la concurrencia de forma más eficiente. Por su parte, Spring Boot 3 simplifica muchas tareas que antes requerían configuraciones complejas, facilitando el desarrollo, el despliegue y el mantenimiento del software. El uso de JARs ejecutables con servidores embebidos, junto con la integración natural con contenedores, hace que las aplicaciones sean más fáciles de desplegar y de escalar, especialmente en entornos cloud.
Otro aspecto clave es la mejora en la calidad y claridad del código. La migración obliga a revisar dependencias, corregir diseños heredados y adoptar buenas prácticas más actuales. Aunque esto pueda suponer un esfuerzo inicial, el resultado es una base de código más limpia, comprensible y fácil de mantener, lo que beneficia tanto a los desarrolladores actuales como a quienes se incorporen al proyecto en el futuro.
Además, Spring Boot 3 y Java 21 ofrecen mejores herramientas para la observabilidad y la seguridad, dos factores fundamentales en aplicaciones empresariales. Contar con métricas, trazas y configuraciones de seguridad más robustas permite detectar problemas antes, reaccionar con mayor rapidez y operar los sistemas con mayor confianza. En conjunto, esta migración debe entenderse como una inversión a largo plazo. No solo moderniza la tecnología, sino que también ayuda al equipo a adquirir nuevos conocimientos, adoptar estándares actuales y trabajar con herramientas más productivas. Con una planificación adecuada, pruebas suficientes y un ritmo razonable, el proceso se convierte en una oportunidad para mejorar la arquitectura, reducir deuda técnica y preparar las aplicaciones para crecer de forma segura y escalable en los próximos años.