Rust 错误恢复模式:什么时候重试,什么时候快速失败,什么时候降级
痛定思痛之后,我花了几天时间系统梳理了错误恢复这件事,总结出了一个决策框架。今天分享给大家:在 Rust 里,错误恢复不是非黑即白的重试/不重试,而是一个从错误类型反推策略的过程。
一、错误分类:不是所有错都配得上"重试"
首先,不是所有错误都该重试。我根据经验把错误分成了三类:
/// 错误分类 —— 决定处理策略的第一步
#[derive(Debug)]
enum ErrorStrategy {
/// 临时性错误 → 可以重试
/// 例子:网络超时、API 限流(429)、服务暂时不可用(503)
Retryable {
reason: String,
/// 建议等待时间(如果服务端返回了 Retry-After)
suggested_delay_ms: Option<u64>,
},
/// 永久性错误 → 快速失败
/// 例子:认证失败(401)、权限不足(403)、请求格式错误(400)
Fatal {
reason: String,
},
/// 部分功能受影响 → 降级
/// 例子:主力模型挂了但备用模型还能用、推荐服务挂了但默认推荐还在
Degradable {
reason: String,
fallback: String, // 降级方案的描述
},
}
/// 把 HTTP 状态码映射到错误策略
fn classify_http_error(status_code: u16, body: &str) -> ErrorStrategy {
match status_code {
// ===== 可重试 =====
429 => ErrorStrategy::Retryable {
reason: "API 限流,稍后再试".to_string(),
suggested_delay_ms: Some(parse_retry_after(body)), // 从响应头读 Retry-After
},
503 | 502 => ErrorStrategy::Retryable {
reason: format!("服务端 {} 错误,可能短暂不可用", status_code),
suggested_delay_ms: Some(1000), // 至少等1秒
},
408 => ErrorStrategy::Retryable {
reason: "请求超时,网络可能抖动".to_string(),
suggested_delay_ms: Some(500),
},
// ===== 快速失败 =====
401 | 403 => ErrorStrategy::Fatal {
reason: "认证/授权失败,重试无意义".to_string(),
},
400 => ErrorStrategy::Fatal {
reason: format!("请求参数错误: {}", body),
},
402 => ErrorStrategy::Fatal {
reason: "账户余额不足!请充值".to_string(),
},
// ===== 降级 =====
500 => ErrorStrategy::Degradable {
reason: "服务端内部错误,可能持续较久".to_string(),
fallback: "切换到备用模型提供商".to_string(),
},
// 未知状态码保守处理
_ => ErrorStrategy::Retryable {
reason: format!("未知状态码 {},保守重试一次", status_code),
suggested_delay_ms: Some(2000),
},
}
}
fn parse_retry_after(_body: &str) -> u64 {
// 实际项目从响应头解析 Retry-After 字段
5_000 // 默认 5 秒
}
这个分类的核心逻辑就是这张决策图:
flowchart TD
Start["收到错误"] --> Q1{"是客户端错误<br/>(4xx 除了429)?"}
Q1 -->|是| Fatal["快速失败<br/>不重试,直接报错"]
Q1 -->|否| Q2{"是限流错误<br/>(429)?"}
Q2 -->|是| RetryDelay["等待 Retry-After 后重试<br/>指数退避"]
Q2 -->|否| Q3{"是服务端错误<br/>(5xx)?"}
Q3 -->|是| Q4{"有备用服务?"}
Q4 -->|有| Degrade["降级:切到备用服务"]
Q4 -->|没有| RetryBackoff["有限重试 + 退避"]
Q3 -->|否| Q5{"是网络超时<br/>(timeout)?"}
Q5 -->|是| RetryBackoff
RetryBackoff --> Q6{"重试次数 < 上限?"}
Q6 -->|是| Wait["等待(指数退避)"]
Wait --> Start
Q6 -->|否| Degrade2["降级:返回缓存结果<br/>或通知用户稍后重试"]
Fatal --> End["结束"]
RetryDelay --> End
Degrade --> End
Degrade2 --> End
style Fatal fill:#ffcdd2
style RetryDelay fill:#fff9c4
style Degrade fill:#c8e6c9
style Degrade2 fill:#c8e6c9
二、重试的四种策略模板
确定了"可以重试"之后,怎么重试也大有讲究。不是简单地 for i in 0..3 { try().await? }。我整理了四种重试策略:
use std::time::Duration;
use tokio::time::sleep;
/// 重试策略枚举
/// 不同场景匹配不同策略,没有银弹
#[derive(Clone, Debug)]
enum RetryPolicy {
/// 1. 固定间隔 Retry —— 最简单的
Fixed {
max_retries: u32,
interval: Duration, // 固定等待时间
},
/// 2. 指数退避 —— 避免"惊群效应"
/// 第1次等100ms,第2次等200ms,第3次等400ms...
Exponential {
max_retries: u32,
base: Duration, // 基础等待时间
max_delay: Duration, // 等待上限(防止等太久)
},
/// 3. 带抖动的指数退避 —— 避免多个客户端同时重试
/// 在等待时间上随机加一点偏移
Jittered {
max_retries: u32,
base: Duration,
max_delay: Duration,
},
/// 4. 无限重试但有 back-pressure —— 持续尝试但不炸服务器
Persistent {
initial_interval: Duration,
max_interval: Duration,
},
}
impl RetryPolicy {
/// 计算第 attempt 次重试应该等多久
fn delay_for(&self, attempt: u32) -> Option<Duration> {
match self {
RetryPolicy::Fixed { max_retries, interval } => {
if attempt > *max_retries {
None // 超过上限,不再重试
} else {
Some(*interval)
}
}
RetryPolicy::Exponential { max_retries, base, max_delay } => {
if attempt > *max_retries {
return None;
}
// 指数公式:base * 2^(attempt-1)
let delay = base.as_millis() as u64 * 2u64.pow(attempt - 1);
let delay = Duration::from_millis(delay);
Some(delay.min(*max_delay)) // 不超过上限
}
RetryPolicy::Jittered { max_retries, base, max_delay } => {
if attempt > *max_retries {
return None;
}
let base_ms = base.as_millis() as u64;
let exp = base_ms * 2u64.pow(attempt - 1);
// 在 [exp * 0.5, exp * 1.5] 范围内随机
let jitter = (exp as f64 * 0.5) as u64
+ (fastrand::u64(..) % (exp as f64 * 1.0) as u64);
let delay = Duration::from_millis(jitter.min(max_delay.as_millis() as u64));
Some(delay)
}
RetryPolicy::Persistent { initial_interval, max_interval } => {
// 一直重试,但等待时间逐渐增加到 max_interval
let ms = (initial_interval.as_millis() as u64)
.saturating_mul(attempt as u64)
.min(max_interval.as_millis() as u64);
Some(Duration::from_millis(ms))
}
}
}
}
/// 通用重试执行器
/// 把策略和实际的异步操作结合起来
async fn retry_with_policy<F, Fut, T, E>(
policy: &RetryPolicy,
operation_name: &str,
mut f: F,
) -> Result<T, E>
where
F: FnMut() -> Fut,
Fut: std::future::Future<Output = Result<T, E>>,
E: std::fmt::Display,
{
let mut attempt = 0u32;
loop {
attempt += 1;
match f().await {
Ok(value) => {
// 成功了!记录一下重试了几次
if attempt > 1 {
tracing::info!(
operation = operation_name,
attempts = attempt,
"操作在第 {} 次尝试时成功", attempt
);
}
return Ok(value);
}
Err(e) => {
// 失败 → 检查还有没有重试配额
match policy.delay_for(attempt) {
Some(delay) => {
tracing::warn!(
operation = operation_name,
attempt = attempt,
next_delay_ms = delay.as_millis(),
error = %e,
"操作失败,{}ms后重试", delay.as_millis()
);
sleep(delay).await;
// continue loop
}
None => {
// 重试次数用完了
tracing::error!(
operation = operation_name,
total_attempts = attempt,
error = %e,
"操作失败,已达最大重试次数"
);
return Err(e);
}
}
}
}
}
}
四种策略怎么选?简单总结:
| 策略 | 适用场景 | 例子 |
|---|---|---|
| Fixed | 资源冲突但有规律(如数据库死锁) | 等 500ms 重试一次 |
| Exponential | API 限流(避免继续打爆服务端) | 429 错误 |
| Jittered | 多客户端同时重试(避免惊群) | 定时任务 |
| Persistent | 关键操作必须完成(如支付回调) | 消息队列消费者 |
三、快速失败:别在没意义的事上浪费时间
很多初学者(包括半年前的我)有个误区:觉得"重试"是一种美德,是负责任的代码。但要我说——明知不可能成功还重试,不是负责任,是在浪费 CPU。
/// 快速失败的三个典型场景
use std::fmt;
#[derive(Debug)]
enum FastFailError {
/// 1. 参数/配置错误 → 重试 100 次还是一样
/// 比如:API Key 填错了、请求的 model 名称不存在
InvalidConfig(String),
/// 2. 权限/认证问题 → 除非你去改权限,否则永远失败
/// 比如:Token 过期了但用户没有重新登录的机制
PermissionDenied(String),
/// 3. 业务规则不满足 → 这不是技术错误,是逻辑错误
/// 比如:用户余额不足、重复提交、数据违反唯一约束
BusinessRule(String),
}
impl fmt::Display for FastFailError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
FastFailError::InvalidConfig(msg) => {
write!(f, "配置错误(快速失败): {}", msg)
}
FastFailError::PermissionDenied(msg) => {
write!(f, "权限不足(快速失败): {}", msg)
}
FastFailError::BusinessRule(msg) => {
write!(f, "业务规则不满足(快速失败): {}", msg)
}
}
}
}
/// 快速失败的正确做法:
/// 直接返回 Err,并把错误信息清晰地传给调用者
fn validate_api_key(key: &str) -> Result<(), FastFailError> {
// 检查 API Key 的格式
if key.is_empty() || key.len() < 10 {
return Err(FastFailError::InvalidConfig(
format!("API Key 格式不正确(长度={},需要至少10位)", key.len())
));
}
Ok(())
}
/// 另一个快速失败的例子:检查用户配额
fn check_quota(used: u64, limit: u64) -> Result<(), FastFailError> {
if used >= limit {
return Err(FastFailError::BusinessRule(
format!("配额已用完({} / {}),请升级套餐", used, limit)
));
}
Ok(())
}
快速失败还有一个额外的好处:让调用方尽快感知到问题。如果一个 API 需要 30 秒超时,你给它加了 3 次重试,那用户就要等 3 分钟才知道失败——而实际上在第一次请求时你就知道是权限错误了。这在用户体验上是巨大的差异。
四、降级策略:主打一个"至少还有你"
最后聊降级。很多错误不是"完全不能用",而是"部分功能受影响"。这时候降级策略就派上用场了:
use std::collections::HashMap;
/// 模型提供商的降级策略
/// 当主模型不可用,自动切换到备用模型
struct ModelDegradation {
/// 模型降级链:主模型 → 备用模型1 → 备用模型2
/// 越靠前越优先
fallback_chain: Vec<String>,
/// 每个模型是否可用(运行时动态更新)
health_status: HashMap<String, bool>,
}
impl ModelDegradation {
fn new(primary: &str, fallbacks: &[&str]) -> Self {
let mut chain = vec![primary.to_string()];
chain.extend(fallbacks.iter().map(|s| s.to_string()));
ModelDegradation {
fallback_chain: chain,
health_status: HashMap::new(),
}
}
/// 标记某个模型不可用
fn mark_unhealthy(&mut self, model: &str) {
tracing::warn!(model, "标记模型为不可用");
self.health_status.insert(model.to_string(), false);
}
/// 获取当前可用的最优模型
fn get_best_available(&self) -> Option<&str> {
self.fallback_chain.iter().find(|model| {
// 默认是健康的(除非显式标记为不健康)
self.health_status.get(model.as_str()).copied().unwrap_or(true)
}).map(|s| s.as_str())
}
}
/// 带降级的 LLM 调用函数
/// 如果主模型挂了,自动切到备用模型
async fn llm_call_with_degradation(
prompt: &str,
degradation: &mut ModelDegradation,
) -> Result<String, Box<dyn std::error::Error>> {
let mut last_error = None;
// 遍历降级链,找到第一个可用的模型
while let Some(model) = degradation.get_best_available() {
tracing::info!(model, "尝试调用模型");
match call_specific_model(model, prompt).await {
Ok(response) => {
// 成功了!如果之前是用备用模型,提醒一下用户
if model != degradation.fallback_chain[0] {
tracing::warn!(
used_model = model,
primary_model = degradation.fallback_chain[0],
"⚠️ 主模型不可用,当前使用备用模型 {},效果可能略有差异", model
);
}
return Ok(response);
}
Err(e) => {
tracing::error!(model, error = %e, "模型调用失败");
// 标记该模型不可用,下次循环会跳到下一个
degradation.mark_unhealthy(model);
last_error = Some(e);
}
}
}
// 所有模型都挂了 → 返回缓存结果(如果有的话)
Err(format!(
"所有模型均不可用,最后的错误: {:?}。建议:检查网络连接或稍后再试。",
last_error
).into())
}
/// 模拟调用特定模型
async fn call_specific_model(
_model: &str,
_prompt: &str,
) -> Result<String, Box<dyn std::error::Error>> {
// 实际项目中对接 openai / anthropic / ollama SDK
Ok(format!("来自模型的回复"))
}
flowchart LR
subgraph 正常["正常状态"]
A1["GPT-4o"] -->|主模型| B1["返回结果"]
end
subgraph 降级["降级状态 - GPT-4o 挂了"]
A2["GPT-4o ❌"] -.->|尝试失败| B2["Claude Sonnet"]
B2 -->|备用模型| C2["返回结果<br/>(可能质量略低)"]
end
subgraph 最终降级["最终降级 - 全部模型挂了"]
A3["GPT-4o ❌"] -.-> B3["Claude ❌"]
B3 -.-> C3["Ollama ❌"]
C3 -.-> D3["🔄 返回缓存结果<br/>或提示用户稍后重试"]
end
style A2 fill:#ffcdd2
style A3 fill:#ffcdd2
style B3 fill:#ffcdd2
style C3 fill:#ffcdd2
降级策略在日志里也要处理好:所有模型都失败时,同一条 prompt 每请求一次就打一条 error,高峰期日志直接刷爆了。我在线上加了一条规则——相同 prompt 的降级日志 60 秒内只打一次,防止日志爆炸。
五、总结
这篇文章我梳理了 Rust 中错误恢复的三种模式和一个决策框架:
- 重试:用于临时性错误(429、503、网络超时),采用指数退避 + 抖动避免惊群
- 快速失败:用于永久性错误(401、400、业务规则),重试无意义,直接报错
- 降级:用于部分服务不可用,切换备用方案保证功能不完全中断
三种模式没有绝对的"最好",关键是从错误类型倒推策略。我自己的实践法则是:先分类、再决策、后执行。遇到一个错误先问自己三个问题——它是永久性的还是暂时性的?重试有意义吗?有没有降级方案?三问之后,策略自然就出来了。
作为自学者,以前我总觉得错误处理就是 match err { _ => panic!() },现在慢慢理解到,这和所有权、生命周期一样,都是 Rust 程序员的核心素养。处理得好,用户的体验平滑优雅;处理得不好,用户看到的就是一坨"内部错误,请稍后重试"。
如果你有自己的错误恢复经验或者踩过的坑,欢迎评论区分享,我们下篇见!
468



被折叠的 条评论
为什么被折叠?



