Spring Boot 2.x → 3.x 实战迁移完整指南

Spring Boot 3.x 带来了 Spring Framework 6、Jakarta EE 9+、JDK 17+ 等一系列重大变化，这是一场“必经的迁移”。本文从 实战角度 出发，手把手带你完成一个 Spring Boot 2.x 项目升级到 3.x 的全过程：依赖变更、代码适配、潜在问题、最佳实践。

一、升级前准备 (Pre-Migration Checklist)

在开始之前，务必做好准备，这是成功升级的关键。

1. 备份项目
   使用 Git 管理代码，并确保当前工作区干净。升级建议新开分支，保留“安全网”。
2. 检查当前版本
   确认 Spring Boot 2.x 的具体版本（如 2.7.18）。建议先升级到该分支的最新版本，再跳到 3.x，减少跨度。
3. 阅读官方文档（必读）

• Spring Boot 3.0 Migration Guide
• Spring Framework 6.0 Migration Guide

4. Java 版本升级
   Spring Boot 3.0 必须 使用 Java 17 或更高版本（推荐 21 LTS）。确保开发环境、CI/CD 和服务器环境统一。
5. 第三方依赖检查

• 使用 ./mvnw dependency:tree 或 gradle dependencies 查看依赖树。
• 确认 MyBatis、Redis、Kafka、SpringDoc 等库是否有 Boot 3 兼容版本。
• MySQL 驱动需替换为 mysql-connector-j（旧的 mysql-connector-java 已废弃）。

6. 自动化迁移工具（推荐）
   引入 OpenRewrite，一键完成 javax.* → jakarta.*、属性改名等迁移：

<plugin>
  <groupId>org.openrewrite.maven</groupId>
  <artifactId>rewrite-maven-plugin</artifactId>
  <version>5.29.0</version>
  <configuration>
    <activeRecipes>
      <recipe>org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_5</recipe>
    </activeRecipes>
  </configuration>
</plugin>

执行：

./mvnw -U rewrite:run

二、核心变更与实战修改步骤

1. 修改 POM.xml / build.gradle

Maven 示例：

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.5.5</version> <!-- 当前稳定版本 -->
    <relativePath/>
</parent>

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

关键变化：

• Jakarta EE：所有 javax.* 包 → jakarta.*
• MySQL 驱动：使用 mysql-connector-j
• SpringDoc OpenAPI：替换为 springdoc-openapi-starter-webmvc-ui:2.8.x

2. 代码修改：javax.* → jakarta.*

Spring Boot 3.x 核心变化：基于 Jakarta EE 9，命名空间全面迁移。

常见修改：

• Servlet: javax.servlet.* → jakarta.servlet.*
• JPA: javax.persistence.* → jakarta.persistence.*
• Validation: javax.validation.* → jakarta.validation.*
• 注解: javax.annotation.* → jakarta.annotation.*

示例：

// Boot 2.x
import javax.persistence.Entity;
import javax.persistence.Id;
import javax.validation.constraints.NotNull;

// Boot 3.x
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.validation.constraints.NotNull;

3. Spring Security 6 配置变更

WebSecurityConfigurerAdapter 已移除，必须改为 SecurityFilterChain Bean。

旧写法 (Boot 2.x)：

@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
                .antMatchers("/public/**").permitAll()
                .anyRequest().authenticated();
    }
}

新写法 (Boot 3.x)：

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    @Bean
    SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        return http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/public/**").permitAll()
                .anyRequest().authenticated()
            )
            .formLogin(Customizer.withDefaults())
            .build();
    }
}

4. 配置文件变更

常见变化：

• server.max-http-header-size → server.max-http-request-header-size
• Spring MVC 默认 Path 匹配：PathPatternParser 替代 AntPathMatcher
• Spring Sleuth 已废弃 → 使用 Micrometer Tracing

运行以下命令，自动检查配置差异：

./mvnw spring-boot:validate -Dspring-boot.version=3.5.5

5. 第三方库适配

• SpringDoc OpenAPI：升级到 2.8.x

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.8.11</version>
</dependency>

• MySQL 驱动：mysql-connector-j
• Lombok：升级到 1.18.24+
• 测试依赖：升级到 Boot 3.x 的 spring-boot-starter-test

三、常见问题与解决方案 (Q&A)

1. ClassNotFoundException / NoSuchMethodError

• 原因：依赖冲突或旧库混入
• 解决：mvn dependency:tree，排除旧版本

2. 找不到 javax 类

• 原因：Hibernate 或 Validator 版本过旧
• 解决：确保使用 Boot 管理的版本，移除手动声明的旧依赖

3. Spring Security 报错

• 原因：WebSecurityConfigurerAdapter 已移除
• 解决：使用 SecurityFilterChain Bean 重写

4. 配置属性不生效

• 原因：配置已重命名或废弃
• 解决：对照官方迁移指南或用 spring-boot:validate

5. 链路追踪失效

• 原因：Spring Sleuth 已废弃
• 解决：切换到 Micrometer Tracing + OpenTelemetry/Zipkin

四、升级后验证

1. 编译通过：确保编译成功，无 javax.*
2. 接口测试：访问 /actuator/health
3. 安全验证：测试登录、权限校验
4. 数据库操作：验证 JPA/MyBatis 正常
5. 监控与日志：确认 Micrometer 指标和链路追踪是否正常

五、加分项：AOT & Native Image

Spring Boot 3.x 原生支持 GraalVM Native Image，可构建更快启动、低内存占用的二进制应用。

构建命令：

./mvnw -Pnative spring-boot:build-image

适合边车服务、Serverless、微服务网关等场景。

六、总结

Spring Boot 2.x → 3.x 升级核心任务：

1. 环境：JDK ≥ 17
2. Jakarta 命名空间：全局替换 javax → jakarta
3. 依赖对齐：BOM 管理三方库，替换过期依赖（如 MySQL 驱动）
4. 配置更新：关注属性改名、PathPattern、监控链路
5. 安全配置重写：用 SecurityFilterChain 取代 WebSecurityConfigurerAdapter

建议 在独立分支逐步升级，借助 OpenRewrite 自动迁移，再通过 回归测试与监控验证，确保平滑过渡。