> ## Documentation Index
> Fetch the complete documentation index at: https://blog.pig4cloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Spring cloud 2025

Spring Cloud 2025.0.0 "Northfields" 于 2025年5月29日正式发布，完全兼容 Spring Boot 3.5.0。本版本在微服务架构的多个核心组件上进行了重要改进和功能增强。

## 版本兼容性

* **Spring Boot**: 3.5.0
* **发布代号**: Northfields (按字母顺序命名传统)
* **主要变更**: 包含破坏性变更，不支持平滑升级，**细节请看这篇文章**

## Spring Cloud Gateway 重大更新

### 新增功能

#### 1. Function & Stream 处理器集成

Gateway 现在原生支持 `spring-cloud-function` 和 `spring-cloud-stream` 处理器：

```yaml theme={null}
spring:
  cloud:
    gateway:
      routes:
        - id: function-route
          uri: function://myFunction
          predicates:
            - Path=/api/process/**
        - id: stream-route
          uri: stream://myStreamProcessor
          predicates:
            - Path=/api/stream/**
```

**技术优势**:

* 支持函数式编程模型处理请求
* 集成消息驱动架构 (Kafka, RabbitMQ)
* 简化 Serverless 和事件驱动架构实现

#### 2. Bucket4j 限流器支持

WebFlux 版本新增 Bucket4j 令牌桶算法支持：

```yaml theme={null}
spring:
  cloud:
    gateway:
      server:
        webflux:
          routes:
            - id: rate-limited-route
              uri: http://backend-service
              filters:
                - name: Bucket4jRateLimit
                  args:
                    capacity: 100
                    refill-rate: 10
                    refill-period: PT1S
```

### 重要弃用

#### 1. WebClientRouting 基础设施

* **状态**: 已弃用，5.0 版本将移除
* **影响**: 依赖此基础设施的路由逻辑需要迁移
* **建议**: 使用 Gateway 提供的标准路由机制

#### 2. 模块和启动器重命名

为明确区分 Web 技术栈和工作模式，引入新的命名规范：

| 旧名称                                       | 新名称                                           | 说明            |
| ----------------------------------------- | --------------------------------------------- | ------------- |
| `spring-cloud-gateway-server`             | `spring-cloud-gateway-server-webflux`         | WebFlux 服务器模式 |
| `spring-cloud-gateway-server-mvc`         | `spring-cloud-gateway-server-webmvc`          | WebMVC 服务器模式  |
| `spring-cloud-starter-gateway-server`     | `spring-cloud-starter-gateway-server-webflux` | WebFlux 启动器   |
| `spring-cloud-starter-gateway-server-mvc` | `spring-cloud-starter-gateway-server-webmvc`  | WebMVC 启动器    |
| `spring-cloud-gateway-mvc`                | `spring-cloud-gateway-proxyexchange-webmvc`   | WebMVC 代理交换   |
| `spring-cloud-gateway-webflux`            | `spring-cloud-gateway-proxyexchange-webflux`  | WebFlux 代理交换  |

### 破坏性变更

#### X-Forwarded-\* 头部默认禁用

出于安全考虑，X-Forwarded-\* 和 Forwarded 头部功能默认禁用。

**配置受信任代理**:

```yaml theme={null}
# WebFlux 版本
spring:
  cloud:
    gateway:
      server:
        webflux:
          trusted-proxies: "192\\.168\\..*|10\\..*"

# WebMVC 版本 (4.1.x+)
spring:
  cloud:
    gateway:
      mvc:
        trusted-proxies: "192\\.168\\..*|10\\..*"
```

**安全影响**: 防止恶意伪造代理头部，需要显式配置信任边界。但如果下游业务有依赖此请求头，请及时处理。

## Spring Cloud Config 增强

### AWS S3 YAML Profile 支持

Config Server 现在支持从 S3 读取 profile 特定的 YAML 文件：

```yaml theme={null}
spring:
  cloud:
    config:
      server:
        awss3:
          bucket: my-config-bucket
          region: us-west-2
```

**文件结构示例**:

```
s3://my-config-bucket/
├── application.yaml
├── application-dev.yaml
├── application-prod.yaml
└── application-test.yaml
```

Config Server 将根据激活的 profile 自动加载对应配置文件。

## Spring Cloud Kubernetes 更新

### 组合配置源支持

Kubernetes ConfigMap 和 Secret 现在可作为组合配置源：

```yaml theme={null}
spring:
  cloud:
    kubernetes:
      config:
        sources:
          - name: app-config
            namespace: default
          - name: db-secret
            namespace: default
            explicit-prefix: database
```

**配置优先级**:

1. 命令行参数
2. 系统属性
3. Kubernetes ConfigMap/Secret
4. application.yaml
5. 默认值

## Spring Cloud Circuitbreaker 新特性

### 响应式隔离支持

新增对响应式编程模式支持：

```java theme={null}
@Component
public class ReactiveService {
    
    @Autowired
    private ReactiveCircuitBreakerFactory circuitBreakerFactory;
    
    public Mono<String> callExternalService() {
        return circuitBreakerFactory
            .create("external-service")
            .run(
                webClient.get().uri("/api/data").retrieve().bodyToMono(String.class),
                throwable -> Mono.just("fallback-response")
            );
    }
}
```

**配置示例**:

```yaml theme={null}
resilience4j:
  bulkhead:
    instances:
      external-service:
        max-concurrent-calls: 10
        max-wait-duration: 1000ms
```

## Spring Cloud Netflix 改进

### Eureka 客户端增强

支持 Apache HTTP Client 5 的 RequestConfig 定制：

```java theme={null}
@Bean
public EurekaClientHttpRequestFactorySupplier customRequestFactorySupplier() {
    return () -> {
        RequestConfig requestConfig = RequestConfig.custom()
            .setConnectTimeout(5000)
            .setSocketTimeout(10000)
            .setConnectionRequestTimeout(3000)
            .build();
        
        return new HttpComponentsClientHttpRequestFactory(
            HttpClients.custom()
                .setDefaultRequestConfig(requestConfig)
                .build()
        );
    };
}
```

## 版本更新清单

所有模块已更新至最新版本以确保与 Spring Boot 3.5.0 兼容：

| 模块名称                        | 版本       |
| --------------------------- | -------- |
| Spring Cloud Config         | 4.3.0    |
| Spring Cloud Gateway        | 4.3.0    |
| Spring Cloud Kubernetes     | 3.3.0    |
| Spring Cloud Circuitbreaker | 3.3.0    |
| Spring Cloud Netflix        | 4.3.0    |
| Spring Cloud Build          | 4.3.0    |
| Spring Cloud Openfeign      | 4.3.0    |
| Spring Cloud Stream         | 4.3.0    |
| Spring Cloud Commons        | 4.3.0    |
| Spring Cloud Contract       | 4.3.0    |
| Spring Cloud Consul         | 4.3.0    |
| Spring Cloud Vault          | 4.3.0    |
| Spring Cloud Function       | 4.3.0    |
| Spring Cloud Bus            | 4.3.0    |
| Spring Cloud Zookeeper      | 4.3.0    |
| Spring Cloud Task           | 3.3.0    |
| Spring Cloud Starter Build  | 2025.0.0 |

## 升级指南

### 前置条件

1. **升级 Spring Boot 至 3.5.0**
2. **Java 版本**: 确保使用 Java 17+

### 升级步骤

#### 1. 更新 BOM 版本

```xml theme={null}
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>2025.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
```

#### 2. Gateway 模块迁移

```xml theme={null}
<!-- 旧依赖 -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>

<!-- 新依赖 -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway-server-webflux</artifactId>
</dependency>
```

#### 3. 配置属性迁移

```yaml theme={null}
# 旧配置
spring:
  cloud:
    gateway:
      routes:
        - id: example
          uri: http://example.com

# 新配置  
spring:
  cloud:
    gateway:
      server:
        webflux:
          routes:
            - id: example
              uri: http://example.com
```

#### 4. 安全配置更新

```yaml theme={null}
spring:
  cloud:
    gateway:
      server:
        webflux:
          trusted-proxies: "10\\..*|192\\.168\\..*"
```

#### 5. Spring Cloud Alibaba 兼容性注意事项

如果您的项目集成了 Spring Cloud Alibaba 组件，需特别注意 Spring Cloud 2025.0.0 与 Spring Cloud Alibaba 2023.0.3 版本之间存在日志依赖冲突问题，可能导致应用启动失败。

解决方案：

1. 可参考 PIG 微服务平台的解决方案 ([https://gitee.com/log4j/pig/tree/jdk17-dev](https://gitee.com/log4j/pig/tree/jdk17-dev))
2. 或通过显式排除冲突依赖并引入兼容版本
3. 等待 Spring Cloud Alibaba 发布完全兼容的 2025.x 版本 （没啥希望了～）

![dCnrLJ](https://minio.pigx.vip/oss/202505/dCnrLJ.png)