Spring Cloud 2025.1.2：Boot 4 微服务升级，先把 Cloud 底座升稳

分享日期：2026-06-13
主题：Java / Spring Cloud 2025.1.2 / Spring Boot 4 / Gateway / Config / OpenFeign / Agent 平台治理

1. 为什么今天值得关注

Spring Cloud 2025.1.2 已在 2026-06-12 发布。官方 release train 文档显示，这一版的 Release Train Version 是 2025.1.2，Supported Boot Version 是 4.0.7；Spring Cloud 项目页也把 2025.1.x 标为 Oakwood，并映射到 Spring Boot 4.0.x。

这条信息很关键：Spring Boot 4.1.0 同样在 2026-06-10 成为最新 GA，但微服务团队不能只看 Boot 最新版本就把所有 Cloud 应用一起推上去。Spring Cloud 的网关、配置中心、OpenFeign、Stream、CircuitBreaker、Kubernetes、Vault 等组件构成的是一条 release train。分布式系统升级时，版本组合比单点版本更重要。

一句话：今天的热点不是“Spring Cloud 又发了一个服务版本”，而是 Oakwood 给 Boot 4 微服务体系提供了一个更明确的稳定升级窗口。

2. 版本背景：Boot 4.1 很新，Cloud 2025.1.2 更适合做底座

截至今天，官方页面给出的关键事实可以归纳为三点：

• Spring Boot GitHub Releases 把 v4.1.0 标为最新版本，发布时间是 2026-06-10。
• Spring Cloud GitHub Releases 把 v2025.1.2 标为最新版本，发布时间是 2026-06-12。
• Spring Cloud 2025.1.2 参考文档标注的 Supported Boot Version 是 4.0.7。

这意味着升级路径要分两层处理：

1. Cloud 体系应用：网关、配置中心、注册发现、声明式 HTTP、消息、任务、Kubernetes 集成等，优先按 Spring Boot 4.0.7 + Spring Cloud 2025.1.2 做基线。
2. 非 Cloud 或低耦合服务：可以单独验证 Spring Boot 4.1 的新特性，例如 gRPC、HTTP Client SSRF 防护、可观测性增强等。

不要把 Boot 4.1 的热度直接等同于“Cloud 全量服务今天就该上 4.1”。更稳妥的做法是：先把微服务底座升到 Oakwood 当前服务版本，再为 Boot 4.1 建立单独的兼容性验证分支。

3. Oakwood 这次覆盖了哪些组件

2025.1.2 release train 中，官方列出的核心组件版本包括：

• Spring Cloud Gateway 5.0.2
• Spring Cloud Config 5.0.4
• Spring Cloud Stream 5.0.2
• Spring Cloud CircuitBreaker 5.0.2
• Spring Cloud Function 5.0.3
• Spring Cloud OpenFeign 5.0.2
• Spring Cloud Kubernetes 5.0.2
• Spring Cloud Vault 5.0.2
• Spring Cloud Bus 5.0.2
• Spring Cloud Contract 5.0.3

这类 release train 的价值在于：团队不需要逐个组件猜版本，而是通过 spring-cloud-dependencies BOM 固定一组经过整理的依赖组合。

Maven 示例：

<properties>
    <java.version>25</java.version>
    <spring-boot.version>4.0.7</spring-boot.version>
    <spring-cloud.version>2025.1.2</spring-cloud.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>${spring-boot.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>${spring-cloud.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Gradle 示例：

plugins {
    id 'java'
    id 'org.springframework.boot' version '4.0.7'
    id 'io.spring.dependency-management' version '1.1.7'
}

ext {
    set('springCloudVersion', '2025.1.2')
}

dependencyManagement {
    imports {
        mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
    }
}

如果团队使用 Maven parent 管理 Boot 版本，也可以继续用 spring-boot-starter-parent，再单独导入 Spring Cloud BOM。关键点是：不要让 Cloud 组件靠传递依赖自然漂移。

4. 推荐升级拓扑

flowchart LR
    Client[用户 / 前端 / 外部系统] --> Gateway[Spring Cloud Gateway 5.0.2]
    Gateway --> Auth[鉴权 / Token Relay / 限流]
    Gateway --> ServiceA[Boot 4.0.7 业务服务]
    Gateway --> AgentApi[Agent API 服务]
    Config[Spring Cloud Config 5.0.4] --> Gateway
    Config --> ServiceA
    Config --> AgentApi
    Vault[Spring Cloud Vault 5.0.2] --> AgentApi
    Circuit[Spring Cloud CircuitBreaker 5.0.2] --> ServiceA
    Stream[Spring Cloud Stream 5.0.2] --> Worker[异步任务 / Agent 工具执行]
    AgentApi --> Model[模型供应商 API]
    AgentApi --> Tools[内部工具 / MCP Server]

这张图表达的是一个升级思路：Cloud 先承担系统边界和运行治理，再让业务服务逐步迁移。

• Gateway 负责统一入口、安全头、限流、熔断、灰度路由、请求大小限制和 Token Relay。
• Config 负责模型参数、工具开关、第三方端点、灰度比例和组件开关的外部化配置。
• Vault 负责模型密钥、API token、数据库凭证和 webhook secret。
• CircuitBreaker 负责模型供应商、内部工具、下游服务的超时、失败和降级。
• Stream/Function 负责长耗时 Agent 任务、批处理、异步工具调用和事件驱动链路。

5. Gateway：先把入口治理升到 Boot 4 时代

Spring Cloud Gateway 5.0.2 的文档明确说明，它基于 Spring Framework 7、Spring Boot 4 和 Reactor 构建；同时提供 Server 和 Proxy Exchange 两种形态，每种形态又覆盖 WebFlux 和 Web MVC。

升级 Gateway 时建议先确认四件事：

5.1 WebFlux 还是 Web MVC

如果网关已经是 Reactive 体系，继续使用 Gateway Server WebFlux 更自然；如果团队主力应用是 Servlet/Web MVC，并且网关只承担局部代理能力，则可以评估 Gateway Server Web MVC 或 Proxy Exchange。

不要为了“统一技术栈”机械迁移。网关的核心是边界治理，选择标准应该是当前请求模型、过滤器生态、团队排障经验和性能压测结果。

5.2 路由规则从“能转发”升级为“能治理”

典型路由不要只写 Path 和 uri，至少要补齐：

• RequestRateLimiter 或业务侧限流策略。
• CircuitBreaker 和 fallback。
• Retry 的幂等性边界。
• RequestSize 和 RequestHeaderSize。
• SecureHeaders 和响应头清理。
• TokenRelay 或统一认证上下文传播。

示例：

spring:
  cloud:
    gateway:
      server:
        webflux:
          routes:
            - id: agent-api
              uri: http://agent-api:8080
              predicates:
                - Path=/agent/**
              filters:
                - StripPrefix=1
                - name: CircuitBreaker
                  args:
                    name: agentApi
                    fallbackUri: forward:/fallback/agent
                - name: RequestSize
                  args:
                    maxSize: 2MB
                - TokenRelay=

配置属性名需要以项目实际采用的 Gateway 形态为准。升级时不要只复制旧配置，先在测试环境打开配置元数据校验和启动失败策略。

5.3 观测维度要按入口组织

Gateway 升级后，应该把这些指标拉进仪表盘：

• route id 维度的请求量、延迟、错误率。
• downstream uri 维度的超时和熔断次数。
• 4xx、5xx、限流、请求体过大、认证失败的分布。
• trace id 在 Gateway、业务服务、Agent 工具服务之间的贯通率。

只有业务服务升级成功并不代表微服务升级成功。入口层的观测断了，问题会在生产环境被放大。

6. Config：把“配置中心”当成运行控制面

Spring Cloud Config 5.0.4 仍然提供基于 HTTP resource 的外部化配置能力，可以嵌入 Spring Boot 应用并通过 @EnableConfigServer 启动。对 Boot 4 微服务升级来说，Config 不只是集中放 YAML 的地方，而应该成为运行控制面。

建议把配置分成四类：

1. 基础运行配置：端口、连接池、线程池、超时、日志级别。
2. 流量治理配置：灰度比例、限流阈值、熔断参数、fallback 策略。
3. Agent 配置：模型供应商、模型名、temperature、max tokens、工具白名单、RAG 检索 topK。
4. 安全配置引用：密钥不要直接进 Git，配置中心只保留 Vault、KMS、Secret Manager 的引用。

Config Server 最小形态：

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.config.server.EnableConfigServer;

@SpringBootApplication
@EnableConfigServer
public class ConfigServerApplication {

    public static void main(String[] args) {
        SpringApplication.run(ConfigServerApplication.class, args);
    }
}

配置示例：

server:
  port: 8888

spring:
  cloud:
    config:
      server:
        git:
          uri: https://git.example.com/platform/config-repo.git

生产环境里还需要补齐：访问控制、审计日志、配置变更审批、配置刷新策略、密钥轮换、回滚脚本和 Config Server 自身的高可用。

7. OpenFeign：能用，但新项目要评估 HTTP Interface

Spring Cloud OpenFeign 仍在 Oakwood release train 中，但官方 OpenFeign 文档已经明确：OpenFeign 项目被视为 feature-complete，后续主要添加 bugfix 和少量社区特性，并建议迁移到 Spring HTTP Service Clients。

这不是说现有 Feign 代码要马上重写。更合理的策略是：

• 已上线的 OpenFeign 客户端先完成 Boot 4 / Cloud 2025.1.2 编译、启动、契约和超时重试验证。
• 新增内部 HTTP 客户端优先评估 Spring Framework 的 HTTP Interface 或 Spring Boot 管理下的 RestClient。
• 对核心下游调用，把超时、重试、熔断、鉴权、日志脱敏、trace 传播从接口注解里抽到统一配置。

一个典型 HTTP Interface：

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;

public interface InventoryClient {

    @GetMapping("/items/{sku}")
    InventoryItem getItem(@PathVariable String sku);
}

这类迁移不要追求一次性全量完成。Feign 是工程存量，HTTP Interface 是新增方向。先把边界和治理统一起来，比改写所有接口更重要。

8. 对 Agent 平台的实际意义

Java Agent 应用最容易失控的地方不是“模型怎么调”，而是“模型能影响哪些出站调用”。Spring Cloud 2025.1.2 这类底座升级，可以把 Agent 出站治理纳入微服务体系。

建议给 Agent 平台建立四条硬边界：

8.1 工具入口走 Gateway

内部工具、MCP Server、文档服务、工单系统、订单系统不要直接暴露给 Agent 编排服务。统一从 Gateway 或内部服务网关进入，便于做鉴权、限流、审计、熔断和灰度。

8.2 模型和工具开关走 Config

模型名、供应商、工具白名单、灰度开关、RAG 检索参数、最大 token 数，不应该写死在业务代码里。它们变化频繁，且风险高，适合走配置中心和审批流程。

示例：

agent:
  model:
    provider: openai-compatible
    name: approved-chat-model
    temperature: 0.2
  tools:
    enabled:
      - ticket.search
      - inventory.read
    disabled:
      - payment.refund
  guardrails:
    max-tool-calls: 5
    require-human-approval:
      - order.cancel
      - payment.refund

8.3 密钥和供应商凭证走 Vault

模型 API key、OAuth client secret、内部系统 token、webhook secret 不要进 Git 配置仓库。Cloud Vault 或企业现有 secret manager 应该成为 Agent 平台的必选组件。

8.4 长任务走 Stream

Agent 生成报告、批量检索、异步调用工具、处理文档导入时，不要把所有工作压在一次 HTTP 请求里。用 Spring Cloud Stream 或任务队列承接长耗时动作，能把超时、重试、幂等和补偿做清楚。

9. 升级检查清单

第一天先做版本基线：

• 统一 JDK、Spring Boot、Spring Cloud BOM 和构建插件版本。
• 确认 Cloud 服务目标组合是 Boot 4.0.7 + Cloud 2025.1.2。
• 把 Boot 4.1 验证放到单独分支，不和 Cloud 底座升级混在同一个变更里。

第二天做组件盘点：

• 列出 Gateway、Config、OpenFeign、Stream、Function、Kubernetes、Vault、CircuitBreaker 使用点。
• 标记哪些是入口层、哪些是核心链路、哪些是内部辅助链路。
• 统计自定义 filter、interceptor、decoder、encoder、retryer、error handler。

第三天做编译和启动：

• 打开 -Werror 或等价的弃用 API 报警策略。
• 使用配置属性元数据和启动失败策略暴露配置变更。
• 先跑 Config Server、Gateway、认证服务，再跑业务服务。

第四天做契约和流量回放：

• 用 Spring Cloud Contract 或现有契约测试验证消费者和生产者。
• 对 Gateway 路由做录制流量回放。
• 检查请求头、trace id、认证上下文和错误码是否保持兼容。

第五天做安全：

• 检查 Gateway 暴露的 actuator、fallback、error endpoint。
• 检查 Config Server 权限、配置仓库权限和密钥泄漏。
• 检查 Agent 工具白名单、SSRF 防护、出站域名 allowlist。

第六天做性能和稳定性：

• 压测 Gateway 路由、Config 拉取、声明式 HTTP 客户端、消息消费。
• 验证熔断、限流、重试、超时、fallback 的组合行为。
• 观测 JVM、Netty/Reactor、线程池、连接池、GC 和 Micrometer 指标。

第七天做灰度：

• 先升级非核心服务和内部工具服务。
• Gateway 开启小流量灰度，保留快速回滚路由。
• Config 变更必须可回滚，关键开关必须可在分钟级恢复。

10. 常见坑

• 只升 Boot，不升 Cloud BOM：编译可能过，运行时配置、网关、HTTP 客户端和观测链路会出现隐性不兼容。
• 看到 Boot 4.1 最新就全量升级：Cloud 2025.1.2 文档当前标注支持 Boot 4.0.7，Cloud 服务应先按这个组合验证。
• 忽视 Jackson 3 和 Jakarta 基线变化：序列化、反序列化、校验、Servlet API、第三方 starter 都可能受影响。
• 网关配置复制旧版本：Gateway 形态、属性命名、filter 行为需要逐项验证。
• Feign 客户端只看接口能不能调用：超时、重试、错误解码、trace 传播、日志脱敏同样是升级范围。
• Agent 工具绕过微服务治理：模型触发的工具调用必须进入权限、审计、限流、熔断和出站访问控制。

11. 给团队的落地建议

如果团队已经在 Spring Boot 3.5 / Spring Cloud 2025.0.x 上，下一步不要直接追 Boot 4.1，而是先建立一条 Boot 4.0.7 + Cloud 2025.1.2 的验证线。把 Gateway、Config、OpenFeign、Stream、Vault 这几个共享组件先跑稳，再让业务服务分批进入。

如果团队还在 Spring Boot 2.x 或早期 3.x，建议把升级拆成两段：先到当前仍受支持的 Boot 3.5 / Cloud 2025.0.x，清理 Jakarta、观测、配置和 HTTP 客户端问题，再规划 Boot 4 / Oakwood。跨太多代一起升，出问题时很难定位是 JDK、Boot、Cloud、第三方库还是业务代码造成的。

对正在做 Agent 平台的 Java 团队，Spring Cloud 2025.1.2 的价值在于：它让 Agent 工具调用、模型出站访问、配置开关、密钥管理、异步任务和网关治理可以继续落在熟悉的 Spring 微服务工程体系里。Agent 可以新，底座要稳。

资料来源

• Spring Cloud GitHub Releases：v2025.1.2 于 2026-06-12 发布，并列出 Gateway 5.0.2、Config 5.0.4、Stream 5.0.2 等组件版本。
  https://github.com/spring-cloud/spring-cloud-release/releases
• Spring Cloud 2025.1.2 Reference：标注 Release Train Version 2025.1.2，Supported Boot Version 4.0.7，并列出各项目参考文档版本。
  Spring Cloud Train Reference Documentation :: Spring Cloud Release
• Spring Cloud 项目页：说明 2025.1.x aka Oakwood 对应 Spring Boot 4.0.x，并推荐使用 spring-cloud-dependencies BOM。
  Spring Cloud
• Spring Cloud Gateway Reference：Gateway 5.0.2 基于 Spring Framework 7、Spring Boot 4 和 Reactor，并提供 WebFlux / Web MVC 形态。
  Spring Cloud Gateway :: Spring Cloud Gateway
• Spring Cloud OpenFeign Reference：OpenFeign 被视为 feature-complete，官方建议新方向评估 Spring HTTP Service Clients。
  Spring Cloud OpenFeign :: Spring Cloud Openfeign
• Spring Boot GitHub Releases：v4.1.0 于 2026-06-10 发布，并标为 latest。
  https://github.com/spring-projects/spring-boot/releases