Spring Boot 3 升级至 4 完整迁移指南

Gradle 配置：

plugins {
    id 'org.springframework.boot' version '4.0.0'
    id 'io.spring.dependency-management' version '1.1.4'
}
java {
    sourceCompatibility = '21'
    targetCompatibility = '21'
}

2. 添加属性迁移工具

部分配置属性可能被废弃或改名。Spring Boot 提供了 spring-boot-properties-migrator 工具，可在启动时自动检查并提示废弃属性。

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

// Gradle 配置
dependencies {
    runtimeOnly 'org.springframework.boot:spring-boot-properties-migrator'
}

启动应用后，该工具会在日志中提示废弃属性。升级完成后，记得移除该依赖。

3. 检查第三方依赖兼容性

Spring Boot 4 升级了 Spring Framework 至 7.0，部分第三方依赖可能尚未适配。需逐一检查是否有兼容版本。

<!-- 数据库相关 -->
<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
</dependency>
<!-- Redis 相关 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>
<!-- 消息队列 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-amqp</artifactId>
</dependency>

建议访问各依赖官网确认是否发布兼容 Spring Boot 4 的版本。

代码修改

1. 废弃的 API 替换

Spring Boot 4 全面支持 Jackson 3，Jackson 2 的自动配置被标记为废弃。

// 升级前：使用 Jackson 2
@Configuration
public class JacksonConfig {
    @Bean
    public Jackson2ObjectMapperBuilder jackson2ObjectMapperBuilder() {
        return new Jackson2ObjectMapperBuilder();
    }
}

// 升级后：改用 Jackson 3
@Configuration
public class JacksonConfig {
    @Bean
    public JacksonObjectMapperBuilder jacksonObjectMapperBuilder() {
        return new JacksonObjectMapperBuilder();
    }
}

2. 配置属性迁移

部分配置属性已改名或被废弃。启动时 spring-boot-properties-migrator 会提示具体变化。

# 升级前配置
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/test
    username: root
    password: 123456
    driver-class-name: com.mysql.cj.jdbc.Driver

根据日志提示调整属性名或删除不需要的配置。

3. 虚拟线程配置

Spring Boot 4 深度集成虚拟线程。若使用 JDK 21，可启用以提升并发性能。

# application.yml 配置
spring:
  threads:
    virtual:
      enabled: true

// 代码中使用虚拟线程执行器
@Configuration
public class VirtualThreadConfig {
    @Bean
    public Executor virtualThreadExecutor() {
        return Executors.newVirtualThreadPerTaskExecutor();
    }

    @Bean
    public TomcatProtocolHandlerCustomizer<?> protocolHandlerVirtualThreadExecutorCustomizer() {
        return protocolHandler -> {
            protocolHandler.setExecutor(Executors.newVirtualThreadPerTaskExecutor());
        };
    }
}

4. 声明式 HTTP 客户端

Spring Framework 7.0 引入声明式 HTTP 客户端，替代 RestTemplate 和 WebClient。

// 升级前：使用 RestTemplate
@Service
public class UserService {
    @Autowired
    private RestTemplate restTemplate;

    public User getUser(Long id) {
        return restTemplate.getForObject("http://api.example.com/users/" + id, User.class);
    }
}

// 升级后：改用声明式 HTTP 客户端
@HttpExchange(url = "http://api.example.com")
public interface UserClient {
    @GetExchange("/users/{id}")
    User getUser(@PathVariable Long id);
}

@Service
public class UserService {
    @Autowired
    private UserClient userClient;

    public User getUser(Long id) {
        return userClient.getUser(id);
    }
}

测试和验证

1. 编译检查

升级后先进行编译，解决出现的错误。

# Maven 编译
mvn clean compile
# Gradle 编译
./gradlew clean build

2. 启动应用

启动应用并观察日志，确认无异常及属性警告。

# 启动应用
mvn spring-boot:run
# 或 java -jar target/your-app.jar

3. 功能测试

运行功能测试，重点验证修改过的代码逻辑。

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

    @Test
    void testUserService() {
        // 验证业务功能
    }
}

常见问题处理

1. 依赖冲突

使用构建工具检查依赖树，排除冲突依赖或升级版本。

# Maven 检查依赖树
mvn dependency:tree
# Gradle 检查依赖
./gradlew dependencies

<!-- Maven 排除冲突依赖 -->
<dependency>
    <groupId>com.example</groupId>
    <artifactId>some-library</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework</groupId>
            <artifactId>spring-core</artifactId>
        </exclusion>
    </exclusions>
</dependency>

2. 配置属性找不到

若日志提示属性被废弃，按提示修改为新属性名或删除。

3. 类找不到

若报 ClassNotFoundException，检查依赖版本是否兼容 Spring Boot 4。

升级后的优化

1. 启用虚拟线程

JDK 21 环境下建议启用虚拟线程以大幅提升并发性能。

spring:
  threads:
    virtual:
      enabled: true

2. 使用 GraalVM 原生镜像

Spring Boot 4 对 GraalVM 支持更完善，可尝试编译原生镜像以加快启动速度并减少内存占用。

# Maven 构建镜像
mvn spring-boot:build-image
# Gradle 构建镜像
./gradlew bootBuildImage

3. 使用分层 JAR

启用分层 JAR 可将依赖层、资源层和业务层分开，优化 Docker 镜像构建效率。

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <layers>
            <enabled>true</enabled>
        </layers>
    </configuration>
</plugin>

总结

从 Spring Boot 3 升级到 4 的主要步骤包括：

1. 检查环境：确认 JDK 版本及当前 Spring Boot 版本。
2. 备份代码：使用 Git 创建分支或备份文件。
3. 升级依赖：更新 Spring Boot 版本，检查第三方依赖兼容性。
4. 修改代码：替换废弃 API，迁移配置属性。
5. 测试验证：完成编译、启动及功能测试。
6. 优化配置：启用虚拟线程，使用原生镜像等特性。

升级过程需耐心细致，遇到问题查阅文档或日志提示。升级完成后，虚拟线程和原生镜像等特性将带来明显的性能提升。