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

m13-domain-error by actionbook/rust-skills

72 周安装量

911 GitHub Stars

GitHub

安装命令

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

代码质量系统架构 Rust

🇨🇳中文介绍

领域错误策略

第 2 层：设计选择

核心问题

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

在设计错误类型之前：

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

错误分类

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

广告位招租

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

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

联系我们

相关 Skills

网页可访问性（A11y）开发指南：实现WCAG合规、键盘导航与屏幕阅读器支持

12,600 周安装

PostgreSQL表设计最佳实践：核心规则、数据类型选择与常见陷阱详解

12,500 周安装

API设计指南：REST/GraphQL设计原则、规范文档与版本控制策略

11,500 周安装

测试策略完整指南：单元/集成/E2E测试金字塔与自动化实践

11,200 周安装

在设计错误类型之前：

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

到领域约束（第 3 层）：

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

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

到实现（第 1 层）：

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

"需要错误上下文"
    ↓ m06-error-handling: anyhow::Context
    ↓ Logging: 使用字段的 tracing

"需要重试逻辑"
    ↓ m07-concurrency: 异步重试模式
    ↓ Crates: 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
}

错误做法	为何错误	更好的做法
所有错误都一样	不可操作	按受众分类
重试所有错误	浪费资源	仅重试暂时性错误
无限重试	自我 DoS	最大尝试次数 + 退避
暴露内部错误	安全风险	用户友好的消息
没有上下文	难以调试	处处使用 .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

Repository

actionbook/rust-skills

GitHub Stars

911

First Seen

Jan 23, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode69

gemini-cli68

codex67

github-copilot64

cursor62

kimi-cli59

代码库搜索技能指南：精准查找函数、追踪依赖、理解架构与定位错误

10,900 周安装

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

🇨🇳中文介绍

领域错误策略

核心问题

错误分类

相关 Skills

思考提示

向上追溯 ↑

向下追溯 ↓

快速参考

错误层次结构

重试模式

常见错误

反面模式

相关技能