Rust 错误处理：从 Result 到 thiserror，生产级方案怎么选？

Rust 错误处理：从 Result 到 thiserror，生产级方案怎么选？

一、当编译器不再帮你兜底：Rust 错误处理的现实困境

写 Rust 的人大概都经历过这种时刻：代码逻辑明明没问题，编译器却死活不让过，原因只是你忘了处理一个 Result。这种体验在刚开始学 Rust 的时候，简直让人怀疑人生。但冷静下来想，这恰恰是 Rust 的核心设计哲学——错误不是异常，不是你可以假装看不见的东西，而是必须被显式处理的返回值。

在 C 语言里，错误码被随意忽略是家常便饭。在 Java 里，try-catch 包裹一切，异常在调用栈里层层上抛，你永远不知道哪一层会吞掉它。Rust 选择了第三条路：用类型系统强制你面对错误。这条路的好处是可靠性，代价是心智负担。

生产环境里，错误处理远不止"unwrap 还是 match"这么简单。一个 CLI 工具需要给用户友好的错误提示，一个库需要给调用方结构化的错误类型，一个异步服务需要把错误正确地传播到 tokio 运行时。这些场景对错误处理的要求各不相同，选错方案，要么代码到处是样板，要么运行时信息丢失。

二、Result、Option 与错误传播：类型层面的安全网

Rust 的错误处理建立在两个核心类型之上：Option<T> 表示可能缺席的值，Result<T, E> 表示可能失败的计算。它们不是语法糖，而是类型系统的一等公民。

graph TD
    A[函数执行] --> B{计算结果}
    B -->|成功| C[Ok T]
    B -->|可恢复错误| D[Err E]
    B -->|逻辑缺席| E[None]
    C --> F[继续处理]
    D --> G[match 显式处理]
    D --> H[? 运算符传播]
    E --> I[unwrap_or 提供默认]
    E --> J[ok_or 转为 Result]

? 运算符是错误传播的核心机制。它不是简单的语法糖，而是一个涉及 From trait 的类型转换过程。当 ? 执行时，如果遇到 Err(e)，它会尝试将 e 通过 From::from() 转换成当前函数的返回错误类型，然后提前返回。这意味着你可以用 ? 把不同模块的错误类型无缝地传播到同一个错误链里。

但这里有个坑：? 只能在返回 Result 的函数里使用。如果你在 main 函数里直接用 ?，Rust 2021 edition 之前是不行的。2021 edition 之后，main 可以返回 Result<(), Box<dyn Error>>，这给了 CLI 工具一个简洁的入口。

三、从手写 Error 到 thiserror：生产级错误类型的演进

先看一个最基础的自定义错误类型：

use std::fmt;
use std::error::Error;

/// 数据库连接错误类型
#[derive(Debug)]
enum DbError {
    /// 连接超时，携带超时时长（毫秒）
    ConnectionTimeout(u64),
    /// 认证失败，携带原因描述
    AuthFailed(String),
    /// 查询执行失败，携带 SQL 语句和底层错误
    QueryFailed { sql: String, source: io::Error },
}

impl fmt::Display for DbError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            DbError::ConnectionTimeout(ms) => {
                write!(f, "数据库连接超时，等待了 {}ms", ms)
            }
            DbError::AuthFailed(reason) => {
                write!(f, "数据库认证失败：{}", reason)
            }
            DbError::QueryFailed { sql, source } => {
                write!(f, "查询执行失败 [{}]，原因：{}", sql, source)
            }
        }
    }
}

impl Error for DbError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        match self {
            DbError::QueryFailed { source, .. } => Some(source),
            _ => None,
        }
    }
}

手写 Display 和 Error 实现很繁琐，尤其是错误变体多的时候。thiserror 就是来解决这个问题的：

use thiserror::Error;
use std::io;

/// 使用 thiserror 派生宏简化错误类型定义
#[derive(Error, Debug)]
enum DbError {
    /// 连接超时错误，自动生成 Display 实现
    #[error("数据库连接超时，等待了 {0}ms")]
    ConnectionTimeout(u64),

    /// 认证失败错误
    #[error("数据库认证失败：{0}")]
    AuthFailed(String),

    /// 查询执行失败，通过 source 属性自动实现 Error::source
    #[error("查询执行失败 [{sql}]，原因：{source}")]
    QueryFailed {
        sql: String,
        #[source]
        source: io::Error,
    },
}

thiserror 的核心优势在于：用声明式的方式替代手写样板代码，#[error(...)] 属性同时处理了 Display 实现，#[source] 属性自动处理了错误链。在库的开发中，thiserror 几乎是标配。

对于应用层，anyhow 提供了另一种思路。它不关心错误类型的具体结构，只关心错误信息的可读性和上下文附加：

use anyhow::{Context, Result};

/// 从配置文件加载数据库配置
fn load_db_config(path: &str) -> Result<DbConfig> {
    let content = std::fs::read_to_string(path)
        .context(format!("无法读取配置文件：{}", path))?;
    let config: DbConfig = toml::from_str(&content)
        .context("配置文件格式解析失败")?;
    Ok(config)
}

context() 方法在不改变错误类型的前提下，给错误链追加上下文信息。这在应用层非常实用——你不需要为每个操作定义专门的错误类型，只需要在关键节点加上"当时在做什么"的说明。

四、thiserror 与 anyhow 的适用边界与架构取舍

选择错误处理方案，本质上是在"类型安全"和"开发效率"之间做权衡。

thiserror 适合库的开发。库的消费者需要根据错误类型做不同的处理逻辑，match 一个具体的枚举比 downcast 一个 anyhow::Error 要自然得多。如果你的 API 需要向调用方暴露错误的结构，thiserror 是正确选择。

anyhow 适合应用层。CLI 工具、Web 服务、后台任务——这些场景下，错误的最终消费者是人，不是代码。你需要的是清晰的错误信息和完整的上下文链，而不是精确的类型匹配。

但两者不是互斥的。一个常见的架构模式是：库内部用 thiserror 定义精确的错误类型，应用层用 anyhow 收集和传播这些错误，同时附加业务上下文。thiserror 定义的错误类型天然实现了 Into<anyhow::Error>，所以这个组合是无缝的。

需要注意的坑：anyhow 的 Error 类型不是 Send + Sync 的（在旧版本中），这在某些异步场景下会出问题。1.0 版本之后已经修复，但如果你在维护老代码，这个点值得排查。另外，anyhow 的错误信息在跨线程传播时可能会丢失 backtrace，这在调试并发问题时是个痛点。

另一个常被忽略的问题是错误信息的国际化。thiserror 的 #[error(...)] 里写的字符串会直接成为 Display 输出，如果你需要支持多语言，就需要在 Display 实现里做翻译映射，而不是依赖派生宏。这种场景下，手写 Display 反而更灵活。

五、总结

Rust 的错误处理体系建立在类型系统之上，Result 和 Option 是编译器强制你面对错误的工具。? 运算符通过 From trait 实现了跨类型的错误传播，这是整个机制的粘合层。thiserror 适合库开发，提供类型精确、可 match 的错误枚举；anyhow 适合应用层，提供上下文附加和简洁的错误传播。两者可以组合使用：库用 thiserror，应用用 anyhow。选择方案时，核心判断标准是错误的消费者是代码还是人。生产环境中，错误处理不只是"让编译通过"，更是给调试和运维留足信息。