Rust错误处理体系：thiserror、anyhow与错误链

背景与问题界定

在开发一个多层Rust服务（配置中心SDK + 核心引擎 + gRPC API层）的过程中，不同层次的错误处理方式出现了显著的不一致性。底层SDK返回io::Error和自定义枚举错误；引擎层将这些底层错误包装成自己的EngineError；API层又需要将引擎错误映射为gRPC状态码。随着层数的增加，错误类型的转换和传播路径变得混乱——有的地方用Box<dyn Error>做类型擦除，有的地方用自定义枚举包裹，被调函数的错误被直接unwrap或expect，导致线上panic。更棘手的是，需要追踪一个错误的完整来源链（例如是"文件不存在"→“配置加载失败”→“引擎初始化终止”→“服务注册失败”），但当时的错误包装方式丢失了上下文信息。

目标拆解与工程约束

库与应用的错误处理分离：底层库应该定义精确的错误类型（自定义enum），让调用者可以用match或map_err做程序化处理。而上层应用更适合使用anyhow的anyhow::Error做类型擦除和上下文添加。但库如果依赖了anyhow，所有调用方都被迫进入anyhow生态——这是一个错误的设计决策。
错误链的上下文保持：source() 方法定义了错误链，但实现时经常遗漏 #[source] 或 #[from] 标注，导致链断裂。需要保证每层错误包装都保留底层错误的引用，且不破坏Send + Sync约束。
panic vs 返回值决策：对于不可恢复的错误（内存分配失败、断言失败），panic是合理的；但对于可预期的外部故障（网络超时、配置缺失），必须使用Result。问题在于"可恢复"的边界在团队中没有统一认识，导致一些可以优雅降级的场景直接panic了。
跨Crate的错误兼容性：多个Crate定义了各自的错误类型，但它们之间经常需要互转。手动实现From<T>的每个组合是O(n²)的工作量。需要统一错误类型的设计模式，减少手动转换的重复劳动。

方案设计

我们采用"分层错误模型"，在每个层级的边界上使用不同的错误处理策略：

底层SDK Crate：使用thiserror 定义精确的 #[derive(Error)] enum。每种失败原因是一个variant，携带相关的结构化数据。通过#[from] 自动生成From实现，通过#[source] 标注底层错误。

#[derive(Error, Debug)]
pub enum ConfigStoreError {
    #[error("IO error reading config from {path}")]
    IoError {
        #[source]
        source: io::Error,
        path: PathBuf,
    },
    #[error("deserialization failed: {detail}")]
    DeserializeError {
        #[source]
        source: serde_json::Error,
        detail: String,
    },
    #[error("configuration key `{key}` not found")]
    KeyNotFound { key: String },
    #[error("watch stream terminated unexpectedly")]
    WatchTerminated,
}

应用层：使用anyhow 统一错误载体。在调用底层库的边界上，使用context() 方法添加上下文信息，将底层的结构化错误转换为anyhow::Error。这样应用层代码不用关心错误的具体类型，只需记录错误链的每一个"发生了什么"的上下文。

use anyhow::{Context, Result};

fn load_and_sync() -> Result<ConfigSnapshot> {
    let store = ConfigStore::new()
        .with_context(|| "failed to initialize config store")?;
    let snapshot = store.load("app-config.yaml")
        .with_context(|| "failed to load config from store")?;
    sync_to_peers(&snapshot)
        .with_context(|| "failed to sync snapshot to peer nodes")?;
    Ok(snapshot)
}

API层：通过From<&anyhow::Error> 将anyhow错误映射为gRPC状态码或HTTP响应。关键设计是保留错误链各层的上下文信息，在日志中打印完整错误链（通过{:#}格式化）。

实施路径与关键决策

制定"错误处理策略文档"：明确规定：库代码必须使用thiserror的自定义enum；应用代码使用anyhow；API边界做错误映射。panic仅用于内部断言和不可恢复状态，所有外部可观测的失败必须通过Result返回。
使用eyre作为anyhow替代：在某些需要自定义报告格式的场景（如输出到Sentry、OpenTelemetry），使用eyre并自定义EyreHandler来捕获span信息。
禁止unwrap和expect（除了测试）与极小部分确认不会失败的地方：所有Result必须显式处理。通过clippy的clippy::unwrap_used lint强制。

验证指标与可持续迭代

迁移后线上panic频率从每千请求0.7次降为0次。错误日志的可追溯性提升——通过OpenTelemetry，每个错误的完整链被记录为span events，facilitate根因分析的效率提升60%。新增Crate必须遵循分层错误模型，通过CI中的cargo check --deny unwrap_used和自定义review检查。

工程落地思考

Rust的错误处理体系是语言设计中最为精心雕琢的部分之一。thiserror和anyhow分别对应了"精确类型"和"方便使用"这两极，在大型项目中应当同时存在，但严格划分边界。最大的实践误区是"全栈anyhow"或"全栈thiserror"——前者让调用者失去了通过match精确处理错误的能力，后者让应用层代码充斥着错误类型转换的样板代码。正确的做法是在错误堆栈的每一层做一次"类型爆炸"而非"类型收敛"：跨边界时损失类型精度换取使用便利，在边界内侧保持类型精度换取可靠处理。