How to Seamlessly Upgrade from Spring Boot 3 to 4 with AI Assistance

The author shares experience and insights on upgrading a Spring Boot 3.5.11 project to Spring Boot 4, emphasizing the new API Versioning feature and using AI to accelerate the migration.

Key Upgrades in Spring Boot 4

Baseline technology shift : Built on Spring Framework 7, requires Java 17+, and runs on Jakarta EE 11 and Servlet 6.1, meaning the upgrade touches runtime and dependency layers.

Modularized codebase : JARs become smaller and responsibilities more focused, affecting dependency composition and auto‑configuration, especially the large changes in Jackson packages.

API Versioning as a first‑class capability : Automatic configuration support for Spring MVC and WebFlux simplifies maintaining multiple API versions.

HTTP Service Clients support : Auto‑configuration for annotated Java interfaces generates client implementations, reducing manual remote‑call boilerplate.

Observability enhancements : New starter spring-boot-starter-opentelemetry exports metrics and traces and auto‑configures the OpenTelemetry SDK.

Testing and infrastructure improvements : Enhanced RestTestClient, JMS API, Redis observability, and task decorator combinations fill remaining engineering gaps.

Overall, Spring Boot 4 is a comprehensive infrastructure recalibration rather than a simple version bump.

Practical Migration Workflow

01 Define Upgrade Scope

Use an AI prompt to generate a complete migration plan that includes version bump, starter updates, package path changes, Jackson 3 adaptation, custom bean checks, foundation module compatibility, and a verification checklist.

我需要将一个现有项目从 Spring Boot 3.5.11 升级到 Spring Boot 4.0.5。请基于 Spring 官方最新文档，并结合当前项目的实际代码与配置，输出一份可执行的完整迁移升级计划，至少包含如下部分：
- 1. 升级 SpringBoot 主版本到 4.0.5
- 2. 切换到 SpringBoot 4 最新的 Starter 体系
- 3. 替换 SpringBoot 3 专用的的三方 Starter
- 4. 修复 SpringBoot 4 带来的包路径变化
- 5. 适配 Jackson 3、WebMVC、Security 等关键组件
- 6. 检查自定义 Spring Bean 配置
- 7. 基础 foundation 包中各种模块的 SpringBoot 4 兼容性检查（可选）
- 8. 输出升级后的验证清单，确认关键行为是否正常

The plan follows a clear sequence: determine scope → adjust dependencies and starters → handle JSON, web, and security layers → fill gaps in shared modules → verify critical behavior.

02 Validate Critical Paths

Check that automatic‑configuration registration files remain effective and that compileOnly/optional dependencies in shared modules are also upgraded to the Spring Boot 4 ecosystem. Verify core interface requests, parameter binding, authentication flows, scheduled tasks, caching, locks, and database transaction behavior.

03 Common Pitfalls

Pitfall 1 : Duplicate ObjectMapper beans cause NoUniqueBeanDefinitionException. Remove custom beans or adjust them with JsonMapperBuilderCustomizer.

Pitfall 2 : Manually registered MappingJackson2HttpMessageConverter should be removed because Spring Boot 4 creates the appropriate mapper automatically.

Pitfall 3 : Third‑party starter libraries must support Spring Boot 4; evaluate any breaking changes such as removed classes or new implementations.

04 Keep High Maintainability

Manage versions centrally with libs.versions.toml and reference them in build.gradle. Example snippets are illustrated in the images below.

Conclusion

The key takeaway from this upgrade is to treat it as a foundational infrastructure recalibration with a clear main line: confirm the upgrade scope, adjust dependencies and starters, handle JSON/web/security, fill shared modules, and finally verify critical behavior. Following this order makes the migration smooth and reliable.

Reference URLs: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Release-Notes https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide https://spring.io/blog/2025/11/20/spring-boot-4-0-0-available-now