Spring Boot 升级全攻略：从 2.2 到 2.7 再到 3.x

📋 升级背景

随着业务发展和技术迭代，保持与 Spring 生态系统的同步至关重要。本次升级将从 Spring Boot 2.2.x 版本逐步升级到 2.7.x 版本，并规划未来升级到 3.x 版本，以获取最新的特性、性能改进和安全补丁。

🔍 框架升级概览

核心框架版本演进

• 2.2.x → 2.7.x：稳定性增强，自动配置优化
• 2.7.x → 3.x：Jakarta EE 命名空间变更，现代化架构

关键变更对比

版本	核心变更	影响程度
2.2 → 2.7	自动配置优化，环境变量绑定调整	低-中
2.7 → 3.0	Jakarta EE 迁移，Security 重构	高

📦 依赖项变更

主要依赖版本变更

依赖	2.2版本	2.7版本	3.0版本
Spring Boot	2.2.x	2.7.x	3.x
Spring Cloud	Hoxton	2021.x	2024.x/2025.x
Hibernate	5.4.x	5.6.x	6.1+
Java	8+	11+	17+

Spring Cloud 重大变更

• FallbackFactory 导入路径变更 ：从 feign.hystrix.FallbackFactory 变更为 org.springframework.cloud.openfeign.FallbackFactory
• 移除 Hystrix 依赖：推荐使用 Sentinel 或 Resilience4j 替代
• Ribbon 替换：使用 Spring Cloud LoadBalancer 替代
• Bootstrap 依赖 ：Spring Cloud 2021.x+ 需要单独引入 spring-cloud-starter-bootstrap

内部依赖注意事项

需要确认以下内部依赖与 Spring Boot 2.7/3.0 的兼容性：

内部代码:略 哈哈哈哈

---

---

🛠️ MyBatis 配置简化

Spring Boot 2.7+ 对 MyBatis 配置进行了优化，减少了冗余配置，提高了启动速度。

📝 详细变更分析

核心功能变更

自动配置

• 2.2 → 2.7：自动配置类加载机制优化，减少启动时间
• 2.7 → 3.0 ：Jakarta EE 命名空间变更（javax.* → jakarta.*）

环境变量绑定

• 2.2 → 2.7：环境变量绑定规则调整，更严格的属性名匹配
• 2.7 → 3.0：配置属性绑定更加严格，支持 Kotlin 扩展

日志配置

• 2.2 → 2.7：默认日志配置调整，更合理的默认值
• 2.7 → 3.0：日志框架升级，支持 Logback 1.4+

安全相关变更

Spring Security 配置（2.2 → 2.7）

WebSecurityConfigurerAdapter 被标记为废弃，推荐使用组件式配置：

// 旧方式
@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        // 配置
    }
}

// 新方式
@Configuration
public class SecurityConfig {
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        // 配置
        return http.build();
    }
}

Spring Security 6.0 变更（2.7 → 3.0）

全面支持 Jakarta Servlet 6.0，安全过滤器链重构：

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

数据访问变更

JPA/Hibernate 升级（2.2 → 2.7）

• Hibernate 版本从 5.4.x 升级到 5.6.x
• 部分 HQL 查询语法可能需要调整

Jakarta Persistence（2.7 → 3.0）

从 javax.persistence 迁移到 jakarta.persistence：

// 2.7 及之前
import javax.persistence.Entity;
import javax.persistence.Id;

// 3.0+
import jakarta.persistence.Entity;
import jakarta.persistence.Id;

Spring Cloud 重大变更

熔断降级迁移

Hystrix 被移除，必须迁移到 Sentinel 或 Resilience4j：

// Hystrix (已废弃)
@HystrixCommand(fallbackMethod = "fallback")
public String call() { }

// Resilience4j (推荐)
@CircuitBreaker(name = "backendA", fallbackMethod = "fallback")
public String call() { }

// Sentinel (推荐)
@SentinelResource(value = "backendA", fallback = "fallback")
public String call() { }

负载均衡迁移

Ribbon 被 Spring Cloud LoadBalancer 替代，需要调整负载均衡配置。

⚠️ 风险评估

高风险项

• Jakarta EE 命名空间迁移（javax → jakarta）
• Spring Security 配置重构
• 熔断降级框架迁移

中风险项

• 环境变量绑定规则变更
• Hibernate 版本升级带来的查询语法调整
• 内部依赖兼容性问题

低风险项

• 日志配置调整
• Actuator 配置变更
• 第三方依赖版本升级

🔥 核心改造要点（3.x 升级）

1. POM 改造

• 升级父 POM 到 3.4.0+
• 升级 Spring Cloud 到 2024.x/2025.x
• 升级 Spring Cloud Alibaba 到 2023.x/2024.x
• 清理旧 Hystrix/旧 Feign 残余

2. 包名替换

• 全局检索替换 javax.* 为 jakarta.*
• 特别注意 Feign 接口中的 javax.validation.Valid 改为 jakarta.validation.Valid

3. Bootstrap 配置

• 引入 spring-cloud-starter-bootstrap 依赖
• 保留现有 bootstrap.yml 结构
• 确保 Nacos 远程配置在启动早期能正常拉取

4. Web 服务器

• 从 Tomcat 切换到 Undertow
• 避免同时存在 Tomcat 与 Undertow 依赖

5. Sentinel/Nacos/Feign 迁移

• 版本对齐到 Spring Cloud Alibaba 2023.x/2024.x
• 保持 Sentinel/OpenFeign 方案
• 处理与 MVC 的循环依赖

6. ORM 与数据访问

• 升级 MyBatis-Plus 到 3.5.5+
• 检查分页插件、类型处理器、枚举映射等自定义实现
• 保持 MySQL 驱动配置

7. 校验与序列化

• Hibernate Validator 8+（Jakarta 命名空间）
• 评估从 Fastjson 迁移到 Jackson

8. Actuator/监控

• 按 3.x 新语法调整 management.* 配置
• 配置健康检查和指标暴露

9. 自动化迁移

使用 OpenRewrite 进行批量处理：

mvn org.openrewrite.maven:rewrite-maven-plugin:run -DactiveRecipes=org.openrewrite.java.spring.boot3.SpringBoot3Migration

🛡️ Sentinel 熔断降级集成

依赖配置

<!-- 添加 Sentinel 依赖 -->
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
    <version>2023.0.0.0</version> <!-- 对应 Spring Cloud 2023.x -->
</dependency>

<!-- 可选：添加 Sentinel Dashboard 监控 -->
<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-dashboard</artifactId>
    <version>1.8.6</version>
</dependency>

<!-- 可选：添加 Feign 集成 -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-openfeign</artifactId>
</dependency>

配置示例

# application.yml
spring:
  cloud:
    sentinel:
      transport:
        dashboard: localhost:8080  # Sentinel Dashboard 地址
        port: 8719  # 客户端端口
      datasource:
        ds1:
          nacos:
            server-addr: localhost:8848
            data-id: sentinel-flow-rules
            group-id: DEFAULT_GROUP
            rule-type: flow
      filter:
        enabled: true

# 开启 Feign 对 Sentinel 的支持
feign:
  sentinel:
    enabled: true

代码示例

注解方式

import com.alibaba.csp.sentinel.annotation.SentinelResource;
import com.alibaba.csp.sentinel.slots.block.BlockException;

@RestController
@RequestMapping("/api")
public class TestController {
    
    @GetMapping("/test")
    @SentinelResource(
        value = "testResource",
        blockHandler = "blockHandlerMethod",
        fallback = "fallbackMethod"
    )
    public String test() {
        // 业务逻辑
        return "Success";
    }
    
    // 熔断降级处理方法
    public String blockHandlerMethod(BlockException e) {
        return "服务限流，请稍后重试";
    }
    
    // 异常降级处理方法
    public String fallbackMethod(Throwable e) {
        return "服务异常，请稍后重试";
    }
}

配置类方式

import com.alibaba.csp.sentinel.slots.block.RuleConstant;
import com.alibaba.csp.sentinel.slots.block.flow.FlowRule;
import com.alibaba.csp.sentinel.slots.block.flow.FlowRuleManager;
import org.springframework.boot.CommandLineRunner;
import org.springframework.stereotype.Component;

import java.util.ArrayList;
import java.util.List;

@Component
public class SentinelConfig implements CommandLineRunner {
    @Override
    public void run(String... args) {
        initFlowRules();
    }
    
    private void initFlowRules() {
        List<FlowRule> rules = new ArrayList<>();
        
        // 配置限流规则
        FlowRule rule = new FlowRule();
        rule.setResource("testResource");
        rule.setGrade(RuleConstant.FLOW_GRADE_QPS);
        rule.setCount(20); // QPS 限制为 20
        rule.setLimitApp("default");
        rules.add(rule);
        
        FlowRuleManager.loadRules(rules);
    }
}

Feign 集成

// 定义 Feign 客户端
@FeignClient(
    value = "service-provider",
    fallback = UserServiceFallback.class
)
public interface UserService {
    
    @GetMapping("/users/{id}")
    User getUserById(@PathVariable("id") Long id);
}

// 降级实现类
@Component
public class UserServiceFallback implements UserService {
    @Override
    public User getUserById(Long id) {
        // 降级逻辑
        return new User(id, "默认用户", "服务降级");
    }
}

✅ 迁移检查清单

代码迁移

• 升级 JDK 到 17 或 21
• 替换所有 javax.* 为 jakarta.*
• 更新实体类导入语句
• 更新 Servlet 相关代码
• 更新验证注解导入（特别是 Feign 接口中的 @Valid）
• 重构 Security 配置
• 迁移 Hystrix 到 Sentinel/Resilience4j

依赖更新

• 更新 Spring Boot 到 3.x
• 更新 Spring Cloud 到 2024.x/2025.x
• 更新 Spring Cloud Alibaba 到 2023.x/2024.x
• 更新 Hibernate 到 6.1+
• 更新 MyBatis-Plus 到 3.5.5+
• 更新第三方依赖版本
• 移除 Hystrix 依赖
• 添加 Resilience4j 或 Sentinel 依赖
• 引入 spring-cloud-starter-bootstrap
• 移除 Tomcat 依赖，引入 Undertow

配置更新

• 检查 application.yml/properties
• 更新日志配置
• 更新 Actuator 配置（3.x 语法）
• 检查环境变量绑定
• 配置 Sentinel 规则
• 确认 Nacos 配置加载正常

测试验证

• 运行单元测试
• 运行集成测试
• 性能测试
• 安全测试
• 熔断降级测试
• 监控验证

📌 总结

Spring Boot 升级是一个系统性工程，需要从依赖管理、代码重构、配置调整等多个维度进行。通过本文的指南，您可以系统性地完成从 2.2 到 2.7 再到 3.x 的升级过程，确保应用的稳定性和安全性。