用 Rust 从零实现熔断器:状态切换的几个数字怎么定
上一篇讲限流,是"我自己扛不住了,别再来"。熔断器管的是另一件事:"下游挂了,别再傻等"。
这两者的区别很关键:限流保护自己,熔断保护整条链路。
一个下游服务开始变慢时,如果没有熔断,上游会积累大量等待超时的请求,线程池被占满,然后上游也挂了。故障就这样一级一级往上爬,最后全站不可用。 熔断器的作用就是在第一级就把它切断。
三个状态
熔断器的状态机非常简单:
失败率超阈值
┌──────────────────┐
│ v
Closed Open
^ │
│ 测试成功 │ 等待 open_timeout
│ v
└──────────── HalfOpen
│ 测试失败
└──────> Open- Closed:正常放行。同时统计成功率。
- Open:直接拒绝,不调用下游。
- HalfOpen:放少量请求"试探",根据结果决定回 Closed 还是 Open。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum State {
Closed,
Open,
HalfOpen,
}HalfOpen 是整个设计的灵魂。 没有它,熔断器一旦打开就永远不会恢复——要么靠人工重置,要么靠固定时间硬恢复(可能在还挂着的时候恢复)。
第一个决策:用什么统计
统计"失败率"需要一个滑动窗口。三种常见做法:
| 方案 | 实现 | 特点 |
|---|---|---|
| 计数窗口 | 最近 N 个请求 | 样本量稳定,突发时反应快 |
| 时间窗口 | 最近 T 秒的请求 | 时间语义直观,空闲时无样本 |
| 分桶窗口 | T 秒切成若干格 | 兼顾两者,主流方案 |
我推荐分桶(和上一篇滑动窗口限流器同一个结构),因为它能同时回答两个问题:"最近 10 秒失败率多少""有多少请求参与统计"。
pub struct Bucket {
/// 这一格的起始时间戳(毫秒)
start_ms: u64,
successes: u64,
failures: u64,
}
pub struct Metrics {
buckets: Vec<Bucket>,
/// 每格的时间跨度
bucket_duration_ms: u64,
/// 当前格的下标
current: usize,
}impl Metrics {
pub fn new(bucket_count: usize, duration_ms: u64) -> Self {
let now = now_ms();
Self {
buckets: (0..bucket_count)
.map(|i| Bucket {
// 每格起点错开,这样"整窗统计"天然是对的
start_ms: now - (bucket_count - i) as u64 * duration_ms,
successes: 0,
failures: 0,
})
.collect(),
bucket_duration_ms: duration_ms,
current: 0,
}
}
fn advance(&mut self, now: u64) {
// 把过期的桶清零,推进到对应位置
let elapsed = now.saturating_sub(self.buckets[self.current].start_ms);
let steps = elapsed / self.bucket_duration_ms;
for _ in 0..steps.min(self.buckets.len() as u64) {
self.current = (self.current + 1) % self.buckets.len();
self.buckets[self.current] = Bucket {
start_ms: self.buckets[self.current].start_ms + self.bucket_duration_ms * steps.max(1),
successes: 0,
failures: 0,
};
}
}
pub fn record(&mut self, success: bool) {
let now = now_ms();
self.advance(now);
let b = &mut self.buckets[self.current];
if success {
b.successes += 1;
} else {
b.failures += 1;
}
}
pub fn totals(&self) -> (u64, u64) {
let s: u64 = self.buckets.iter().map(|b| b.successes).sum();
let f: u64 = self.buckets.iter().map(|b| b.failures).sum();
(s, f)
}
}分桶的关键性质是"整窗统计只需要把所有桶相加",不需要逐个判断时间戳。 这也是 Hystrix、Resilience4j 的做法。
第二个决策:连续失败还是失败率
两种触发条件:
连续失败 N 次:简单,但对低流量接口基本无效(一个接口每分钟 3 个请求,连续 5 次失败要等快 2 分钟)。
失败率超阈值:更通用,但需要足够的样本量——3 个请求全部失败,失败率是 100%,但不该熔断。
所以正确的实现要两个条件都满足:
pub struct Config {
/// 统计窗口内最少要有多少个请求才评估
pub min_requests: u64, // 建议 20
/// 失败率阈值
pub failure_rate_threshold: f64, // 建议 0.5
/// 连续失败多少次直接熔断
pub consecutive_failure_threshold: u64, // 建议 5
/// 窗口大小(毫秒)
pub window_ms: u64, // 建议 10000
/// Open 状态持续多久
pub open_timeout_ms: u64, // 建议 5000
/// HalfOpen 放行多少个试探请求
pub half_open_probes: u64, // 建议 3
}min_requests 是最容易被忽略、也最重要的参数。 没有它,一个刚上线的接口或者冷门接口会在第一次失败时就熔断,造成"误伤"。
判断逻辑:
impl Metrics {
/// 是否应该从 Closed 转向 Open
pub fn should_trip(&self, cfg: &Config) -> bool {
let (successes, failures) = self.totals();
let total = successes + failures;
// 条件一:样本量足够
if total < cfg.min_requests {
return false;
}
// 条件二:失败率超阈值
let rate = failures as f64 / total as f64;
rate >= cfg.failure_rate_threshold
}
}"失败率 + 最小样本量"这个组合,是熔断器最容易做对也最容易做错的点。 只看比例会误伤低流量接口,只看次数会在高流量下反应过慢。
熔断器主体
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::Mutex;
pub struct CircuitBreaker {
cfg: Config,
state: Mutex<Inner>,
}
struct Inner {
state: State,
metrics: Metrics,
/// 连续失败计数
consecutive_failures: u64,
/// 进入 Open 的时间
opened_at: Option<std::time::Instant>,
/// HalfOpen 已经放行了多少个
half_open_in_flight: u64,
/// HalfOpen 期间的成功数
half_open_successes: u64,
}
impl CircuitBreaker {
/// 关键入口:判断这次调用能不能放行
pub fn try_acquire(&self) -> Result<Permit<'_>, BreakerError> {
let mut inner = self.state.lock().unwrap();
match inner.state {
State::Closed => Ok(Permit { breaker: self }),
State::Open => {
// 到时间了,转到 HalfOpen
if let Some(opened) = inner.opened_at {
if opened.elapsed().as_millis() as u64 >= self.cfg.open_timeout_ms {
inner.state = State::HalfOpen;
inner.half_open_in_flight = 0;
inner.half_open_successes = 0;
return self.try_acquire_half_open(&mut inner);
}
}
Err(BreakerError::Open)
}
State::HalfOpen => self.try_acquire_half_open(&mut inner),
}
}
fn try_acquire_half_open(&self, inner: &mut Inner) -> Result<Permit<'_>, BreakerError> {
if inner.half_open_in_flight >= self.cfg.half_open_probes {
// 试探名额已满,其余请求继续拒绝
return Err(BreakerError::Open);
}
inner.half_open_in_flight += 1;
Ok(Permit { breaker: self })
}
}用 RAII 保证"结果一定被记录"
熔断器最怕的是"拿了许可却忘了上报结果"——统计就失真了。用 RAII 强制上报:
pub struct Permit<'a> {
breaker: &'a CircuitBreaker,
}
impl<'a> Permit<'a> {
/// 调用成功
pub fn success(mut self) {
self.breaker.on_result(true);
std::mem::forget(self); // 阻止 Drop 再报一次失败
}
/// 调用失败
pub fn failure(mut self) {
self.breaker.on_result(false);
std::mem::forget(self);
}
}
impl<'a> Drop for Permit<'a> {
fn drop(&mut self) {
// 没有显式上报就被 drop,按失败处理(保守)
self.breaker.on_result(false);
}
}std::mem::forget 是关键:success() 和 failure() 消费了 self,但因为 Permit 实现了 Drop,不能直接 move。用 mem::forget 跳过析构函数是这里的标准做法。
"没上报就按失败算"是刻意的保守选择。 如果调用方因为 panic 或者提前 return 忘了上报,把它算成成功会让熔断器过于乐观——这在故障场景下是危险的。
结果处理
impl CircuitBreaker {
fn on_result(&self, success: bool) {
let mut inner = self.state.lock().unwrap();
match inner.state {
State::Closed => {
inner.metrics.record(success);
if success {
inner.consecutive_failures = 0;
} else {
inner.consecutive_failures += 1;
}
// 两个触发条件,满足任一即熔断
if inner.consecutive_failures >= self.cfg.consecutive_failure_threshold
|| inner.metrics.should_trip(&self.cfg)
{
self.trip(&mut inner);
}
}
State::HalfOpen => {
inner.half_open_in_flight = inner.half_open_in_flight.saturating_sub(1);
if success {
inner.half_open_successes += 1;
// 试探全部成功 → 恢复
if inner.half_open_successes >= self.cfg.half_open_probes {
inner.state = State::Closed;
inner.metrics = Metrics::new(10, self.cfg.window_ms / 10);
inner.consecutive_failures = 0;
inner.opened_at = None;
}
} else {
// 任意一个试探失败 → 立刻回到 Open
self.trip(&mut inner);
}
}
State::Open => {
// Open 状态下不应该有结果上报(因为根本没放行)
// 但如果并发下漏了,忽略掉
}
}
}
fn trip(&self, inner: &mut Inner) {
inner.state = State::Open;
inner.opened_at = Some(std::time::Instant::now());
inner.consecutive_failures = 0;
inner.metrics = Metrics::new(10, self.cfg.window_ms / 10);
}
}注意 HalfOpen 的两个不对称策略:
- 全部试探成功 → 才恢复(严格)
- 任意一个试探失败 → 立刻回到 Open(快速)
为什么要不对称?因为误判"已恢复"的代价,远大于多等一个 open_timeout。如果恢复太早,下游还在故障中,一放开流量就会再次被打垮——熔断器会陷入"打开-恢复-再打开"的抖动。
熔断器的恢复一定要"保守",熔断一定要"果断"。 这是它在状态机上的基本取向。
参数怎么定:几个经验法则
实现完了,真正难的是调参。几个踩过坑之后总结的原则:
1. window_ms 不要太大。 如果窗口是 60 秒,故障发生时你要等 60 秒才能积累出"失败率超阈值"。建议 10 秒左右,或者用"连续失败"作为快速触发。
2. open_timeout_ms 要略大于下游的恢复时间。 太短会反复抖动,太长会让恢复延迟。常见做法是指数退避:第一次 1 秒,第二次 2 秒,第三次 4 秒,上限 30 秒。
fn backoff(&self, open_count: u32) -> u64 {
let base = self.cfg.open_timeout_ms;
(base * 2u64.pow(open_count.min(5))).min(30_000)
}3. half_open_probes 用 1-3 就够。 放太多请求试探,等于在没确认恢复的情况下重新施加压力。
4. min_requests 至少 20。 太小的样本量毫无统计意义。
5. failure_rate_threshold 常用 0.5。 有些团队用 0.3(更敏感),适合核心链路。
最容易忽略的一条:哪些错误算"失败"。
fn is_failure(err: &AppError) -> bool {
match err {
// 网络、超时、5xx → 算失败,说明下游有问题
AppError::Timeout | AppError::Network => true,
AppError::Http(500..=599) => true,
// 4xx → 不算失败,这是调用方的问题,不是下游的问题
AppError::Http(400..=499) => false,
// 业务错误码 → 明确排除
AppError::Business(_) => false,
}
}如果把 4xx 也算成失败,一个被人乱扫的接口会把自己的熔断器打开。 这是实践中非常常见的误配。
三个必须踩过的坑
1. 熔断器是"每个下游"一个,不是全局一个。 用一个全局熔断器保护所有下游,会导致"A 下游挂了,连 B 的调用也被拒绝"。
正确做法是按下游实例维度维护:
pub struct BreakerRegistry {
breakers: Mutex<std::collections::HashMap<String, std::sync::Arc<CircuitBreaker>>>,
}
impl BreakerRegistry {
pub fn get(&self, target: &str, cfg: Config) -> std::sync::Arc<CircuitBreaker> {
let mut map = self.breakers.lock().unwrap();
map.entry(target.to_string())
.or_insert_with(|| std::sync::Arc::new(CircuitBreaker::new(cfg)))
.clone()
}
}key 应该是"下游服务 + 实例",而不是"下游服务"。 一个服务有 10 个实例,其中 1 个挂了,不该把整个服务的调用都熔断——那台机器应该被单独摘除。
2. 熔断器不能替代超时。 这是最常见的误解。熔断器在 Open 时不发请求,但在 Closed 状态下它是"放行"的——如果下游只是变慢而不是报错,失败率可能并不高,熔断器不会触发。
超时管"单次调用最多等多久",熔断管"连续失败后不再尝试",重试管"失败后换实例再试"。三者缺一不可。
3. HalfOpen 的并发控制。 前面用了 half_open_in_flight 计数,这是必需的。如果没有它,Open 转 HalfOpen 的瞬间涌入的几百个请求会全部放行——等于直接恢复了全部流量。
这个 bug 在压测时很难发现(因为长时间处于 Closed),只有在真实故障恢复时才暴露。唯一的发现方式是写针对状态机的单元测试。
结论
熔断器的实现不长,但每个参数都是一次取舍:
统计用分桶滑动窗口;触发要"失败率 + 最小样本量"和"连续失败"双条件;Open 时间用指数退避;HalfOpen 恢复保守、熔断果断;4xx 等调用方错误不能计入失败。
还有一条最重要的工程原则:熔断器要按下游实例维度隔离,并且搭配超时和重试一起使用。 单独一个熔断器解决不了"下游变慢"这类问题——它只能解决"下游持续报错"。这也是它和下一篇(工作窃取调度器)看起来无关、但都属于"让系统在压力下保持可控"这个主题的原因。