Spring Cloud Circuit Breaker 使用指南

1. 概述

本文将带你快速掌握 Spring Cloud Circuit Breaker 的核心用法，帮助你在微服务架构中实现更稳定的容错机制。

我们会先了解 Spring Cloud Circuit Breaker 提供了哪些优势，再通过 Spring Boot 的自动配置机制，轻松集成主流的熔断器实现。

✅ 提示：如果你还不熟悉“熔断器”（Circuit Breaker）的基本概念，建议先阅读《Hystrix 入门》或《Resilience4j 使用指南》打个基础。

2. Spring Cloud Circuit Breaker 简介

在早期 Spring Cloud 生态中，熔断功能主要依赖 Netflix Hystrix，通过 @EnableCircuitBreaker 和 @HystrixCommand 注解实现。但这种方式存在一个致命问题：与 Hystrix 强耦合。

这意味着一旦你想换成 Resilience4j 或 Sentinel，就得重写大量业务代码，非常不灵活。

Spring Cloud Circuit Breaker 就是为解决这个问题而生的：

✅ 它提供了一套统一的抽象层，屏蔽了底层不同熔断框架的差异
✅ 支持插件化扩展，可自由切换实现（Resilience4j、Hystrix、Sentinel 等）
✅ 编码面向接口，无需关心具体实现

⚠️ 本文以 Resilience4j 为例，但所讲方法同样适用于其他实现。

3. 自动配置机制

要使用某个熔断器实现，只需引入对应的 Spring Boot Starter 即可。Spring 会自动完成 Bean 注册和配置。

引入 Resilience4j Starter

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-circuitbreaker-resilience4j</artifactId>
    <version>1.0.2.RELEASE</version>
</dependency>

只要这个依赖在 classpath 中，Spring Boot 就会自动配置好 CircuitBreakerFactory 等必要组件。

关闭自动配置（可选）

如果你只想手动控制，可以通过配置禁用：

spring.cloud.circuitbreaker.resilience4j.enabled=false

4. 简单熔断示例

我们来构建一个简单的 Spring Boot Web 应用，调用外部 API 获取专辑列表，并为其加上熔断保护。

目标接口：
https://jsonplaceholder.typicode.com/albums

4.1 创建熔断器实例

首先注入 CircuitBreakerFactory，它是创建熔断器的核心工厂：

@Service
public class AlbumService {
    
    @Autowired
    private CircuitBreakerFactory circuitBreakerFactory;

    // ...
}

通过 create() 方法即可创建一个指定 ID 的熔断器：

CircuitBreaker circuitBreaker = circuitBreakerFactory.create("circuitbreaker");

✅ ID 建议按业务命名，便于监控和排查问题，比如 order-service-cb。

4.2 使用熔断器包装任务

使用 run() 方法包裹可能失败的操作，传入 Supplier 函数式接口：

public String getAlbumList() {
    CircuitBreaker circuitBreaker = circuitBreakerFactory.create("circuitbreaker");
    String url = "https://jsonplaceholder.typicode.com/albums";

    return circuitBreaker.run(() -> restTemplate.getForObject(url, String.class));
}

这样，当请求超时或异常时，熔断器会自动处理，避免雪崩。

添加降级逻辑（Fallback）

更常见的是提供一个降级方案，当调用失败时返回兜底数据：

public String getAlbumList() {
    CircuitBreaker circuitBreaker = circuitBreakerFactory.create("circuitbreaker");
    String url = "http://localhost:1234/not-real"; // 模拟不可用服务
    
    return circuitBreaker.run(
        () -> restTemplate.getForObject(url, String.class),
        throwable -> getDefaultAlbumList() // 降级方法
    );
}

⚠️ 注意：

降级方法接收 Throwable 参数，可根据异常类型返回不同结果
如果不提供 fallback 且调用失败，会抛出 NoFallbackAvailableException

4.3 编写控制器接口

最后暴露一个 REST 接口供测试：

@RestController
public class AlbumController {

    @Autowired
    private AlbumService albumService;

    @GetMapping("/albums")
    public String albums() {
        return albumService.getAlbumList();
    }
}

启动应用后访问：
[GET] http://localhost:8080/albums

5. 全局自定义配置

默认配置往往不够用。我们可以通过定义 Customizer<CircuitBreakerFactory> Bean 来统一设置所有熔断器的行为。

定义通用配置

@Configuration
public class Resilience4JConfiguration {

    @Bean
    public Customizer<Resilience4JCircuitBreakerFactory> globalCustomConfiguration() {
        CircuitBreakerConfig circuitBreakerConfig = CircuitBreakerConfig.custom()
            .failureRateThreshold(50)  // 失败率阈值 50%
            .waitDurationInOpenState(Duration.ofMillis(1000)) // 熔断后等待 1 秒
            .slidingWindowSize(2)      // 滑动窗口大小为 2
            .build();

        TimeLimiterConfig timeLimiterConfig = TimeLimiterConfig.custom()
            .timeoutDuration(Duration.ofSeconds(4)) // 超时 4 秒
            .build();

        return factory -> factory.configureDefault(id -> new Resilience4JConfigBuilder(id)
            .timeLimiterConfig(timeLimiterConfig)
            .circuitBreakerConfig(circuitBreakerConfig)
            .build());
    }
}

✅ configureDefault() 会作用于所有未单独配置的熔断器，适合统一规范。

6. 针对性自定义配置

有时不同接口对稳定性要求不同，需要差异化配置。

为特定熔断器设置配置

@Bean
public Customizer<Resilience4JCircuitBreakerFactory> specificCustomConfiguration1() {
    CircuitBreakerConfig config = CircuitBreakerConfig.custom()
        .failureRateThreshold(20)  // 更敏感
        .waitDurationInOpenState(Duration.ofMillis(500))
        .slidingWindowSize(5)
        .build();

    TimeLimiterConfig timeLimiterConfig = TimeLimiterConfig.custom()
        .timeoutDuration(Duration.ofSeconds(2))
        .build();

    return factory -> factory.configure(builder -> builder
        .circuitBreakerConfig(config)
        .timeLimiterConfig(timeLimiterConfig)
        .build(), 
        "critical-service-cb" // 只对这个 ID 生效
    );
}

批量配置多个熔断器

@Bean
public Customizer<Resilience4JCircuitBreakerFactory> specificCustomConfiguration2() {
    // ... 同上 config 定义

    return factory -> factory.configure(builder -> builder
        .circuitBreakerConfig(config)
        .timeLimiterConfig(timeLimiterConfig)
        .build(), 
        "order-cb", "payment-cb", "inventory-cb" // 多个 ID
    );
}

✅ 这种方式适合将一组相关服务配置成相同策略，避免重复定义。

7. 其他可选实现

Spring Cloud Circuit Breaker 支持多种后端实现，你可以根据团队技术栈选择：

Hystrix：老牌方案，Netflix 已停止维护，但仍有不少存量系统在用
Sentinel：阿里开源，强项在于流量控制和系统自适应保护
Spring Retry：轻量级重试机制，严格来说不算完整熔断器

✅ 最关键的一点：你可以在同一个项目中混合使用多种实现！
比如订单服务用 Resilience4j，支付服务用 Sentinel，完全没问题。

📌 补充：Resilience4j 本身还提供了 RateLimiter（限流）、Bulkhead（舱壁隔离）、Retry（重试）等模块，功能比 Spring Cloud Circuit Breaker 暴露的更丰富。如需高级功能，可直接使用原生 API。

8. 总结

Spring Cloud Circuit Breaker 是微服务容错设计的标准解法，它通过抽象层解耦了业务代码与具体实现，极大提升了系统的可维护性和灵活性。

核心要点回顾：

✅ 使用 Starter 自动装配，开箱即用
✅ 通过 CircuitBreakerFactory 创建熔断器实例
✅ run() 方法支持主逻辑 + fallback 降级
✅ 支持全局和局部两种自定义配置方式
✅ 可自由切换或共存多种底层实现

💡 源码已托管至 GitHub：https://github.com/baeldung/spring-cloud-tutorials
分支路径：spring-cloud-modules/spring-cloud-circuit-breaker

Persistence

REST

Security