从 Spring Boot 2.x 平滑迁移至 3.x：Jakarta EE 9 与 Java 17 的挑战与机遇

你好！我是某团队技术负责人。

Spring Boot 3.0 的发布标志着 Java 生态系统的一个重要转折点。这不仅仅是一个版本号的跳跃，它是 Spring 框架拥抱云原生（Cloud Native）、AOT（Ahead-of-Time）编译以及 Java 语言现代化的里程碑。

然而，我也知道大家对于升级的顾虑。从 2.x 到 3.x 的迁移曲线比以往要陡峭，主要是因为底层的"地基"变了：Java 17 成为了最低基准，Jakarta EE 9 带来了包名的全面替换。

但这并非不可逾越。今天，我将带大家深入拆解这次迁移，从底层原理到实战代码，帮助大家平滑过渡。

从 Spring Boot 2.x 平滑迁移至 3.x：Jakarta EE 9 与 Java 17 的挑战与机遇

1. 引言：为什么要升级？

在着手迁移之前，我们必须明确收益。Spring Boot 3.x 并非为了升级而升级，它带来了以下核心价值：

拥抱原生（Native Image）：基于 GraalVM 的原生镜像支持成为一等公民，应用启动速度达到毫秒级，内存占用大幅降低。
Java 17+ 的红利：强制要求 Java 17 LTS，意味着我们可以直接使用 Records、Sealed Classes、Text Blocks 等语法特性，代码更简洁、性能更强。
可观测性（Observability）：Micrometer Tracing 取代了 Spring Cloud Sleuth，提供了统一的指标和链路追踪门面。

但机遇总是伴随着挑战。本次升级的破坏性更新较多，我们需要格外小心。

2. 核心概念与前置知识

2.1 Java 17 基准

Spring Boot 2.x 最低支持 Java 8，而 3.x 最低要求 Java 17。这迫使我们必须先完成 JDK 的升级。Java 17 是目前的 LTS（长期支持）版本，提供了更好的 GC 性能（ZGC）和模块化支持。

2.2 Jakarta EE 9：大更名（The Great Rename）

这是迁移中最大的痛点。由于 Oracle 将 Java EE 移交给 Eclipse Foundation，出于商标法律原因，所有的 javax.* 包名必须修改为 jakarta.* 。

这影响了 Servlet、JPA (Hibernate)、Validation (Bean Validation) 等几乎所有核心规范。

3. 技术深度解析与代码实战

3.1 核心挑战：从 Javax 到 Jakarta

在 Spring Boot 3 中，Tomcat、Jetty 等内嵌容器已升级至支持 Jakarta EE 10 的版本。如果你的代码中还残留着 import javax.persistence.*，编译将直接报错。

迁移策略：

你需要对整个项目进行全局替换。

代码对比：

Before (Spring Boot 2.x):

java 复制代码

import javax.persistence.Entity;
import javax.persistence.Id;
import javax.servlet.http.HttpServletRequest;
import javax.validation.constraints.NotNull;

@Entity
public class User {
    @Id
    private Long id;
    @NotNull
    private String username;
}

After (Spring Boot 3.x):

java 复制代码

// 包名全面变更
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.validation.constraints.NotNull;

@Entity
public class User {
    @Id
    private Long id;
    @NotNull
    private String username;
}

注意：像 javax.sql.* 或 javax.crypto.* 这样属于 Java SE 标准库的包不需要修改，只有属于 Java EE (Jakarta EE) 规范的包需要修改。

3.2 Java 17 特性集成

升级后，我们可以利用 Java 17 的 Record（记录类）来简化 DTO（数据传输对象）的定义。Spring Boot 3 对 Record 有着极好的支持，包括数据绑定和 JSON 序列化。

实战示例：使用 Record 替代 Lombok @Data

java 复制代码

// Spring Boot 2.x (使用 Lombok)
@Data
@AllArgsConstructor
public class UserDto {
    private String username;
    private String email;
}

// Spring Boot 3.x (Java 17 Record)
// 更加简洁，不可变性，且原生支持
public record UserDto(String username, String email) {}

在 Controller 中直接使用：

java 复制代码

@PostMapping("/register")
public ResponseEntity<String> register(@RequestBody UserDto userDto) {
    // userDto.username(); // 访问方式变为方法调用
    return ResponseEntity.ok("User registered: " + userDto.username());
}

3.3 Spring Security 6 的重大重构

Spring Security 6.0 是 Spring Boot 3 的默认依赖，它移除了过时的 WebSecurityConfigurerAdapter，要求基于组件（Bean）的方式配置安全策略。这是很多开发者遇到的最大"坑"。

迁移实战：

Before (继承 Adapter):

java 复制代码

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

After (SecurityFilterChain Bean):

java 复制代码

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorize -> authorize
                // 注意：antMatchers 被 requestMatchers 取代
                .requestMatchers("/public/**").permitAll()
                .anyRequest().authenticated()
            )
            .formLogin(Customizer.withDefaults()); // 使用 Lambda DSL
        
        return http.build();
    }
}

关键点变化：

antMatchers() 变更为 requestMatchers()。
废弃了 .and() 的链式调用，推荐使用 Lambda DSL（如 .authorizeHttpRequests(auth -> ...)），可读性更强。

4. 常见迁移陷阱与解决方案

陷阱 1：第三方库的兼容性（Lombok, Swagger, Hibernate）

很多第三方库如果版本过低，不支持 Jakarta EE 9 命名空间，会导致 ClassNotFoundException。

Lombok : 必须升级到 1.18.22 以上（主要是对 JDK 17 的支持）。
Swagger/OpenAPI : 旧版 springfox 库已停止维护且不支持 Spring Boot 3。
- 解决方案 : 迁移至 springdoc-openapi-starter-webmvc-ui (v2.x)。
Hibernate: Spring Boot 3 默认集成了 Hibernate 6.x。如果你的代码依赖了 Hibernate 特有的旧 API，可能需要重构。

陷阱 2：URL 尾部斜杠匹配

在 Spring Boot 2.x 中，/api/users 和 /api/users/ 默认是匹配同一个 Controller 方法的。
在 Spring Boot 3.x 中，这是一个重大变更：默认不再自动匹配尾部斜杠。

/api/users 只能匹配 /api/users。
如果客户端请求 /api/users/，将返回 404。

解决方案：

规范客户端调用。

或者通过配置改回旧行为（不推荐，建议适应新规范）：

java 复制代码

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void configurePathMatch(PathMatchConfigurer configurer) {
        configurer.setUseTrailingSlashMatch(true); // 已标记为 Deprecated，但仍可用
    }
}

陷阱 3：配置文件属性迁移

部分配置属性在 3.x 中被移除或重命名。例如 spring.redis.* 变更为 spring.data.redis.*。

解决方案：

引入 spring-boot-properties-migrator 依赖。它会在启动时检测旧属性，并在控制台打印警告，告诉你正确的新属性名。迁移完成后务必移除该依赖。

xml 复制代码

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

5. 最佳实践指南

5.1 "两步走" 迁移策略

不要试图直接从 2.1 或 2.3 升级到 3.0。

第一步 ：先升级到 Spring Boot 2.7.x（2.x 的最后一个版本）。2.7 版本提供了许多向后兼容的桥接和弃用警告，这是最好的跳板。
第二步 ：修复所有 2.7 中的 Deprecated 警告。
第三步：修改版本号至 3.x，升级 JDK 至 17，执行包名替换。

5.2 使用自动化工具

手动替换 javax 包名容易出错且枯燥。强烈推荐使用 OpenRewrite 。

OpenRewrite 提供了一个 Maven/Gradle 插件，可以自动扫描源代码并执行 Spring Boot 3 的迁移配方（Recipe），包括依赖升级、代码替换、配置修改。

Maven 示例：

bash 复制代码

mvn org.openrewrite.maven:rewrite-maven-plugin:run \
  -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-spring:RELEASE \
  -Drewrite.activeRecipes=org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_0

5.3 调整依赖管理

检查 pom.xml 或 build.gradle。Spring Boot 3 移除了对某些旧库的自动版本管理（如 EhCache 2, Hazelcast 3），需要确保所有传递依赖都支持 Jakarta EE。

6. 总结

从 Spring Boot 2.x 迁移到 3.x 是一次"伤筋动骨"但也"脱胎换骨"的过程。

挑战在于处理 Jakarta EE 的包名变更、适应 Spring Security 6 的新配置模式以及解决第三方库的兼容性。
机遇在于获得了 Java 17 的强大语法糖、GraalVM 原生镜像的极速启动能力以及更加现代化的观测性体系。

作为工程师，我们不应畏惧版本升级。通过先升级到 2.7、利用 OpenRewrite 自动化工具、以及充分的单元测试覆盖，我们可以将风险降到最低。

现在，检查你的 JDK 版本，准备好拥抱 Spring Boot 3 的全新世界吧。

注：本文基于 Spring Boot 3.0 及 3.1 版本特性编写。随着版本迭代，部分细节可能微调，请以官方文档为准。