Moving a production monolith or a fleet of microservices from Spring Boot 2.7 to 3.x is not a "bump the version and pray" task. I recently led a migration for a fintech platform where we hit a wall with legacy dependencies still clinging to the javax.* namespace. The jump to Java 17 is the easy part; the real friction lies in the absolute transition to Jakarta EE 9/10, which breaks every servlet filter, validation logic, and persistence mapping you’ve written in the last decade.
📋 Tested Environment: Spring Boot 3.2.4 on OpenJDK 17 (Eclipse Temurin)
Key Discovery: Many third-party libraries (like older QueryDSL or Swagger 2) lack Jakarta-compatible branches. You must replace springfox-boot-starter with springdoc-openapi-starter-webmvc-ui immediately to avoid internal ClassNotFoundException errors during context startup.
The Javax to Jakarta Namespace Pivot
The most jarring change is the migration from javax.servlet to jakarta.servlet. During our migration, our build passed, but the application failed at runtime with a NoClassDefFoundError: javax/servlet/Filter. This happened because while we updated our source code, a transitive dependency—an old version of a custom logging filter—was still looking for the javax namespace. You cannot mix these namespaces in a single ClassLoader environment without serious shading hacks.
I found that using the OpenRewrite recipes significantly reduced the manual labor. However, do not trust it blindly. It often misses XML-based configurations or specialized persistence files like orm.xml. We had to manually audit our validation-api usages. In Spring Boot 3, Hibernate 6 is the default, which strictly enforces Jakarta Persistence 3.1. This means your @Entity classes must use jakarta.persistence.Entity. If you forget even one, Hibernate will simply ignore the class, leading to "Table not found" errors that are notoriously hard to debug.
Beyond the imports, check your pom.xml or build.gradle for hardcoded versions. We noticed that some developers had pinned hibernate-core to version 5.x to solve a specific bug in the past. This pinning will break the Spring Boot 3 autoconfiguration entirely. Always prefer the Spring Boot Parent BOM to manage these versions unless you have a specific, documented reason to override them.
Fixing Broken Security Configurations
If you are still using WebSecurityConfigurerAdapter, your code won't even compile. Spring Security 6.0 (bundled with Boot 3) removed this class entirely. I had to refactor our entire security layer to a component-based model using the SecurityFilterChain bean. This isn't just a syntax change; it changes how the filter chain is constructed and prioritized.
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.authorizeHttpRequests(auth -> auth
// Use requestMatchers instead of antMatchers
.requestMatchers("/api/public/**").permitAll()
.anyRequest().authenticated()
)
// New lambda-based configuration is mandatory
.csrf(csrf -> csrf.disable())
.httpBasic(Customizer.withDefaults());
return http.build();
}Notice the change from antMatchers to requestMatchers. This is a subtle but critical shift. requestMatchers is more secure because it integrates directly with Spring MVC's introspection, preventing path traversal vulnerabilities that were common when antMatchers and mvcMatchers were used inconsistently. For a deeper dive into modern security patterns, see our guide on implementing OAuth2 in Spring Boot 3. Also, verify your official Spring Security migration docs for specific edge cases involving method security.
Leveraging Java 17 and 21 Features
Spring Boot 3 requires Java 17 as a baseline, but I recommend jumping straight to Java 21 if your infrastructure allows it. The performance gains in the JVM and the availability of Virtual Threads (Project Loom) in Spring Boot 3.2+ are game-changers for high-concurrency applications. During our migration, we replaced dozens of "Boilerplate" DTOs with Java Records. This reduced our codebase size by roughly 15% and improved readability.
We encountered an issue with Constructor Binding in @ConfigurationProperties. In Spring Boot 2.x, you often needed @ConstructorBinding on the class or constructor. In Boot 3, if the class is a Record and has a single constructor, the annotation is no longer required. This makes your configuration classes much cleaner. However, be careful with @NestedConfigurationProperty; we found that some nested structures stopped binding correctly if the inner classes weren't explicitly initialized.
Another metric we tracked was the startup time. While Java 17 is faster, the initialization of Hibernate 6 and the new AOT (Ahead-of-Time) processing capabilities in Spring Framework 6 actually added a few seconds to our local dev cycles. If you are deploying to Kubernetes, you should explore GraalVM Native Image support, which is now a first-class citizen in Boot 3. We managed to drop our container memory footprint from 800MB to 120MB by compiling to native binaries, though it doubled our CI/CD build time.
Frequently Asked Questions
Q. Can I still use Java 11 with Spring Boot 3?
A. No. Spring Boot 3 has a hard requirement for Java 17+. Attempting to run it on Java 11 will result in a java.lang.UnsupportedClassVersionError. This is due to the framework being compiled with the Java 17 class file format (version 61).
Q. My Swagger/OpenAPI UI stopped working after the upgrade, why?
A. Springfox is effectively dead and does not support Jakarta EE. You must migrate to springdoc-openapi-starter-webmvc-ui. Ensure you use the "starter" dependency which includes the necessary Jakarta-compatible swagger-ui components.
Q. How do I handle 'javax' dependencies that haven't been updated?
A. You can use the Eclipse Transformer tool to byte-code transform old JARs from the javax to jakarta namespace at build time. However, it is safer to find alternative libraries or check for 'jakarta' classified versions of the existing ones (e.g., querydsl-jpa:jakarta).
The migration to Spring Boot 3 is more than a version bump; it is a fundamental shift in the Java ecosystem. By addressing the Jakarta namespace early and auditing your security filters, you can avoid the most common pitfalls. If you're interested in further optimizing your new stack, check out our article on tuning Virtual Threads for Spring Boot 3.2.
Post a Comment