Spring Cloud 版本治理

概述

Spring Cloud 采用伦敦地铁站名作为版本代号（如 Hoxton、2020.0），每个大版本对应一个 Spring Boot 基线版本。版本治理是微服务架构中最容易被忽视却影响最大的基础工作。

一、版本命名规则

1.1 历史版本代号

Spring Cloud 版本	代号	Spring Boot 兼容	发布时间
Hoxton.SR12	Hoxton	2.2.x / 2.3.x	2020
2020.0.x	Ilford	2.4.x / 2.5.x	2021
2021.0.x	Jubilee	2.6.x / 2.7.x	2022
2022.0.x	Kilburn	3.0.x / 3.1.x	2023
2023.0.x	Leyton	3.2.x	2024
2024.0.x	-	3.3.x / 3.4.x	2025

1.2 版本后缀含义

后缀	含义	示例
`.0`	首个正式版	2023.0.0
`.x`	小版本递增	2023.0.1 → 2023.0.2
`-M1` / `-M2` / `-RC`	里程碑/候选版	2023.0.0-M1
`-SR1` / `-SR2`	服务版本（Hoxton 时代）	Hoxton.SR1
`-SNAPTHOT`	开发版	2023.0.0-SNAPTHOT

二、依赖管理 BOM

2.1 BOM 引入方式

xml

<!-- 方式 1：继承 Spring Boot Parent -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.0</version>
</parent>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>2023.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

xml

<!-- 方式 2：独立 BOM（不使用 Spring Boot Parent） -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>3.2.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>2023.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <!-- Spring Cloud Alibaba BOM -->
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-alibaba-dependencies</artifactId>
            <version>2023.0.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

2.2 BOM 覆盖机制

xml

<!-- 当 BOM 中某个依赖版本不合适时，可以在 dependencyManagement 中显式覆盖 -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>2023.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>

        <!-- 覆盖 Nacos 客户端版本 -->
        <dependency>
            <groupId>com.alibaba.nacos</groupId>
            <artifactId>nacos-client</artifactId>
            <version>2.3.0</version>
        </dependency>
    </dependencies>
</dependencyManagement>

三、兼容性矩阵

3.1 Spring Cloud 2023.0 (Leyton) × Spring Boot 3.2

组件	版本	说明
Spring Boot	3.2.x	最低 Java 17
Spring Cloud	2023.0.x	-
Spring Cloud LoadBalancer	4.1.x	替换已废弃的 Ribbon
Spring Cloud OpenFeign	4.1.x	需手动引入
Spring Cloud Gateway	4.1.x	基于 WebFlux
Spring Cloud Circuit Breaker	3.1.x	集成 Resilience4j
Spring Cloud Config	4.1.x	配置中心
Nacos (Alibaba)	2023.0.0.0	Spring Cloud Alibaba
Sentinel (Alibaba)	2023.0.0.0	流量控制
Resilience4j	2.2.x	断路器

3.2 关键依赖版本对照（2023.0.0）

依赖	版本
spring-cloud-commons	4.1.0
spring-cloud-openfeign-core	4.1.0
spring-cloud-gateway-server	4.1.0
spring-cloud-loadbalancer	4.1.0
spring-cloud-context	4.1.0
spring-cloud-config-server	4.1.0
spring-cloud-starter-netflix-eureka-client	4.1.0（保留但改用 Eureka 3.x）
spring-cloud-starter-bootstrap	4.1.0（需要显式引入）

四、版本迁移实战

4.1 Hoxton → 2021.0 (Jubilee) 迁移

破坏性变更清单：

变更	影响	迁移方案
Netflix Ribbon 废弃	LoadBalancer 相关功能失效	替换为 Spring Cloud LoadBalancer
Netflix Hystrix 废弃	断路器失效	替换为 Resilience4j
Zuul 废弃	API 网关失效	替换为 Spring Cloud Gateway
Spring Boot 2.3 → 2.6	配置属性变化	参考 Spring Boot 迁移指南
`feign.hystrix.enabled`	属性删除	使用 `spring.cloud.openfeign.circuitbreaker.enabled`
`spring.cloud.bootstrap.enabled`	需显式开启	引入 `spring-cloud-starter-bootstrap`

4.2 2021.0 → 2023.0 (Leyton) 迁移

破坏性变更清单：

变更	影响	迁移方案
Spring Boot 2.7 → 3.2	最低 Java 17	升级 JDK，处理 `javax.`→`jakarta.`
Java EE → Jakarta EE	`javax.servlet` → `jakarta.servlet`	全量替换 import
`SpringFactoriesLoader` 废弃	自动配置失效	迁移到 `AutoConfiguration.imports`
`@ConstructorBinding` 调整	配置属性绑定变化	检查 `@ConfigurationProperties` 用法
`spring.cloud.bootstrap.enabled`	配置语法变化	使用 `spring.config.import`

4.3 迁移步骤模板

text

1. 升级 Java 版本（Java 11 → 17）
2. 更新 pom.xml 中的 Spring Boot Parent 版本
3. 更新 spring-cloud-dependencies BOM 版本
4. 处理 javax.* → jakarta.* 包名变更
5. 将 Ribbon 替换为 LoadBalancer
6. 将 Hystrix 替换为 Resilience4j
7. 将 Zuul 替换为 Spring Cloud Gateway
8. 更新 application.yml 中的配置属性名
9. 替换自动配置（META-INF/spring.factories → META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports）
10. 更新测试代码中的 Mock/Stub

4.4 迁移检查清单

java

// 迁移后需要验证的检查点

// 检查点 1：Nacos 配置刷新
@RefreshScope
@Configuration
@ConfigurationProperties(prefix = "order")
public class OrderConfig {
    // 验证配置是否正常刷新
}

// 检查点 2：Feign 调用
@FeignClient(name = "user-service")
public interface UserFeignClient {
    // 验证 @RequestHeader / @PathVariable 是否正常工作
}

// 检查点 3：Gateway 路由
@Bean
public RouteLocator routes(RouteLocatorBuilder builder) {
    // 验证路由规则是否正常
}

// 检查点 4：断路器
@CircuitBreaker(name = "orderService", fallbackMethod = "fallback")
public Order getOrder(Long id) {
    // 验证熔断降级是否正常
}

// 检查点 5：配置中心
// 验证 @Value / @ConfigurationProperties 是否正常注入

五、踩坑实录

5.1 jakarta.* 包名变更

text

问题：Spring Boot 3.x 使用 Jakarta EE 9+，所有 javax.* 改为 jakarta.*
影响：所有使用 javax.servlet、javax.validation、javax.persistence 的代码

报错示例：
   ClassNotFoundException: javax.servlet.Filter

解决方案：
   1. 全局搜索 javax 替换为 jakarta
   2. 更新第三方依赖版本
   3. Feign 中的 Hystrix 集成类需要更新

5.2 Bootstrap 配置变更

yaml

# Spring Cloud 2022.x 之前
spring:
  cloud:
    bootstrap:
      enabled: true

# Spring Cloud 2022.x 之后
# 方式 1：引入 bootstrap starter
# <dependency>
#   <groupId>org.springframework.cloud</groupId>
#   <artifactId>spring-cloud-starter-bootstrap</artifactId>
# </dependency>

# 方式 2：使用 spring.config.import
spring:
  config:
    import: optional:nacos:order-service-dev.yaml

5.3 Circular placeholder 错误

yaml

# 错误：循环引用
spring:
  application:
    name: ${app.name}
app:
  name: ${spring.application.name}

# 正确：使用字面量
spring:
  application:
    name: order-service

5.4 Feign 断路器集成

yaml

# Spring Cloud 2022.x 前
feign:
  hystrix:
    enabled: true

# Spring Cloud 2023.x
spring:
  cloud:
    openfeign:
      circuitbreaker:
        enabled: true

六、版本管理最佳实践

6.1 统一版本管理

xml

<!-- parent pom.xml -->
<properties>
    <spring-boot.version>3.2.0</spring-boot.version>
    <spring-cloud.version>2023.0.0</spring-cloud.version>
    <spring-cloud-alibaba.version>2023.0.0.0</spring-cloud-alibaba.version>

    <!-- 覆盖 BOM 中的特定版本 -->
    <nacos-client.version>2.3.0</nacos-client.version>
    <sentinel.version>1.8.7</sentinel.version>
</properties>

6.2 版本锁定策略

text

1. 所有子模块使用 parent BOM 统一版本
2. 子模块不显式声明版本号（由 BOM 统一管理）
3. 第三方覆盖版本在 parent pom 集中管理
4. 禁止子模块单独声明 spring-cloud 依赖版本
5. 每个大版本升级准备独立的迁移分支

6.3 Checkstyle 版本检查

xml

<!-- Maven Enforcer 插件确保版本一致性 -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-enforcer-plugin</artifactId>
    <executions>
        <execution>
            <goals><goal>enforce</goal></goals>
            <configuration>
                <rules>
                    <requireJavaVersion>
                        <version>[17,)</version>
                    </requireJavaVersion>
                    <bannedDependencies>
                        <excludes>
                            <exclude>org.springframework.cloud:spring-cloud-starter-netflix-ribbon</exclude>
                            <exclude>org.springframework.cloud:spring-cloud-starter-netflix-hystrix</exclude>
                        </excludes>
                    </bannedDependencies>
                </rules>
            </configuration>
        </execution>
    </executions>
</plugin>

七、总结

知识点	说明
版本代号	Hoxton → Ilford → Jubilee → Kilburn → Leyton
BOM 管理	`spring-cloud-dependencies` 统一管理版本
Java 17	Spring Boot 3.x 最低要求
jakarta.*	javax.* 迁移到 jakarta.*
Ribbon→LoadBalancer	Netflix Ribbon 已废弃
Hystrix→Resilience4j	Netflix Hystrix 已废弃
Zuul→Gateway	Netflix Zuul 已废弃
Bootstrap→config.import	配置引导方式变更
Maven Enforcer	自动禁止使用已废弃的依赖

参考链接：
Spring Cloud 版本索引
Spring Boot 版本迁移指南
Spring Cloud 2023.0 发布说明

Spring Cloud 版本治理 ​

概述 ​

一、版本命名规则 ​

1.1 历史版本代号 ​

1.2 版本后缀含义 ​

二、依赖管理 BOM ​

2.1 BOM 引入方式 ​

2.2 BOM 覆盖机制 ​

三、兼容性矩阵 ​

3.1 Spring Cloud 2023.0 (Leyton) × Spring Boot 3.2 ​

3.2 关键依赖版本对照（2023.0.0） ​

四、版本迁移实战 ​

4.1 Hoxton → 2021.0 (Jubilee) 迁移 ​

4.2 2021.0 → 2023.0 (Leyton) 迁移 ​

4.3 迁移步骤模板 ​

4.4 迁移检查清单 ​

五、踩坑实录 ​

5.1 jakarta.* 包名变更 ​

5.2 Bootstrap 配置变更 ​

5.3 Circular placeholder 错误 ​

5.4 Feign 断路器集成 ​

六、版本管理最佳实践 ​

6.1 统一版本管理 ​

6.2 版本锁定策略 ​

6.3 Checkstyle 版本检查 ​

七、总结 ​

Spring Cloud 版本治理

概述

一、版本命名规则

1.1 历史版本代号

1.2 版本后缀含义

二、依赖管理 BOM

2.1 BOM 引入方式

2.2 BOM 覆盖机制

三、兼容性矩阵

3.1 Spring Cloud 2023.0 (Leyton) × Spring Boot 3.2

3.2 关键依赖版本对照（2023.0.0）

四、版本迁移实战

4.1 Hoxton → 2021.0 (Jubilee) 迁移

4.2 2021.0 → 2023.0 (Leyton) 迁移

4.3 迁移步骤模板

4.4 迁移检查清单

五、踩坑实录

5.1 jakarta.* 包名变更

5.2 Bootstrap 配置变更

5.3 Circular placeholder 错误

5.4 Feign 断路器集成

六、版本管理最佳实践

6.1 统一版本管理

6.2 版本锁定策略

6.3 Checkstyle 版本检查

七、总结