How to Seamlessly Migrate to Spring Boot 3.0 and Java 17

Spring Boot entered the 2.0 era on February 28, 2018; Spring Boot 3.0 will be officially released in November 2022, based on Spring Framework 6.0, requiring Java 17 or higher and Jakarta EE 9, giving developers six months to transition.

Java 17

Java 17 is the most important LTS version since Java 8, offering many improvements and the best performance among LTS releases. All Spring Boot 2.x versions support Java 17, allowing immediate upgrade and experimentation with new features and APIs.

Upgrade to Spring Boot 2.7 first

Spring Boot 2.7 is the last major 2.x release. Spring Boot 2.5 has ended OSS support, and 2.6 will stop being maintained after Spring Boot 3.0 is released. Upgrade to 2.7 gradually (2.4 → 2.5 → 2.6 → 2.7) to ensure a smooth migration to 3.0.

Remove deprecated code

Each Spring Boot version marks some APIs with @Deprecated. Spring Boot 3.0 will completely remove deprecated code from 2.x, so avoid using it and replace it with the suggested alternatives.

Configuration file mechanism changes

In Spring Boot 2.4 the loading mechanism for application.properties and application.yaml changed, breaking backward compatibility. A legacy processing flag can be enabled:

spring:
  config:
    use-legacy-processing: true

This flag will be removed in 3.0, so adopt the new configuration style.

Multi‑document YAML

When using the --- separator in YAML, the order of documents determines property registration from 2.4 onward, unlike earlier versions that relied on spring.profiles.active.

---
spring:
  profiles:
    active: dev
  application:
    name: dev-app
server:
  port: 8081
---
spring:
  profiles:
    active: prod
  application:
    name: prod-app
server:
  port: 8080

From 2.4 onward, later properties override earlier ones.

External configuration always overrides JAR‑internal configuration

External application-dev.yaml files now always override the same‑profile files inside the JAR, a change introduced in 2.4.

Activating profiles

Replace the old spring.profiles property with spring.config.activate.on-profile. The legacy spring.profiles.active still works for command‑line activation but cannot be used inside application-<profile>.yaml or multi‑document YAML.

Old usage:

spring:
  profiles: "prod"
secret: "production-password"

New usage:

spring:
  config:
    activate:
      on-profile: "prod"
secret: "production-password"

Higher‑performance path parsing

Since Spring Boot 2.6 the default path parser is PathPatternParser instead of AntPathMatcher. Issues with Swagger can be fixed by setting spring.mvc.pathmatch.matching-strategy. Although AntPathMatcher remains functional in 3.0, PathPatternParser is recommended for better performance.

Compatibility issues

Ensure third‑party libraries and code are compatible with Jakarta EE 9 and that dependencies used by Spring Framework have plans to support Spring 6.

Try Spring 6

Spring 6 and Spring Boot 3 have reached several milestones; consider experimenting with them to evaluate upgrade difficulty.