Rust 错误处理分层策略：从 thiserror 到 anyhow 的工程化实践

Rust 错误处理分层策略：从 thiserror 到 anyhow 的工程化实践

一、错误处理的工程困境：Result 满天飞但信息丢失

Rust 的 Result<T, E> 强制开发者处理错误，这是安全性的保障。但实际项目中，错误处理往往走向两个极端：要么用 Box<dyn Error> 吞掉所有类型信息，调试时只能看字符串；要么为每个模块定义独立错误类型，From 转换写到手软。更常见的问题是：底层错误被层层包装后，原始上下文丢失——"IO 错误"不知道是哪个文件、"解析失败"不知道是哪个字段、"连接超时"不知道是哪个服务。分层错误处理策略是解决这些问题的关键。

graph TB
    A[错误处理策略] --> B[库层: thiserror<br/>强类型 + 可枚举]
    A --> C[应用层: anyhow<br/>上下文丰富 + 灵活]
    A --> D[边界层: 错误转换<br/>库错误 → 应用错误]

    B --> E[优势: 模式匹配<br/>API 可枚举]
    B --> F[劣势: 上下文不足<br/>转换繁琐]

    C --> G[优势: .context() 链<br/>灵活添加信息]
    C --> H[劣势: 不可模式匹配<br/>类型信息丢失]

    D --> I[核心原则:<br/>库暴露结构化错误<br/>应用附加上下文]

二、错误处理的底层机制与设计原则

2.1 Rust 错误处理的本质：值与传播

Rust 的 ? 操作符是错误传播的语法糖：如果 Result 是 Err，立即从当前函数返回；如果是 Ok，解包继续执行。? 要求当前函数的返回错误类型与被传播的错误类型之间实现 From 转换。

graph LR
    A[底层 IO 错误] -->|? 传播| B[解析层错误]
    B -->|? 传播| C[业务层错误]
    C -->|? 传播| D[应用层错误]

    A -->|From 转换| B
    B -->|From 转换| C
    C -->|From 转换| D

    D --> E[最终错误链:<br/>应用上下文 → 业务原因 → 解析细节 → IO 根因]

2.2 thiserror 的派生宏原理

thiserror 通过 #[derive(Error)] 自动实现 std::error::Error trait 和 Display trait。#[source] 标注错误来源，自动实现 Error::source() 方法，形成错误链。#[from] 自动实现 From 转换，支持 ? 传播。

2.3 anyhow 的上下文链原理

anyhow 的 context() 方法将原始错误包装为 Context 结构体，保存附加信息和新错误，形成链表。打印时从外到内遍历链表，输出完整的上下文信息。

三、生产级代码实现与最佳实践

3.1 库层错误定义（thiserror）

use thiserror::Error;

/// 数据库访问层错误
#[derive(Error, Debug)]
pub enum DbError {
    #[error("连接池耗尽: 等待超时 {timeout_ms}ms")]
    PoolExhausted { timeout_ms: u64 },

    #[error("查询执行失败: {query}")]
    QueryFailed {
        query: String,
        #[source]
        source: sqlx::Error,
    },

    #[error("记录未找到: {table} WHERE {condition}")]
    NotFound { table: String, condition: String },

    #[error("事务冲突: {reason}")]
    Conflict { reason: String },
}

/// 解析层错误
#[derive(Error, Debug)]
pub enum ParseError {
    #[error("JSON 解析失败: {path}")]
    JsonError {
        path: String,
        #[source]
        source: serde_json::Error,
    },

    #[error("配置格式错误: 字段 '{field}' 期望 {expected}，实际 {actual}")]
    FormatMismatch {
        field: String,
        expected: String,
        actual: String,
    },

    #[error("缺少必填字段: {field}")]
    MissingField { field: String },
}

/// 业务层错误（组合底层错误）
#[derive(Error, Debug)]
pub enum ServiceError {
    #[error("用户服务异常")]
    UserError(#[from] DbError),

    #[error("配置加载异常")]
    ConfigError(#[from] ParseError),

    #[error("权限不足: 需要 {required}，当前 {current}")]
    PermissionDenied { required: String, current: String },

    #[error("限流: 每分钟最多 {limit} 次请求")]
    RateLimited { limit: u32 },
}

3.2 应用层错误处理（anyhow + context）

use anyhow::{Context, Result, anyhow};

/// 应用层函数：使用 anyhow 添加丰富的上下文信息
pub fn load_user_config(path: &str) -> Result<UserConfig> {
    let content = std::fs::read_to_string(path)
        .with_context(|| format!("读取配置文件失败: {}", path))?;

    let config: UserConfig = serde_json::from_str(&content)
        .with_context(|| format!("解析配置文件失败: {}", path))?;

    // 业务校验
    if config.max_connections == 0 {
        return Err(anyhow!(
            "配置校验失败: max_connections 不能为 0 (文件: {})", path
        ));
    }

    Ok(config)
}

/// 多步操作：每一步都添加上下文
pub fn initialize_service(config_path: &str) -> Result<()> {
    let config = load_user_config(config_path)
        .context("服务初始化失败: 无法加载配置")?;

    let pool = create_connection_pool(&config)
        .context("服务初始化失败: 连接池创建失败")?;

    run_migrations(&pool)
        .context("服务初始化失败: 数据库迁移失败")?;

    Ok(())
}

/// 从 anyhow 错误中提取具体的库层错误类型
pub fn handle_service_error(err: anyhow::Error) -> String {
    // 检查是否为特定的库层错误
    if let Some(db_err) = err.downcast_ref::<DbError>() {
        match db_err {
            DbError::PoolExhausted { timeout_ms } => {
                format!("数据库连接池耗尽，请稍后重试 (超时: {}ms)", timeout_ms)
            }
            DbError::NotFound { table, condition } => {
                format!("数据不存在: {} WHERE {}", table, condition)
            }
            _ => format!("数据库错误: {}", db_err),
        }
    } else if let Some(parse_err) = err.downcast_ref::<ParseError>() {
        format!("配置错误: {}", parse_err)
    } else {
        format!("未知错误: {:?}", err)
    }
}

3.3 错误链的完整打印与日志记录

use tracing::{error, warn, info};
use anyhow::Error;

/// 打印完整错误链（包含所有上下文）
pub fn log_error_chain(err: &Error) {
    // 打印最外层错误
    error!("错误: {}", err);

    // 打印错误链中的每一层上下文
    let mut cause = err.source();
    let mut depth = 1;
    while let Some(e) = cause {
        error!("  原因[{}]: {}", depth, e);
        cause = e.source();
        depth += 1;
    }

    // 打印 anyhow 的 context 链
    for (i, ctx) in err.chain().enumerate() {
        if i > 0 {
            warn!("  上下文[{}]: {}", i, ctx);
        }
    }
}

/// HTTP API 错误响应转换
pub fn error_to_http_response(err: Error) -> (u16, String) {
    // 根据错误类型返回不同的 HTTP 状态码
    if let Some(ServiceError::RateLimited { limit }) = err.downcast_ref() {
        (429, format!("请求过于频繁，每分钟最多 {} 次", limit))
    } else if let Some(ServiceError::PermissionDenied { .. }) = err.downcast_ref() {
        (403, "权限不足".to_string())
    } else if let Some(DbError::NotFound { .. }) = err.downcast_ref() {
        (404, "资源不存在".to_string())
    } else if let Some(DbError::Conflict { .. }) = err.downcast_ref() {
        (409, "数据冲突".to_string())
    } else {
        (500, "内部服务错误".to_string())
    }
}

四、错误处理策略的架构权衡

4.1 thiserror vs anyhow 适用场景

4.2 错误转换的维护成本

每新增一个底层错误类型，都需要在业务层添加 #[from] 转换。当底层模块多时，业务层错误枚举会膨胀。解决方案：按领域分组错误，避免一个巨型枚举。

4.3 适用边界与禁用场景

thiserror 适用：

• 公共库/SDK 的错误类型定义
• 需要调用者模式匹配处理的场景
• 错误类型是 API 契约的一部分

anyhow 适用：

• 应用顶层 main 函数
• 中间件/胶水代码的错误传播
• 不需要调用者区分错误类型的场景

禁用场景：

• 不要在库的公共 API 返回 anyhow::Error（调用者无法模式匹配）
• 不要用字符串拼接传递错误信息（丢失结构化数据）
• 不要忽略错误（let _ = risky_operation()），至少记录日志

五、总结

Rust 错误处理的核心原则是"分层"：库层用 thiserror 定义强类型错误，保证 API 可枚举和可模式匹配；应用层用 anyhow 添加上下文信息，保证错误链可追溯。两者的桥梁是 #[from] 自动转换和 downcast 运行时类型提取。错误链的完整性决定了排障效率——"连接超时"和"用户服务连接超时：尝试连接 10.0.1.5:5432 失败"的信息量差了十倍。好的错误处理不是消除错误，而是让每一个错误都携带足够的上下文，让排查者能快速定位根因。