从 Spring Boot 3+Java 21 到 Spring Boot 4+Java 25：迁移全指南

Ne0inhk

23 Mar 2026 — 9 min read

随着 Spring Boot 4 正式发布（基于 Spring Framework 6.2）和 Java 25 LTS 的落地，不少团队开始规划升级路线。从 Spring Boot 3+Java 21 迁移到新组合，既要适配框架的新特性，也要利用 Java 25 的性能红利，同时避开兼容性陷阱。本文整理了核心注意要点，帮你平稳过渡～

一、📋迁移前必做：环境与依赖自查

1. 基础环境适配

Java 版本门槛：Spring Boot 4 要求最低 Java 25（不再支持 Java 21 及以下），需先升级 JDK 至 25（推荐 Oracle JDK 25 或 OpenJDK 25）。✅ 检查：java -version 确认版本≥25.0，同时确保 IDE（IntelliJ 2025.3+/Eclipse 2025-12+）已支持 Java 25 语法。
构建工具升级：
- Maven 需≥3.9.6（旧版本可能无法解析 Java 25 字节码）；
- Gradle 需≥8.8（建议用gradle wrapper --gradle-version 8.8升级包装器）。

2. 核心依赖版本锁定

Spring Boot 4 对第三方依赖做了大幅升级，需重点关注：

依赖	Spring Boot 3 版本	Spring Boot 4 版本	注意点
Spring Framework	6.0.x/6.1.x	6.2.x	移除大量`@Deprecated` API，如`WebMvcConfigurerAdapter`
Spring Security	6.1.x/6.2.x	6.3.x	OAuth2 客户端配置类重构，`ClientRegistration`参数调整
Hibernate	6.1.x	6.5.x	强制要求 JPA 3.2 规范，旧版实体类注解需微调
Jackson	2.15.x	2.17.x	对 Java 25 记录类（Record）的序列化逻辑优化

💡 建议：用spring-boot-dependencies管理版本，避免手动指定依赖版本导致冲突。

二、🔨代码适配：从框架到 Java 语法的调整

1. Spring Boot 4 的「破坏性变更」

Web 层调整：
- Spring MVC 中@RequestMapping的params属性不再支持通配符*，需用hasText()等表达式替代；
- WebFlux 移除WebFilter的@Order注解支持，需通过Ordered接口指定顺序。
配置文件变化：
- server.tomcat.max-threads被标记为过时，推荐用server.tomcat.threads.max替代；
- 数据库连接池默认从 HikariCP 5.x 升级到 6.x，spring.datasource.hikari.connection-timeout单位从毫秒改为秒（需注意数值调整）。

自动配置简化：移除spring-boot-starter-json中默认依赖的jackson-datatype-joda（Joda 时间库已过时），需手动添加依赖或迁移到 Java 8 + 时间 API（java.time）。

<!-- 如需保留Joda支持，手动引入 --> <dependency> <groupId>com.fasterxml.jackson.datatype</groupId> <artifactId>jackson-datatype-joda</artifactId> </dependency>

2. Java 25 特性适配与利用

升级到 Java 25 后，不仅要兼容语法，更要学会用新特性优化代码：

模式匹配增强（JEP 463）优化分支逻辑处理 Spring 的ResponseEntity时更简洁：

// 旧代码 if (responseEntity.getStatusCode().is2xxSuccessful()) { User user = responseEntity.getBody(); if (user != null) { // 处理用户 } } // Java 25新写法 if (responseEntity instanceof ResponseEntity<User>(User user) && responseEntity.getStatusCode().is2xxSuccessful()) { // 直接使用user（自动判空+类型匹配） }

字符串模板（String Templates）简化动态内容替代String.format()和 "+" 拼接，在日志、SQL 构建中更安全：

// 日志输出 String userId = "u123"; log.info(STR."用户\{userId}登录成功，IP：\{request.getRemoteAddr()}"); // JPA查询（配合Spring Data JPA） @Query(STR."SELECT u FROM User u WHERE u.name = \{name} AND u.status = 'ACTIVE'") List<User> findActiveUsers(String name);

虚拟线程（Virtual Threads）替代传统线程池Spring Boot 4 默认对@Async方法支持虚拟线程，可通过配置全局启用：

# application.properties spring.task.execution.thread-name-prefix=app-async- spring.task.execution.virtual-threads.enabled=true # 启用虚拟线程

旧代码中手动创建的线程池（如Executors.newFixedThreadPool()）可替换为：

// 替换前 ExecutorService executor = Executors.newFixedThreadPool(10); // 替换后（Java 25推荐） ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();

三、⚙️进阶优化：利用新特性提升性能

1. 基于 Java 25 的内存优化

紧凑对象头（JEP 519）：默认启用，无需代码修改，对象内存占用减少 5~15%，对缓存密集型应用（如商品详情页缓存）收益明显。

AOT 预热加速（JEP 514）：结合 Spring Boot 4 的 AOT 支持，生成预编译镜像：

# 构建AOT优化的应用 ./mvnw spring-boot:process-aot package # 启动时加载预热数据 java -XX:UseProfilingDataFile=profile.jfr -jar app.jar

效果：容器启动时间缩短 40%+，适合 K8s 环境快速扩缩容。

2. Spring Boot 4 的新特性应用

原生镜像（Native Image）支持增强：通过spring-boot-starter-native可将应用编译为原生可执行文件，启动时间从秒级降至毫秒级（需 GraalVM 25 + 支持）。

配置绑定简化：支持@ConfigurationProperties直接绑定 Java 25 的密封类（Sealed Classes）：

sealed interface AppConfig permits DbConfig, RedisConfig {} record DbConfig(String url, String username) implements AppConfig {} @ConfigurationProperties(prefix = "app") public AppConfig appConfig() { ... }

四、🧪测试与验证：避坑关键步骤

兼容性测试：
- 重点测试第三方库：如 MyBatis 需升级至 3.5.14+，Elasticsearch 客户端需≥8.14.0（否则可能出现 Java 25 字节码不兼容）。
性能基准测试：对比迁移前后的关键指标（用 JMH 或 Spring Boot Actuator）：
- 接口响应时间（尤其并发场景，虚拟线程应带来明显提升）；
- 内存占用（Heap 使用量应下降）；
- GC 停顿时间（默认的 Shenandoah GC 在 Java 25 中更优）。
安全合规检查：Java 25 强化了加密算法支持（如 SHA-3 增强），需确认应用中使用的加密方式（如 JWT 签名）是否适配，避免因算法废弃导致功能失效。

用jdeprscan工具扫描旧代码中使用的过时 API：

jdeprscan --class-path target/classes com.yourpackage

五、📌迁移 Checklist（可直接复用）

升级 JDK 至 25 并验证 IDE 支持
替换spring-boot-starter-parent版本为 4.x
检查并升级第三方依赖至 Spring Boot 4 兼容版本
移除代码中使用的 Spring Framework 6.2 + 废弃 API
用虚拟线程替换手动线程池配置
测试字符串模板在日志、SQL 中的使用是否正常
运行jdeprscan和jlink检查依赖合规性
执行全量自动化测试 + 性能基准测试

六、🚗版本依赖对照表

以下是 Spring Boot 3（基于 Java 21）与 Spring Boot 4（基于 Java 25）的核心依赖版本对照表，涵盖常用框架、驱动及工具类，附带迁移注意点：

依赖类型	组件名称	Spring Boot 3 对应版本	Spring Boot 4 对应版本	迁移注意点 ⚠️
核心框架	Spring Framework	6.0.x ~ 6.1.x	6.2.x	移除`WebMvcConfigurerAdapter`等废弃类，`@RequestMapping`参数规则调整
	Spring Security	6.1.x ~ 6.2.x	6.3.x	OAuth2 客户端配置类重构，`ClientRegistration`部分参数名变更
数据访问	Spring Data JPA	3.1.x ~ 3.2.x	3.3.x	强制依赖 JPA 3.2 规范，实体类`@GeneratedValue`策略默认值调整
	Hibernate Core	6.1.x	6.5.x	旧版`@Formula`表达式语法不兼容，需改用 JPQL 标准写法
	MySQL Connector	8.0.33 ~ 8.1.0	8.2.0	移除对`useSSL=false`的默认支持，需显式配置`sslMode=DISABLE`关闭 SSL
	PostgreSQL Driver	42.5.x	42.7.x	对 Java 25 的`Record`类型映射优化，需更新实体类中相关字段注解
JSON 处理	Jackson Databind	2.15.x	2.17.x	默认禁用`@JsonIgnoreProperties(ignoreUnknown=true)`，需显式开启
	Gson	2.10.1	2.11.0	支持 Java 25 字符串模板的序列化，旧版自定义`TypeAdapter`需适配新 API
缓存与消息	Spring Cache	6.1.x	6.2.x	`@Cacheable`的`keyGenerator`默认实现变更，自定义生成器需重新测试
	Redis Client (Lettuce)	6.3.x	6.5.x	支持虚拟线程的异步连接池，需调整`spring.redis.lettuce.pool`配置参数
	RabbitMQ Client	5.18.x	5.20.x	移除`ChannelAwareMessageListener`的过时方法，需改用`MessageListener`
Web 相关	Spring WebFlux	6.1.x	6.2.x	`WebFilter`的`@Order`注解失效，需通过`Ordered`接口指定执行顺序
	Thymeleaf	3.1.2.RELEASE	3.2.0.RELEASE	模板引擎默认开启严格模式，`th:text`空值处理逻辑变更
工具与测试	Lombok	1.18.26	1.18.30	需配合 Java 25 的`--enable-preview`编译，否则`record`类注解可能失效
	JUnit 5	5.9.x	5.10.x	`@ParameterizedTest`的参数解析器优化，旧版自定义参数需适配
	Mockito	4.11.x	5.8.x	对 Java 25 虚拟线程的模拟支持增强，需更新`@Mock`的初始化方式
构建工具	Maven Compiler Plugin	3.11.x	3.12.x	需指定`release=25`，否则无法编译 Java 25 语法
	Gradle Plugin	7.6.x	8.8.x	需启用`java.toolchain.languageVersion = JavaLanguageVersion.of(25)`

使用说明：

迁移时建议通过spring-boot-dependencies统一管理版本，避免手动指定导致冲突；
标红注意点需优先测试（如 MySQL SSL 配置、Hibernate 表达式语法）；
第三方工具（如 Swagger、XXL-Job）需确认其最新版本是否兼容 Spring Boot 4+Java 25（通常需升级至 2025 年 Q3 后的发布版）。

总结

从 Spring Boot 3+Java 21 到 4+Java 25 的迁移，核心是「适配变更 + 拥抱新特性」。框架层面需关注依赖升级和配置调整，Java 层面则可通过虚拟线程、字符串模板等特性提升性能与开发效率。建议分阶段推进：先在非核心服务验证，再逐步迁移核心系统，借助工具链降低风险。

👉 公众号「软件开发大百科」🌟 | ZEEKLOG传送门：https://zhengkai.blog.ZEEKLOG.net/