Spring Boot 从 2.7.x 升级到 3.3注意事项

将 Spring Boot 从 2.7.x 升级到 3.3 是一个重要的迁移过程，特别是因为 Spring Boot 3.x 系列基于 Jakarta EE 9，而不再使用 Java EE。此版本升级伴随着许多重大变化，以下是你在升级过程中需要注意的关键事项：

1. JDK 版本升级

• 要求：Spring Boot 3.x 最低要求 JDK 17。如果你当前项目还在使用 JDK 8 或 JDK 11，首先需要升级到 JDK 17 或更高版本。
• 建议：在升级 Spring Boot 之前，先确保项目能够在 JDK 17 上正常运行。

2. Jakarta EE 迁移

• 变化：Spring Boot 3.x 转换到 Jakarta EE 9，所有 Java EE 包名从 javax.* 更改为 jakarta.*。
  • 例如：javax.servlet 变成了 jakarta.servlet。
• 解决方法：检查代码中是否直接依赖了 javax.* 包，如果有的话，必须修改为 jakarta.*。许多第三方库和框架（如 Hibernate、Tomcat、Jetty 等）也需要更新到兼容 Jakarta EE 版本。

3. Spring Framework 6 升级

• Spring Boot 3.x 是基于 Spring Framework 6 构建的，升级到 Spring Framework 6 会带来以下改动：
  • 移除的 API：一些已经废弃的 API 将被彻底移除。
  • 不再支持的框架：对一些老旧技术和库的支持被移除，如 JUnit 4、CGLIB、Rhino 等。
  • Reactive Changes：Spring WebFlux 的一些 API 已做调整。
• 解决方法：根据官方迁移指南，调整代码中使用到的 Spring API。

4. 依赖库的兼容性

• 第三方库升级：确保你项目中使用的所有第三方库都兼容 Spring Boot 3.x 和 Jakarta EE 9。如果你使用的库没有更新到支持 jakarta.* 包，可能需要找到替代方案或等待库更新。
• 建议：升级前使用 mvn dependency:tree 或 ./gradlew dependencies 来检查所有依赖项，并确认其兼容性。

5. Spring Security

• Spring Security 6：Spring Boot 3.x 使用 Spring Security 6，带来了诸多变化，尤其是在 OAuth2 和 JWT 的处理上有新的 API 改动。
• 变化示例：
  • 许多配置类和方法已经废弃或被重构，比如 WebSecurityConfigurerAdapter 已被弃用，推荐使用 SecurityFilterChain 来配置安全规则。
  • @EnableWebSecurity 需要与 SecurityConfigurerAdapter 一起配置，而不再是继承 WebSecurityConfigurerAdapter。

6. Hibernate 和 JPA

• Jakarta Persistence API：Spring Boot 3.x 使用的 Hibernate 版本已经迁移到 Jakarta Persistence API (jakarta.persistence)，这意味着你需要检查项目中所有 JPA 实体类的导入声明，确保它们指向正确的 Jakarta 包。
• 建议：使用自动化工具如 jdeps 或 jdeprscan 来检查代码中的依赖并进行迁移。

7. 日志框架

• Log4j 2.x 或 Logback 更新：Spring Boot 3.x 默认使用较新的日志库版本，确保项目中的日志框架已经升级到最新的稳定版本以防止兼容性问题。
• 日志配置：检查 log4j2.xml 或 logback-spring.xml 中的配置项是否需要更新，尤其是涉及 jakarta.* 包的。

8. Spring Cloud 和其他生态系统

• Spring Cloud 兼容性：如果你使用了 Spring Cloud，确保 Spring Cloud 版本与 Spring Boot 3.x 兼容。通常 Spring Cloud 会发布兼容特定 Spring Boot 版本的版本。
  • 例如：Spring Cloud 2022.0.x 系列版本兼容 Spring Boot 3.x。

9. 废弃和移除的 API

• 废弃 API 清单：在 Spring Boot 2.7.x 中，某些 API 可能已经标记为废弃，Spring Boot 3.x 可能会彻底移除这些 API。因此在升级前，建议先解决所有废弃 API 的警告。
• 工具：使用 jdeps 或 jdeprscan 工具检查是否使用了废弃的 API。

10. 配置文件的变更

• application.properties / application.yml：一些配置属性可能在 Spring Boot 3.x 中发生了变更或重命名，需要检查你的配置文件。
• 解决方法：参考 Spring Boot 官方发布的配置属性迁移指南，确保配置项正确迁移。

11. 测试框架

• JUnit 5：Spring Boot 3.x 强制要求使用 JUnit 5。如果你项目中仍在使用 JUnit 4，需要迁移到 JUnit 5。JUnit 5 提供了更现代化的 API 和特性，如 @ExtendWith、@TestFactory、@Nested 等。
• Mock 和 Stub 库：升级时也要注意测试框架如 Mockito、WireMock 等的兼容性。

示例：升级过程的步骤

1. 升级 Java 版本

• 修改 pom.xml 中的 maven.compiler.source 和 maven.compiler.target 为 17，或者修改 build.gradle 中的 sourceCompatibility 和 targetCompatibility 为 17。
• 确保在 JDK 17 环境下编译和运行项目。

2. 升级 Spring Boot 版本

• 在 pom.xml 中将 Spring Boot 版本升级为 3.3.x：

  <parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>3.3.x</version><relativePath/> <!-- lookup parent from repository -->
  </parent>
  

• 或者在 build.gradle 中：

  implementation 'org.springframework.boot:spring-boot-starter:3.3.x'
  

3. 迁移依赖库

• 使用 mvn dependency:tree 或 ./gradlew dependencies 查看依赖树，确保所有依赖都兼容 jakarta.* 包名。
• 手动调整代码中对 javax.* 的引用，改为 jakarta.*。

4. 运行和测试

• 运行项目，修复编译和运行时问题。
• 运行单元测试和集成测试，确保所有测试通过，且升级不会破坏功能。

额外工具

• jdeps：用于检测是否使用了已被移除的 JDK 内部 API。
• jdeprscan：扫描项目是否使用了已废弃的 API，可以结合 --release 17 参数来检查与 JDK 17 的兼容性。

总结

从 Spring Boot 2.7.x 升级到 3.3 是一个涉及较多变动的过程，特别是迁移到 Jakarta EE 和 JDK 17。你需要确保：

1. 项目在 JDK 17 上正常运行。
2. 所有 javax.* 包改为 jakarta.*。
3. 更新 Spring 依赖和第三方库以支持 Jakarta EE 9。
4. 仔细检查配置文件和日志，处理废弃 API。