3. Spring Boot 4.x 迁移指南：从 3.x 到 4.x

Spring Boot 4.x 迁移指南

本文详细介绍如何从 Spring Boot 3.x 平滑迁移到 4.x。

一、前置准备

1.1 升级 JDK

要求：Java 21+

# SDKMAN
sdk install java 21.0.1-tem
sdk use java 21.0.1-tem

# 验证
java -version
​

1.2 兼容性检查

# 使用 OpenRewrite 自动分析
mvn org.openrewrite.maven:rewrite-maven-plugin:run \
  -Drewrite.activeRecipes=io.github.patterns.springboot.UpgradeToSpringBoot4
​

二、依赖升级

2.1 父 POM 升级

<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>4.0.0</version>
</parent>
​

2.2 关键依赖

三、代码迁移

3.1 Jakarta EE 命名空间

自动迁移：

# Eclipse 自动迁移
mvn jakarta:eclipse
​

手动修改：

// ❌ 旧版
import javax.servlet.*;
import javax.persistence.*;

// ✅ 新版
import jakarta.servlet.*;
import jakarta.persistence.*;
​

3.2 配置属性变更

# 3.x
spring.jpa.database-platform=org.hibernate.dialect.PostgreSQLDialect

# 4.x（自动检测，通常不需要配置）
​

四、功能变化

4.1 虚拟线程

启用方式：

spring.threads.virtual.enabled=true
​

代码适配：

// 传统 @Async
@Async
public CompletableFuture<String> asyncMethod() { }

// 虚拟线程（更简单）
public String virtualThreadMethod() {
    // 自动使用虚拟线程
    return service.call();
}
​

4.2 可观测性

// 使用 @Observed 注解
@Observed(name = "user.login")
public User login(String username) {
    return userService.authenticate(username);
}
​

五、测试与验证

5.1 单元测试

@SpringBootTest
class ApplicationTests {
    @Test
    void contextLoads() {
        // 验证上下文加载
    }
}
​

5.2 集成测试

# 运行测试套件
mvn clean test

# 构建原生镜像测试
mvn -Pnative native:compile
​

六、常见问题

Q1: javax.* 类找不到？

A: 确保所有依赖已升级到 Jakarta EE 10+ 版本。

Q2: 启动失败？

A: 检查：

1. JDK 版本是否为 21+
2. 所有依赖是否兼容
3. 配置文件是否有语法错误

Q3: 性能下降？

A:

1. 启用虚拟线程
2. 调整堆内存大小
3. 检查 GC 日志

七、回滚方案

如果迁移遇到问题，可以：

# 回滚到 3.x
git revert <commit-hash>
mvn clean package
​

总结

迁移要点：

1. ✅ 升级到 JDK 21+
2. ✅ 更新所有依赖
3. ✅ javax.* → jakarta.*
4. ✅ 启用虚拟线程
5. ✅ 充分测试

预计迁移时间：1-2 周中小型项目