从SpringBoot3+Java21到SpringBoot4+Java25迁移全指南与注意事项

随着 Spring Boot 4 正式发布（基于 Spring Framework 6.2）和 Ja va 25 LTS 的落地，不少团队已经开始规划升级路线。从 Spring Boot 3 + Ja va 21 迁移到新组合，既要适配框架的新特性，也要利用 Ja va 25 的性能红利，还得时刻留意那些容易踩坑的兼容性问题。这篇文章整理了核心的注意要点，希望能为你提供一些实用的参考。 ## 一、迁移前必做：环境与依赖自查 ### 1. 基础环境适配 Spring Boot 4 对 Ja va 版本的门槛很明确——最低要求 Ja va 25，不再支持 Ja va 21 及以下版本。所以第一步，得先把 JDK 升级到 25，推荐使用 Oracle JDK 25 或 OpenJDK 25。可以用 `ja va -version` 确认版本是否 ≥25.0，同时确保 IDE（IntelliJ 2025.3+ 或 Eclipse 2025-12+）已经支持 Ja va 25 语法。 构建工具也得跟着升级： - Ma ven 需要 ≥3.9.6，旧版本可能无法解析 Ja va 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 | 对 Ja va 25 记录类（Record）的序列化逻辑优化 | 推荐的做法是：用 `spring-boot-dependencies` 统一管理版本，避免手动指定依赖版本导致冲突。 ## 二、代码适配：从框架到 Ja va 语法的调整 ### 1. Spring Boot 4 的“破坏性变更” **自动配置简化**：`spring-boot-starter-json` 中默认依赖的 `jackson-datatype-joda` 被移除（Joda 时间库已过时），需要手动添加依赖，或者迁移到 Ja va 8+ 时间 API（`ja va.time`）。 ```plain com.fasterxml.jackson.datatype jackson-datatype-joda ``` **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` 的单位从毫秒改为秒，数值需要相应调整。 ### 2. Ja va 25 特性适配与利用 升级到 Ja va 25 后，不只是要兼容语法，更重要的是学会用新特性来优化代码。 **虚拟线程（Virtual Threads）替代传统线程池** Spring Boot 4 默认对 `@Async` 方法支持虚拟线程，可以通过配置全局启用： ```ja va # application.properties spring.task.execution.thread-name-prefix=app-async- spring.task.execution.virtual-threads.enabled=true # 启用虚拟线程 ``` 旧代码中手动创建的线程池（如 `Executors.newFixedThreadPool()`）可以替换为： ```ja va // 替换前 ExecutorService executor = Executors.newFixedThreadPool(10); // 替换后（Ja va 25推荐） ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor(); ``` **字符串模板（String Templates）简化动态内容** 替代 `String.format()` 和“+”拼接，在日志、SQL 构建中更安全： ```ja va // 日志输出 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 findActiveUsers(String name); ``` **模式匹配增强（JEP 463）优化分支逻辑** 处理 Spring 的 `ResponseEntity` 时可以更简洁： ```ja va // 旧代码 if (responseEntity.getStatusCode().is2xxSuccessful()) { User user = responseEntity.getBody(); if (user != null) { // 处理用户 } } // Ja va 25新写法 if (responseEntity instanceof ResponseEntity(User user) && responseEntity.getStatusCode().is2xxSuccessful()) { // 直接使用user（自动判空+类型匹配） } ``` ## 三、进阶优化：利用新特性提升性能 ### 1. 基于 Ja va 25 的内存优化 **紧凑对象头（JEP 519）**：默认启用，无需修改代码，对象内存占用减少 5~15%，对缓存密集型应用（如商品详情页缓存）收益明显。 **AOT 预热加速（JEP 514）**：结合 Spring Boot 4 的 AOT 支持，可以生成预编译镜像： ```ja va # 构建AOT优化的应用 ./mvnw spring-boot:process-aot package # 启动时加载预热数据 ja va -XX:UseProfilingDataFile=profile.jfr -jar app.jar ``` 效果：容器启动时间缩短 40%+，适合 K8s 环境快速扩缩容。 ### 2. Spring Boot 4 的新特性应用 **原生镜像（Native Image）支持增强**：通过 `spring-boot-starter-native` 可以将应用编译为原生可执行文件，启动时间从秒级降至毫秒级（需要 GraalVM 25 支持）。 **配置绑定简化**：支持 `@ConfigurationProperties` 直接绑定 Ja va 25 的密封类（Sealed Classes）： ```ja va sealed interface AppConfig permits DbConfig, RedisConfig {} record DbConfig(String url, String username) implements AppConfig {} @ConfigurationProperties(prefix = "app") public AppConfig appConfig() { ... } ``` ## 四、测试与验证：避坑关键步骤 **兼容性测试**： - 用 `jdeprscan` 工具扫描旧代码中使用的过时 API： ```ja va jdeprscan --class-path target/classes com.yourpackage ``` - 重点测试第三方库：如 MyBatis 需升级至 3.5.14+，Elasticsearch 客户端需 ≥8.14.0（否则可能出现 Ja va 25 字节码不兼容）。 **性能基准测试**：对比迁移前后的关键指标（用 JMH 或 Spring Boot Actuator）： - 接口响应时间（尤其并发场景，虚拟线程应该带来明显提升）； - 内存占用（Heap 使用量应该下降）； - GC 停顿时间（默认的 Shenandoah GC 在 Ja va 25 中表现更优）。 **安全合规检查**：Ja va 25 强化了加密算法支持（如 SHA-3 增强），需要确认应用中使用的加密方式（如 JWT 签名）是否适配，避免因算法废弃导致功能失效。 ## 五、迁移 Checklist（可直接复用） - 升级 JDK 至 25 并验证 IDE 支持 - 替换 `spring-boot-starter-parent` 版本为 4.x - 检查并升级第三方依赖至 Spring Boot 4 兼容版本 - 移除代码中使用的 Spring Framework 6.2+ 废弃 API - 用虚拟线程替换手动线程池配置 - 测试字符串模板在日志、SQL 中的使用是否正常 - 运行 `jdeprscan` 和 `jlink` 检查依赖合规性 - 执行全量自动化测试 + 性能基准测试 ## 六、版本依赖对照表 以下是 Spring Boot 3（基于 Ja va 21）与 Spring Boot 4（基于 Ja va 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 | 对 Ja va 25 的 `Record` 类型映射优化，需更新实体类中相关字段注解 | | **JSON 处理** | Jackson Databind | 2.15.x | 2.17.x | 默认禁用 `@JsonIgnoreProperties(ignoreUnknown=true)`，需显式开启 | | | Gson | 2.10.1 | 2.11.0 | 支持 Ja va 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 | 需配合 Ja va 25 的 `--enable-preview` 编译，否则 `record` 类注解可能失效 | | | JUnit 5 | 5.9.x | 5.10.x | `@ParameterizedTest` 的参数解析器优化，旧版自定义参数需适配 | | | Mockito | 4.11.x | 5.8.x | 对 Ja va 25 虚拟线程的模拟支持增强，需更新 `@Mock` 的初始化方式 | | **构建工具** | Ma ven Compiler Plugin | 3.11.x | 3.12.x | 需指定 `release=25`，否则无法编译 Ja va 25 语法 | | | Gradle Plugin | 7.6.x | 8.8.x | 需启用 `ja va.toolchain.languageVersion = Ja vaLanguageVersion.of(25)` | 使用说明： 1. 迁移时建议通过 `spring-boot-dependencies` 统一管理版本，避免手动指定导致冲突； 2. 注意点中标记的内容需优先测试（如 MySQL SSL 配置、Hibernate 表达式语法）； 3. 第三方工具（如 Swagger、XXL-Job）需确认其最新版本是否兼容 Spring Boot 4+Ja va 25（通常需升级至 2025 年 Q3 后的发布版）。 ## 总结 从 Spring Boot 3+Ja va 21 到 4+Ja va 25 的迁移，核心在于“适配变更 + 拥抱新特性”。框架层面需要关注依赖升级和配置调整，Ja va 层面则可以通过虚拟线程、字符串模板等特性来提升性能与开发效率。建议分阶段推进：先在非核心服务上验证，再逐步迁移核心系统，借助工具链降低风险。