Spring Boot 3.x 升级相比 2.x 变化非常大，因为它基于 Spring Framework 6 和 Jakarta EE 10，牵涉到包名、依赖、JDK 要求等多个层面。

一、升级的坑（常见踩雷点）

1.JDK 要求

• 最低 JDK 版本：17（推荐直接用 JDK 21 LTS）。
• 如果项目是 JDK8/11，需要先升级到 JDK17 才能用 Spring Boot 3.x。

2.Jakarta EE 包名全量迁移

• 原来 javax.* → 全部变成 jakarta.*。
• 常见影响：
• Servlet API：javax.servlet → jakarta.servlet
• JPA：javax.persistence → jakarta.persistence
• Validation：javax.validation → jakarta.validation
• 解决方法：代码、依赖、第三方库都要支持新包名，否则直接编译错误。
• 坑点：老旧依赖（如老版本的 Hibernate Validator、Shiro、MyBatis 扩展）如果不支持 Jakarta 包，必须升级版本。

3.第三方依赖兼容性

• 依赖必须支持 Spring 6 / Jakarta EE 10 / JDK17，否则无法编译或运行。
• 特别是：
• 安全框架（Spring Security / Shiro）
• ORM（Hibernate / MyBatis / JOOQ）
• 模板引擎（Thymeleaf、Freemarker）
• Swagger → springdoc-openapi（Swagger 2 已不再维护，且不兼容）

4.Spring Security 大改

4.1 包导入替换

• 把所有代码中 javax.* 改为对应的 jakarta.*。
• IDE 可批量替换。

4.2 Spring Security 配置变更

• 删除 WebSecurityConfigurerAdapter 继承类。
• 新增 SecurityFilterChain Bean，使用 Lambda DSL 方式：

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http.authorizeHttpRequests(auth -> auth
        .requestMatchers("/public/**").permitAll()
        .anyRequest().authenticated());
    return http.build();
}

4.3 JPA 和 Hibernate 变更

• 升级 persistence.xml 中命名空间（如有）。
• 变更方言（Dialect）类名。
• 注意 Hibernate 6 新增的方法和废弃的 API。
• 查询语句和 @Formula 语法需验证。

4.4 配置文件调整

• 属性命名变动，参见官方文档。
• 典型示例：
• spring.data.rest.basePath → spring.data.rest.base-path
• spring.jpa.hibernate.use-new-id-generator-mappings 已废弃。
• 重新确认 Actuator 端点暴露配置：

management:
  endpoints:
    web:
      exposure:
        include: "*"

4.5 测试框架

• 切换到 JUnit 5。
• 旧的 @RunWith(SpringRunner.class) 改用 @ExtendWith(SpringExtension.class)。
• 依赖修改：

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>5.x.x</version>
    <scope>test</scope>
</dependency>

5.构建与运行

6.国际化（i18n）默认编码变化

• MessageSource 默认 UTF-8 编码（2.x 默认是 ISO-8859-1）。
• 旧项目可能需要重新确认 properties 文件编码。

7.Hibernate 6.x 变化

• Hibernate 6.x 是 Spring Boot 3.x 默认 JPA 实现。
• 部分 API 废弃/变更：
• Query#unwrap 行为调整。
• @Formula 的语法要求更严格。
• 方言（Dialect）类包名变化。
• 生成 SQL 默认参数绑定方式变成 position-based。

8.配置文件属性调整

• 部分配置项已重命名或废弃，例如：
• spring.jpa.hibernate.use-new-id-generator-mappings → 已废弃
• spring.data.rest.basePath → 改为 spring.data.rest.base-path
• 需要查 Spring Boot 3.0 Migration Guide 对照表。

9.测试框架变化

• JUnit 5 是默认测试框架（JUnit 4 已不直接支持）。
• @SpringBootTest、@DataJpaTest 等注解用法基本不变，但部分 mock API 调整。

二、新特性亮点

1.基于 Spring Framework 6

• 全面支持 JDK 17+ 语言特性（record、sealed class、pattern matching）。
• 原生支持 Virtual Threads（JDK 21 Project Loom）。
• 提升底层性能和内存效率。

2.全面 Jakarta EE 10

• 最新 Servlet 6.0、JPA 3.1、Bean Validation 3.0。
• 为未来 Java EE 演进做好兼容。

3.AOT / 原生镜像支持

• 内置 GraalVM Native Image 支持，可生成可执行文件（启动快、内存小）。
• mvn -Pnative native:compile
• 对微服务和 Serverless 非常友好。

4.新的 Observability 体系

• 与 Micrometer 结合更紧密，支持 OpenTelemetry。
• 更方便链路追踪（Tracing）和 Metrics 采集。

5.JSON 处理更灵活

• 默认 Jackson 2.14+，更好地支持 Java 17 记录类型（record）和 Instant。
• 支持 @JsonCreator 简化反序列化。

6.改进的 Web 层

• WebFlux / WebMvc 性能提升。
• HttpInterface Client（声明式 HTTP 调用，类似 OpenFeign）：
• @HttpExchange("/users") interface UserClient { @GetExchange("/{id}") User getUser(@PathVariable String id); }

7.Docker/K8s 支持更完善

• spring-boot:build-image 生成容器镜像更轻量。
• 支持 buildpacks 自动探测运行环境。

三、升级建议

1. 先升级依赖（Spring Security、Hibernate、Thymeleaf、Swagger → springdoc）。
2. 批量替换包名（javax → jakarta）。
3. 改安全配置（去掉 WebSecurityConfigurerAdapter）。
4. 跑集成测试，尤其是持久层和国际化。
5. 可选：试试 GraalVM 原生镜像优化启动速度。

排查步骤建议

• 编译期：
• 包导入错误，依赖缺失。
• API 变更的编译错误。
• 启动期：
• Spring Security 配置异常，导致授权失败。
• Hibernate 实体扫描失败或映射异常。
• 运行期：
• Actuator 端点不可访问。
• 监控指标缺失。
• REST 接口序列化异常。
• 测试期：
• 兼容性测试覆盖。
• 集成测试和单元测试全部通过。

参考资料

• 官方升级指南（重点阅读）
  https://docs.spring.io/spring-boot/docs/3.0.0/reference/htmlsingle/#migration
• Spring Framework 6 迁移
  https://github.com/spring-projects/spring-framework/wiki/Upgrading-to-Spring-Framework-6.x
• Hibernate 6 变更说明
  https://hibernate.org/orm/releases/6.0/
• Spring Security 6 迁移文档
  https://spring.io/blog/2022/11/10/spring-security-6-0-migration-guide