Spring Cloud 速查表

本文档提供 Spring Cloud 常用配置的快速参考，基于 Spring Cloud 2024.x / 2025.x 版本。

版本对应

Release Train	代号	Spring Boot	JDK	状态
2025.1.x	Oakwood	4.0.x	21+	最新
2025.0.x	Northfields	3.5.x	17+	维护中
2024.0.x	Moorgate	3.4.x	17+	维护中
2023.0.x	Leyton	3.3.x, 3.2.x	17+	维护中
2022.0.x	Kilburn	3.0.x, 3.1.x	17+	EOL
2021.0.x	Jubilee	2.6.x, 2.7.x	8+	EOL

版本选择建议：新项目使用最新稳定版（2024.0.x 或 2025.0.x），存量项目根据 Spring Boot 版本选择对应的 Spring Cloud 版本。务必确保版本匹配，版本不匹配会导致各种不可预期的错误。

查看最新版本：访问 Spring Cloud 官网获取最新版本信息。

Maven 依赖

Spring Cloud BOM

<properties>
    <spring-cloud.version>2024.0.0</spring-cloud.version>
</properties>

<dependencyManagement>
    <dependencies>
        <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>

Spring Cloud Alibaba BOM

<properties>
    <spring-cloud-alibaba.version>2023.0.3.2</spring-cloud-alibaba.version>
</properties>

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

常用 Starter

Starter	用途
`spring-cloud-starter-netflix-eureka-server`	Eureka 服务端
`spring-cloud-starter-netflix-eureka-client`	Eureka 客户端
`spring-cloud-starter-gateway`	API 网关
`spring-cloud-starter-loadbalancer`	负载均衡
`spring-cloud-starter-openfeign`	声明式 HTTP 客户端
`spring-cloud-starter-config`	配置中心客户端
`spring-cloud-starter-circuitbreaker-resilience4j`	断路器
`spring-cloud-starter-alibaba-nacos-discovery`	Nacos 服务发现
`spring-cloud-starter-alibaba-nacos-config`	Nacos 配置中心
`spring-cloud-starter-alibaba-sentinel`	Sentinel 流控

Spring Cloud Alibaba

版本对应

Spring Cloud Alibaba	Spring Cloud	Spring Boot
2023.0.1.0	2023.0.x	3.2.x
2022.0.0.0	2022.0.x	3.0.x
2021.0.5.0	2021.0.x	2.6.x

详细版本对应请参考 Spring Cloud Alibaba 官方文档。

Nacos 服务发现

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>

配置

spring:
  application:
    name: user-service
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848
        namespace: dev
        group: DEFAULT_GROUP
        cluster-name: DEFAULT
        weight: 1
        metadata:
          version: v1
          zone: shanghai

常用配置项

配置项	说明	默认值
`server-addr`	Nacos Server 地址	-
`namespace`	命名空间 ID	public
`group`	分组	DEFAULT_GROUP
`cluster-name`	集群名	DEFAULT
`weight`	权重	1
`ephemeral`	是否临时实例	true
`heart-beat-interval`	心跳间隔	5000ms
`ip-delete-timeout`	IP 删除超时	30000ms

Nacos 配置中心

依赖

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>

配置

spring:
  application:
    name: user-service
  profiles:
    active: dev
  cloud:
    nacos:
      config:
        server-addr: localhost:8848
        file-extension: yml
        namespace: dev
        group: DEFAULT_GROUP
        shared-configs:
          - data-id: common.yml
            refresh: true
        extension-configs:
          - data-id: database.yml
            refresh: true

动态刷新

@RestController
@RefreshScope
public class ConfigController {

    @Value("${app.config.value:default}")
    private String configValue;
}

Spring Cloud Gateway

依赖

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>

路由配置

spring:
  cloud:
    gateway:
      routes:
        - id: user-service
          uri: lb://user-service
          predicates:
            - Path=/user/**
          filters:
            - StripPrefix=1
      discovery:
        locator:
          enabled: true
          lower-case-service-id: true

断言工厂

断言	示例
Path	`Path=/user/**`
Method	`Method=GET,POST`
Header	`Header=X-Request-Id, \d+`
Query	`Query=name, zhang.*`
Cookie	`Cookie=session, abc123`
Host	`Host=**.example.com`
After	`After=2024-01-01T00:00:00+08:00`
Before	`Before=2024-12-31T23:59:59+08:00`
Between	`Between=2024-01-01T00:00:00+08:00,2024-12-31T23:59:59+08:00`
RemoteAddr	`RemoteAddr=192.168.1.1/24`
Weight	`Weight=group1, 80`

过滤器工厂

过滤器	示例
AddRequestHeader	`AddRequestHeader=X-Request-Id, 12345`
AddResponseHeader	`AddResponseHeader=X-Response-Time, 2024`
RemoveRequestHeader	`RemoveRequestHeader=X-Unwanted`
RemoveResponseHeader	`RemoveResponseHeader=X-Unwanted`
SetRequestHeader	`SetRequestHeader=X-Request-Id, 54321`
AddRequestParameter	`AddRequestParameter=foo, bar`
StripPrefix	`StripPrefix=1`
PrefixPath	`PrefixPath=/api`
RewritePath	`RewritePath=/api/(?<s>.*), /${s}`
SetPath	`SetPath=/api/user/{segment}`
RedirectTo	`RedirectTo=302, https://example.com`
SetStatus	`SetStatus=404`
Retry	`Retry=3`
RequestSize	`RequestSize=500KB`

全局过滤器

@Component
public class AuthGlobalFilter implements GlobalFilter, Ordered {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        // 认证逻辑
        return chain.filter(exchange);
    }

    @Override
    public int getOrder() {
        return -100;
    }
}

OpenFeign

依赖

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-openfeign</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>

启用

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

客户端定义

@FeignClient(name = "user-service", fallback = UserClientFallback.class)
public interface UserClient {

    @GetMapping("/user/{id}")
    User getUser(@PathVariable("id") Long id);

    @PostMapping("/user")
    User createUser(@RequestBody User user);
}

配置

feign:
  client:
    config:
      default:
        connectTimeout: 5000
        readTimeout: 5000
        loggerLevel: BASIC
  circuitbreaker:
    enabled: true
  compression:
    request:
      enabled: true
    response:
      enabled: true

日志级别

级别	说明
NONE	不记录日志（默认）
BASIC	请求方法、URL、状态码、执行时间
HEADERS	BASIC + 请求头和响应头
FULL	HEADERS + 请求体和响应体

Spring Cloud LoadBalancer

依赖

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>

使用 RestTemplate

@Configuration
public class RestTemplateConfig {

    @Bean
    @LoadBalanced
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }
}

使用 WebClient

@Configuration
public class WebClientConfig {

    @Bean
    @LoadBalanced
    public WebClient.Builder webClientBuilder() {
        return WebClient.builder();
    }
}

配置

spring:
  cloud:
    loadbalancer:
      cache:
        enabled: true
        ttl: 35s
        capacity: 256
      health-check:
        initial-delay: 0s
        interval: 25s
      configurations: default  # weighted, zone-preference, health-check

自定义策略

public class RandomLoadBalancerConfig {

    @Bean
    ReactorLoadBalancer<ServiceInstance> randomLoadBalancer(
            Environment environment,
            LoadBalancerClientFactory factory) {
        String name = environment.getProperty(LoadBalancerClientFactory.PROPERTY_NAME);
        return new RandomLoadBalancer(
            factory.getLazyProvider(name, ServiceInstanceListSupplier.class),
            name
        );
    }
}

Sentinel

依赖

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
</dependency>

配置

spring:
  cloud:
    sentinel:
      transport:
        dashboard: localhost:8080
        port: 8719
      eager: true
      datasource:
        flow:
          nacos:
            server-addr: localhost:8848
            data-id: ${spring.application.name}-flow-rules
            rule-type: flow

使用

@GetMapping("/user/{id}")
@SentinelResource(value = "getUser", blockHandler = "getUserBlockHandler")
public User getUser(@PathVariable Long id) {
    return userService.getById(id);
}

public User getUserBlockHandler(Long id, BlockException ex) {
    return new User(id, "限流降级用户");
}

Resilience4j

依赖

<dependency>
    <groupId>io.github.resilience4j</groupId>
    <artifactId>resilience4j-spring-boot3</artifactId>
</dependency>

断路器配置

resilience4j:
  circuitbreaker:
    instances:
      userService:
        slidingWindowSize: 10
        failureRateThreshold: 50
        waitDurationInOpenState: 10s
        permittedNumberOfCallsInHalfOpenState: 3
        slowCallDurationThreshold: 2s
        slowCallRateThreshold: 50

使用

@CircuitBreaker(name = "userService", fallbackMethod = "fallback")
public User getUser(Long id) {
    return userClient.getUser(id);
}

public User fallback(Long id, Exception ex) {
    return new User(id, "降级用户");
}

Eureka

服务端

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

server:
  port: 8761

eureka:
  client:
    register-with-eureka: false
    fetch-registry: false

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

客户端

spring:
  application:
    name: user-service

eureka:
  client:
    service-url:
      defaultZone: http://localhost:8761/eureka/
  instance:
    prefer-ip-address: true
    lease-renewal-interval-in-seconds: 10
    lease-expiration-duration-in-seconds: 30

常用注解

注解	用途
`@EnableDiscoveryClient`	启用服务发现客户端
`@EnableFeignClients`	启用 Feign 客户端
`@FeignClient`	声明 Feign 客户端
`@LoadBalanced`	启用负载均衡
`@RefreshScope`	支持配置刷新
`@SentinelResource`	Sentinel 资源注解
`@CircuitBreaker`	断路器注解
`@LoadBalancerClient`	自定义负载均衡配置

常见问题

服务注册失败

检查 Nacos/Eureka 地址是否正确，检查命名空间配置，检查网络连通性。

网关路由不生效

检查路由配置语法，检查断言是否匹配，检查目标服务是否已注册。

Feign 调用超时

调整超时配置：

feign:
  client:
    config:
      default:
        connectTimeout: 10000
        readTimeout: 30000

负载均衡不生效

确保添加了 spring-cloud-starter-loadbalancer 依赖，确保使用 @LoadBalanced 注解，确保禁用了 Ribbon。

配置不刷新

确保添加了 @RefreshScope 注解，确保配置了 refresh: true，检查 Nacos 配置是否正确。

版本对应​

Maven 依赖​

Spring Cloud BOM​

Spring Cloud Alibaba BOM​

常用 Starter​

Spring Cloud Alibaba​

版本对应​

Nacos 服务发现​

配置​

常用配置项​

Nacos 配置中心​

依赖​

配置​

动态刷新​

Spring Cloud Gateway​

依赖​

路由配置​

断言工厂​

过滤器工厂​

全局过滤器​

OpenFeign​

依赖​

启用​

客户端定义​

配置​

日志级别​

Spring Cloud LoadBalancer​

依赖​

使用 RestTemplate​

使用 WebClient​

配置​

自定义策略​

Sentinel​

依赖​

配置​

使用​

Resilience4j​

依赖​

断路器配置​

使用​

Eureka​

服务端​

客户端​

常用注解​

常见问题​

服务注册失败​

网关路由不生效​

Feign 调用超时​

负载均衡不生效​

配置不刷新​

参考链接​

版本对应

Maven 依赖

Spring Cloud BOM

Spring Cloud Alibaba BOM

常用 Starter

Spring Cloud Alibaba

版本对应

Nacos 服务发现

配置

常用配置项

Nacos 配置中心

依赖

配置

动态刷新

Spring Cloud Gateway

依赖

路由配置

断言工厂

过滤器工厂

全局过滤器

OpenFeign

依赖

启用

客户端定义

配置

日志级别

Spring Cloud LoadBalancer

依赖

使用 RestTemplate

使用 WebClient

配置

自定义策略

Sentinel

依赖

配置

使用

Resilience4j

依赖

断路器配置

使用

Eureka

服务端

客户端

常用注解

常见问题

服务注册失败

网关路由不生效

Feign 调用超时

负载均衡不生效

配置不刷新

参考链接