从 Spring Boot 2 升级到 Spring Boot 3 的终极指南

一、升级前的核心准备

1. JDK 版本升级

Spring Boot 3 强制要求 Java 17 及以上版本。若当前项目使用 Java 8 或 11，需按以下步骤操作：

安装 JDK 17 ：从 Oracle 或 OpenJDK 官网下载，配置环境变量（如 JAVA_HOME）。
IDE 设置 ：在 IntelliJ IDEA 或 Eclipse 中修改项目 JDK 版本（示例）：
xml 复制代码
```

<properties>
    <java.version>17</java.version>
</properties>
```

2. 依赖版本检查

Spring Boot 3 基于 Spring Framework 6 和 Jakarta EE 10，需确保所有依赖兼容：

Spring Cloud：建议升级至 2023.0.x 版本。
数据库驱动：如 MyBatis 需升级到 3.0.3+，Hibernate 到 6.1.4+。
第三方库：检查 Redis、ShardingSphere 等是否支持 Spring Boot 3（如 ShardingSphere 5.4.1+）。

二、代码迁移的核心步骤

1. Spring Boot 版本升级

修改 pom.xml 或 build.gradle：

xml 复制代码

<!-- Maven 示例 -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.4</version>  <!-- 最新稳定版 -->
</parent>

2. Jakarta EE 包名替换

所有 javax.* 包需替换为 jakarta.*，例如：

java 复制代码

// 修改前
import javax.servlet.http.HttpServletRequest;
// 修改后
import jakarta.servlet.http.HttpServletRequest;

操作技巧 ：使用 IDE 的全局替换功能（如 IntelliJ 的 Ctrl+Shift+R）批量修改。

3. 配置属性迁移

Spring Boot 3 中部分配置项已变更：

Redis 配置 ：spring.redis → spring.data.redis
日志格式 ：默认日期格式改为 ISO-8601，可通过以下配置恢复旧格式：
yaml 复制代码
```
logging:
  pattern:
    dateformat: "yyyy-MM-dd HH:mm:ss.SSS"
```

辅助工具 ：添加 spring-boot-properties-migrator 生成迁移报告：

xml 复制代码

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-properties-migrator</artifactId>
    <scope>runtime</scope>
</dependency>

4. 注解与 API 调整

@ConstructorBinding：不再需要类级别的注解，仅用于多构造函数的场景。

URL 匹配规则 ：默认关闭尾部斜杠匹配，需手动启用：

java 复制代码

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void configurePathMatch(PathMatchConfigurer configurer) {
        configurer.setUseTrailingSlashMatch(true);  // 启用斜杠匹配
    }
}

三、关键问题与解决方案

1. 依赖冲突

场景：启动时抛出 ClassNotFoundException 或 NoSuchMethodError。
解决：

检查依赖树：使用 mvn dependency:tree 分析冲突。

排除旧版本依赖（示例）：

xml 复制代码

<dependency>
    <groupId>com.example</groupId>
    <artifactId>old-library</artifactId>
    <exclusions>
        <exclusion>
            <groupId>javax.servlet</groupId>
            <artifactId>servlet-api</artifactId>
        </exclusion>
    </exclusions>
</dependency>

2. 安全配置变更

Spring Security 6 中 SecurityContext 需显式保存：

java 复制代码

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
        .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
        .securityContext(securityContext -> securityContext
            .securityContextRepository(new HttpSessionSecurityContextRepository())  // 启用 Session 存储
        );
    return http.build();
}

3. 响应式编程兼容性

若使用 WebFlux，需注意：

响应头大小限制 ：Tomcat 需自定义配置：

java 复制代码

@Configuration
public class ServerConfig implements WebServerFactoryCustomizer<TomcatServletWebServerFactory> {
    @Override
    public void customize(TomcatServletWebServerFactory factory) {
        factory.addConnectorCustomizers(connector -> 
            connector.setProperty("maxHttpResponseHeaderSize", "100000"));
    }
}

四、升级后的验证与优化

1. 测试策略

单元测试 ：确保所有 @SpringBootTest 测试通过。
集成测试：使用 Testcontainers 验证数据库、Redis 等外部服务。
性能测试：通过 JMeter 对比启动时间和内存占用（Spring Boot 3 启动速度提升约 20%）。

2. 监控与日志

Actuator 配置 ：启用健康检查与指标监控：

yaml 复制代码

management:
  endpoints:
    web:
      exposure:
        include: health,metrics

日志聚合：集成 ELK 或 Prometheus + Grafana。

五、总结与建议

升级到 Spring Boot 3 不仅是版本迭代，更是技术栈的全面革新。通过本文的步骤，开发者可系统性解决包名替换、配置迁移、依赖冲突等核心问题。建议在升级前充分备份代码，并参考官方迁移指南。最终，你将获得更快的启动速度、更好的虚拟线程支持，以及 Jakarta EE 10 的现代化特性。