Spring Cloud 2025.0.3 (Northfields) 发布：升级路径与实战配置

预计阅读时间：9 分钟

Spring Cloud 2025.0.3 作为 Northfields 版本线的第三个补丁版本已正式发布。这个版本线对应 Spring Boot 3.5.x，对微服务开发者来说，它意味着一系列依赖兼容性修复和组件稳定性提升。如果你已经在 2025.0.0 或 2025.0.1/2 上运行，这次升级成本很低；如果还在 2024.0.x (Moorgate) 甚至更早的版本线上，现在是一个值得规划迁移的节点。

版本线定位：2025.0.x 与 Spring Boot 3.5 的绑定关系

Spring Cloud 的版本列车与 Spring Boot 版本是严格绑定的。2025.0.x 整条线基于 Spring Boot 3.5.x 和 Spring Framework 7.x。这意味着：

Jakarta EE 11 基线——Servlet、JPA 等命名空间全部是 jakarta.*，不再有 javax.* 残留。
Java 17 是最低要求，Java 21 是推荐运行版本，虚拟线程（Project Loom）在 Spring Boot 3.5 中已默认可用。
Native Image 支持通过 Spring Native / AOT 编译继续成熟，Gateway、Config 等核心组件的 GraalVM 兼容性在本版本线中持续改善。

2025.0.3 作为补丁版本，核心变化集中在：各子项目（Config、Gateway、OpenFeign、Circuit Breaker 等）的 bug fix、依赖版本对齐、以及与 Spring Boot 3.5.3 的兼容性校准。它不引入新功能，但解决了一些在 2025.0.0-2 中报告的生产问题。

核心子项目版本一览

以下是 2025.0.3 中各子项目的版本坐标（以 Maven 为例）：

子项目	版本
Spring Cloud Config	2025.0.3
Spring Cloud Gateway	2025.0.3
Spring Cloud OpenFeign	2025.0.3
Spring Cloud Circuit Breaker	2025.0.3
Spring Cloud Netflix (Eureka)	2025.0.3
Spring Cloud Stream	2025.0.3
Spring Cloud Commons	2025.0.3
Spring Cloud Kubernetes	2025.0.3

所有子项目在同一版本列车下版本号统一，这是 Spring Cloud 版本管理的惯例——你不需要单独指定每个子项目的版本，只需声明 spring-cloud-dependencies BOM。

从零搭建：最小可运行项目示例

下面给出一个基于 Spring Cloud 2025.0.3 的最小微服务组合：一个 Eureka 注册中心 + 一个服务提供者 + 一个 Gateway 网关。代码可直接复制运行。

Maven 依赖配置

<!-- pom.xml -->
<project>
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.5.3</version>
  </parent>

  <groupId>com.example</groupId>
  <artifactId>spring-cloud-2025-demo</artifactId>
  <version>0.0.1</version>
  <packaging>pom</packaging>

  <properties>
    <java.version>21</java.version>
    <spring-cloud.version>2025.0.3</spring-cloud.version>
  </properties>

  <dependencyManagement>
    <dependencies>
      <!-- 一行 BOM 锁定所有子项目版本 -->
      <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>
</project>

关键点：spring-cloud.version 只需设为 2025.0.3，BOM 会自动把 Config、Gateway、Eureka 等全部对齐。不要手动指定子项目版本号，否则会打破版本列车的一致性。

Eureka Server——注册中心

// eureka-server/src/main/java/com/example/EurekaServerApp.java
package com.example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.netflix.eureka.server.EnableEurekaServer;

@SpringBootApplication
@EnableEurekaServer
public class EurekaServerApp {
    public static void main(String[] args) {
        SpringApplication.run(EurekaServerApp.class, args);
    }
}

# eureka-server/src/main/resources/application.yml
server:
  port: 8761

eureka:
  instance:
    hostname: localhost
  client:
    register-with-eureka: false
    fetch-registry: false
    service-url:
      defaultZone: http://${eureka.instance.hostname}:${server.port}/eureka/

对应 Maven 子模块依赖：

<dependencies>
  <dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-netflix-eureka-server</artifactId>
  </dependency>
</dependencies>

服务提供者——注册到 Eureka

// provider/src/main/java/com/example/ProviderApp.java
package com.example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.netflix.eureka.EnableEurekaClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
@EnableEurekaClient
public class ProviderApp {
    public static void main(String[] args) {
        SpringApplication.run(ProviderApp.class, args);
    }
}

@RestController
class HelloController {
    @GetMapping("/hello")
    public String hello() {
        return "Hello from Spring Cloud 2025.0.3!";
    }
}

# provider/src/main/resources/application.yml
spring:
  application:
    name: hello-provider

server:
  port: 8081

eureka:
  client:
    service-url:
      defaultZone: http://localhost:8761/eureka/

Spring Cloud Gateway——网关路由

// gateway/src/main/java/com/example/GatewayApp.java
package com.example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

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

# gateway/src/main/resources/application.yml
server:
  port: 8080

spring:
  application:
    name: gateway
  cloud:
    gateway:
      routes:
        - id: hello-route
          uri: lb://hello-provider   # lb:// 表示从 Eureka 拉取实例列表
          predicates:
            - Path=/api/hello
          filters:
            - StripPrefix=1           # /api/hello → /hello

eureka:
  client:
    service-url:
      defaultZone: http://localhost:8761/eureka/

启动顺序：Eureka Server → Provider → Gateway。访问 http://localhost:8080/api/hello，Gateway 会从 Eureka 发现 hello-provider 实例并转发请求，返回 "Hello from Spring Cloud 2025.0.3!"。

从旧版本线升级的注意事项

如果你从 2024.0.x (Moorgate) 或更早版本升级到 2025.0.x，有几件事必须提前排查：

1. Spring Boot 基线跳跃

2024.0.x 基于 Spring Boot 3.4.x，2025.0.x 基于 3.5.x。先单独把 Boot 从 3.4 升到 3.5，确认应用正常运行，再切换 Cloud BOM。两步走比一步到位更容易定位问题。

2. OpenFeign 的迁移

Spring Cloud OpenFeign 在 2025.0.x 中继续维护，但官方已明确推荐新项目使用 Spring Cloud 6.1+ 的声明式 HTTP 客户端（基于 Spring Framework 的 HttpInterface）。如果你有大量 Feign 接口，短期内继续用没问题；长期规划中建议逐步迁移。

3. Circuit Breaker 实现

Resilience4J 仍是 Spring Cloud Circuit Breaker 的默认实现。如果你之前用了 Sentinel 或其他自定义实现，确认对应适配器版本与 2025.0.3 BOM 兼容。

4. 配置中心加密

Spring Cloud Config 在 2025.0.x 中对加密/解密的支持有调整——对称加密的配置方式有变更，不对称加密的 keystore 格式推荐使用 PKCS12。升级前检查 encrypt.key 相关配置。

升级检查清单

检查项	动作
Spring Boot 版本	升至 3.5.x，先独立验证
`spring-cloud.version`	改为 `2025.0.3`
子项目版本号	删除所有手动指定的子项目版本，让 BOM 管理
`javax.*` 引用	全部替换为 `jakarta.*`（2025.0.x 不再有兼容层）
Java 运行版本	最低 17，推荐 21
Feign 接口	短期可保留，长期规划迁移到 HttpInterface
Config 加密配置	检查 `encrypt.key` 和 keystore 格式
测试覆盖	重点跑集成测试——注册发现、网关路由、配置拉取

小结

Spring Cloud 2025.0.3 是一条成熟版本线上的稳定性补丁，适合已经在 2025.0.x 上的团队直接升级，也适合从 2024.0.x 规划跨版本迁移的团队作为目标版本。升级的核心工作量不在 Cloud 本身，而在 Spring Boot 3.5 的基线适配——先把 Boot 稳住，Cloud 的切换只是改一行 BOM 版本号。