Rust领域错误处理策略：分类、恢复与最佳实践指南

m13-domain-error by zhanghandong/rust-skills

580 周安装量

912 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/zhanghandong/rust-skills --skill m13-domain-error

开发系统架构 Rust

🇨🇳中文介绍

领域错误策略

第二层：设计选择

核心问题

谁需要处理这个错误，以及他们应该如何恢复？

在设计错误类型之前：

这是面向用户的还是内部的？
恢复是否可能？
调试需要什么上下文？

错误分类

错误类型	受众	恢复方式	示例
面向用户	最终用户	引导操作	`InvalidEmail`, `NotFound`
内部错误	开发者	调试信息	`DatabaseError`,

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

749,400 周安装

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

255,700 周安装

Vercel Web界面规范检查工具 - 自动检测代码是否符合Web设计指南

205,600 周安装

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

136,300 周安装

在设计错误类型之前：

谁会看到这个错误？
- 最终用户 → 友好的、可操作的消息
- 开发者 → 详细的、可调试的信息
- 运维 → 结构化的、可告警的信息
我们能恢复吗？
- 瞬时错误 → 使用退避策略重试
- 可降级错误 → 使用回退值
- 永久错误 → 快速失败，发出告警
需要什么上下文？
- 调用链 → anyhow::Context
- 请求ID → 结构化日志
- 输入数据 → 错误负载

追溯至领域约束（第三层）：

"我应该如何处理支付失败？"
    ↑ 询问：业务规则对于重试有何要求？
    ↑ 检查：domain-fintech（交易要求）
    ↑ 检查：SLA（可用性要求）

问题	追溯至	询问
重试策略	domain-*	可接受的重试延迟是多少？
用户体验	domain-*	用户应该看到什么消息？
合规性	domain-*	审计必须记录什么？

追溯至实现（第一层）：

"需要类型化错误"
    ↓ m06-error-handling: 库使用 thiserror
    ↓ m04-zero-cost: 错误枚举设计

"需要错误上下文"
    ↓ m06-error-handling: anyhow::Context
    ↓ 日志记录：带字段的 tracing

"需要重试逻辑"
    ↓ m07-concurrency: 异步重试模式
    ↓ 依赖包：tokio-retry, backoff

恢复模式	适用场景	实现方式
重试	瞬时故障	指数退避
回退	降级模式	缓存值/默认值
熔断器	级联故障	failsafe-rs
超时	慢操作	`tokio::time::timeout`
舱壁隔离	隔离	独立的线程池

#[derive(thiserror::Error, Debug)]
pub enum AppError {
    // 面向用户
    #[error("Invalid input: {0}")]
    Validation(String),

    // 瞬时错误（可重试）
    #[error("Service temporarily unavailable")]
    ServiceUnavailable(#[source] reqwest::Error),

    // 内部错误（记录详细信息，显示通用信息）
    #[error("Internal error")]
    Internal(#[source] anyhow::Error),
}

impl AppError {
    pub fn is_retryable(&self) -> bool {
        matches!(self, Self::ServiceUnavailable(_))
    }
}

use tokio_retry::{Retry, strategy::ExponentialBackoff};

async fn with_retry<F, T, E>(f: F) -> Result<T, E>
where
    F: Fn() -> impl Future<Output = Result<T, E>>,
    E: std::fmt::Debug,
{
    let strategy = ExponentialBackoff::from_millis(100)
        .max_delay(Duration::from_secs(10))
        .take(5);

    Retry::spawn(strategy, || f()).await
}

错误做法	为何错误	更好的做法
所有错误都一样	不可操作	按受众分类
重试所有错误	浪费资源	仅重试瞬时错误
无限重试	导致自我拒绝服务	最大尝试次数 + 退避
暴露内部错误	安全风险	用户友好的消息
没有上下文	难以调试	处处使用 .context()

反面模式	为何不好	更好的做法
字符串错误	没有结构	thiserror 类型
对可恢复错误使用 panic!	用户体验差	带上下文的 Result
忽略错误	静默失败	记录或传播错误
处处使用 Box	丢失类型信息	thiserror
在正常路径中处理错误	性能问题	尽早验证

何时使用	参见
错误处理基础	m06-error-handling
重试实现	m07-concurrency
领域建模	m09-domain
面向用户的 API	domain-*

🇺🇸English

Domain Error Strategy

Layer 2: Design Choices

Core Question

Who needs to handle this error, and how should they recover?

Before designing error types:

Is this user-facing or internal?
Is recovery possible?
What context is needed for debugging?

Error Categorization

Error Type	Audience	Recovery	Example
User-facing	End users	Guide action	`InvalidEmail`, `NotFound`
Internal	Developers	Debug info	`DatabaseError`, `ParseError`
System	Ops/SRE	Monitor/alert	`ConnectionTimeout`, `RateLimited`
Transient	Automation	Retry	`NetworkError`, `ServiceUnavailable`
Permanent	Human	Investigate	`ConfigInvalid`, `DataCorrupted`

Thinking Prompt

Before designing error types:

Who sees this error?
- End user → friendly message, actionable
- Developer → detailed, debuggable
- Ops → structured, alertable
Can we recover?
- Transient → retry with backoff
- Degradable → fallback value
- Permanent → fail fast, alert
What context is needed?
- Call chain → anyhow::Context
- Request ID → structured logging
- Input data → error payload

Trace Up ↑

To domain constraints (Layer 3):

"How should I handle payment failures?"
    ↑ Ask: What are the business rules for retries?
    ↑ Check: domain-fintech (transaction requirements)
    ↑ Check: SLA (availability requirements)

Question	Trace To	Ask
Retry policy	domain-*	What's acceptable latency for retry?
User experience	domain-*	What message should users see?
Compliance	domain-*	What must be logged for audit?

Trace Down ↓

To implementation (Layer 1):

"Need typed errors"
    ↓ m06-error-handling: thiserror for library
    ↓ m04-zero-cost: Error enum design

"Need error context"
    ↓ m06-error-handling: anyhow::Context
    ↓ Logging: tracing with fields

"Need retry logic"
    ↓ m07-concurrency: async retry patterns
    ↓ Crates: tokio-retry, backoff

Quick Reference

Recovery Pattern	When	Implementation
Retry	Transient failures	exponential backoff
Fallback	Degraded mode	cached/default value
Circuit Breaker	Cascading failures	failsafe-rs
Timeout	Slow operations	`tokio::time::timeout`
Bulkhead	Isolation	separate thread pools

Error Hierarchy

#[derive(thiserror::Error, Debug)]
pub enum AppError {
    // User-facing
    #[error("Invalid input: {0}")]
    Validation(String),

    // Transient (retryable)
    #[error("Service temporarily unavailable")]
    ServiceUnavailable(#[source] reqwest::Error),

    // Internal (log details, show generic)
    #[error("Internal error")]
    Internal(#[source] anyhow::Error),
}

impl AppError {
    pub fn is_retryable(&self) -> bool {
        matches!(self, Self::ServiceUnavailable(_))
    }
}

Retry Pattern

use tokio_retry::{Retry, strategy::ExponentialBackoff};

async fn with_retry<F, T, E>(f: F) -> Result<T, E>
where
    F: Fn() -> impl Future<Output = Result<T, E>>,
    E: std::fmt::Debug,
{
    let strategy = ExponentialBackoff::from_millis(100)
        .max_delay(Duration::from_secs(10))
        .take(5);

    Retry::spawn(strategy, || f()).await
}

Common Mistakes

Mistake	Why Wrong	Better
Same error for all	No actionability	Categorize by audience
Retry everything	Wasted resources	Only transient errors
Infinite retry	DoS self	Max attempts + backoff
Expose internal errors	Security risk	User-friendly messages
No context	Hard to debug	.context() everywhere

Anti-Patterns

Anti-Pattern	Why Bad	Better
String errors	No structure	thiserror types
panic! for recoverable	Bad UX	Result with context
Ignore errors	Silent failures	Log or propagate
Box everywhere	Lost type info	thiserror
Error in happy path	Performance	Early validation

Related Skills

When	See
Error handling basics	m06-error-handling
Retry implementation	m07-concurrency
Domain modeling	m09-domain
User-facing APIs	domain-*

Weekly Installs

580

Repository

zhanghandong/rust-skills

GitHub Stars

912

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode533

codex518

gemini-cli508

github-copilot495

amp452

kimi-cli447

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

103,800 周安装

Rust领域错误处理策略：分类、恢复与最佳实践指南

🇨🇳中文介绍

领域错误策略

核心问题

错误分类

相关 Skills

思考提示

向上追溯 ↑

向下追溯 ↓

快速参考

错误层次结构

重试模式

常见错误

反面模式

相关技能