Rust 错误处理工程实战：从 anyhow 到 thiserror 的全景指南

错误处理是 Rust 最受赞誉的特性之一，但也是新手最容易产生困惑的地方。Result<E, T>、? 操作符、unwrap() 的取舍、Box<dyn Error> 的性能隐患——这些看似零散的概念，背后是一套完整的错误处理哲学。本文将从工程实践出发，梳理 Rust 错误处理的完整生态。

---

1. 错误处理的类型学

在深入代码之前，必须先理解 Rust 社区对错误的分类方式。这种分类决定了你在不同场景下应选择哪种策略。

1.1 不可恢复错误 vs 可恢复错误

Rust 将错误分为两大类：

• 不可恢复错误（Panic）：程序遇到了无法继续执行的严重问题（越界、栈溢出等）。通过 panic! 触发，默认行为是线程终止。
• 可恢复错误（Result）：预期内可能发生的错误（文件不存在、网络超时等），通过 Result<T, E> 表达，要求调用方显式处理。

这个区分至关重要：panic 是 crash，Result 是 control flow。在生产代码中，panic 应仅用于编程错误（invariant violation）或启动时的配置校验。

1.2 Library 错误 vs Application 错误

在实践中，错误处理策略因角色不同而截然不同：

维度	Library 错误	Application 错误
暴露方式	定义明确的枚举类型	通常用 Box<dyn Error> 或 anyhow::Error
匹配需求	调用方需要精确匹配	通常只需打印或记录
性能要求	高（避免堆分配）	相对宽松
反序列化	需要（跨 FFI、序列化边界）	通常不需要
生态标准	thiserror	anyhow / eyre

这个区分是理解整个错误生态的关键锚点。

---

2. thiserror：库级错误的标准解法

2.1 为什么需要 thiserror？

手写 std::error::Error impl 很繁琐：

// 手写 Error impl 的痛苦
#[derive(Debug)]
pub enum ParseError {
    Io(std::io::Error),
    InvalidFormat { line: usize, msg: String },
}

impl std::fmt::Display for ParseError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Io(e) => write!(f, "IO error: {}", e),
            Self::InvalidFormat { line, msg } => {
                write!(f, "parse error at line {}: {}", line, msg)
            }
        }
    }
}

impl std::error::Error for ParseError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            Self::Io(e) => Some(e),
            _ => None,
        }
    }
}

impl From<std::io::Error> for ParseError {
    fn from(e: std::io::Error) -> Self {
        Self::Io(e)
    }
}

#[derive(thiserror::Error)] 将上述代码压缩为十几行：

#[derive(thiserror::Error, Debug)]
pub enum ParseError {
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),

    #[error("parse error at line {line}: {msg}")]
    InvalidFormat { line: usize, msg: String },
}

2.2 生产级错误类型设计模式

在实际项目中，错误类型的设计远比上面的例子复杂。以下是几个关键模式：

模式一：分层错误类型

// storage.rs - 存储层错误
#[derive(thiserror::Error, Debug)]
pub enum StorageError {
    #[error("connection failed: {0}")]
    ConnectionFailed(#[from] tonic::transport::Error),

    #[error("key not found: {key}")]
    NotFound { key: String },

    #[error("serialization error: {0}")]
    Serialization(#[from] serde_json::Error),

    #[error("timeout after {0:?}")]
    Timeout(std::time::Duration),
}

// service.rs - 服务层错误
#[derive(thiserror::Error, Debug)]
pub enum ServiceError {
    #[error("storage error: {0}")]
    Storage(#[from] StorageError),

    #[error("permission denied: user={user}, resource={resource}")]
    PermissionDenied { user: String, resource: String },

    #[error("invalid input: {0}")]
    InvalidInput(String),

    #[error("rate limited: retry after {retry_after_secs}s")]
    RateLimited { retry_after_secs: u64 },
}

关键设计原则：每一层只添加本层特有的错误变体，下层错误通过 #[from] 透明传播。

模式二：携带调试上下文

#[derive(thiserror::Error, Debug)]
pub enum ApiError {
    #[error("failed to fetch user {user_id} from provider {provider}")]
    UserFetch {
        provider: String,
        user_id: u64,
        #[source]
        source: reqwest::Error,
    },
}

注意 #[source] 属性：它告诉 thiserror 这是底层错误源（实现 source() ），与其他"纯上下文"字段区分开。

模式三：支持 downcast 精确匹配

#[derive(thiserror::Error, Debug)]
pub enum PipelineError {
    #[error("stage {stage} failed: {reason}")]
    StageFailed {
        stage: String,
        reason: String,
        recoverable: bool,
        #[source]
        source: Box<dyn std::error::Error + Send + Sync>,
    },
}

2.3 性能考量

thiserror 生成的错误类型默认是 栈上分配的（不涉及堆分配），这对热路径至关重要：

Result<T, ParseError>   // 大小 = max(T, ParseError) + 1 byte discriminant
Result<T, anyhow::Error> // 固定 2 个指针宽度的胖指针（Always 16 bytes on 64-bit）

关键性能差异： - thiserror 错误：无堆分配、无虚函数调用，match 可内联 - anyhow::Error 错误：默认有堆分配（Box）、vtable 间接调用（但做了优化）

在 tight loop 中（如解析器、序列化器），应使用 thiserror 类型而非 anyhow。

---

3. anyhow：应用层错误的瑞士军刀

3.1 核心特性

anyhow 提供了 anyhow::Error 类型，它本质上是一个 Box<dyn Error + Send + Sync + 'static> 的优化包装：

• 零样板：自动为任何实现 Error 的类型提供 From impl
• 上下文附加：.context() 和 .with_context() 链附加语义信息
• Backtrace 支持：在 RUST_BACKTRACE=1 环境下自动捕获
• Downcast 反射：允许回退到精确类型匹配

3.2 上下文附加的工程价值

// 没有 context 的错误信息：
// "No such file or directory (os error 2)"

// 有 context 的错误信息：
// "failed to load config for service 'payment-svc' from /etc/payment.toml: No such file or directory (os error 2)"

在微服务架构中，一条没有上下文的错误日志几乎毫无调试价值。anyhow 让上下文附加变得廉价：

use anyhow::Context;

fn load_config(path: &Path) -> Result<Config> {
    let content = std::fs::read_to_string(path)
        .with_context(|| format!("failed to read config file: {}", path.display()))?;

    let config: Config = toml::from_str(&content)
        .context("failed to parse TOML config")?;

    Ok(config)
}

fn init_payment_service() -> Result<PaymentService> {
    let config = load_config(Path::new("/etc/payment.toml"))
        .context("failed to initialize payment service: config loading failed")?;
    // ...
}

3.3 bail! 和 ensure! 宏

use anyhow::{bail, ensure};

fn validate_port(port: u16) -> Result<()> {
    ensure!(port >= 1024, "port {} is in reserved range (0-1023)", port);
    ensure!(port != 8080, "port 8080 is already occupied by legacy service");
    Ok(())
}

fn connect(addr: SocketAddr) -> Result<TcpStream> {
    match TcpStream::connect(addr) {
        Ok(stream) => Ok(stream),
        Err(e) if e.kind() == std::io::ErrorKind::ConnectionRefused => {
            bail!("connection to {} refused — is the service running?", addr)
        }
        Err(e) => Err(e).context(format!("failed to establish TCP connection to {}", addr)),
    }
}

3.4 anyhow vs eyre vs color-eyre

特性	anyhow	eyre	color-eyy
目标用户	通用应用	命令行应用	命令行应用（彩色输出）
Sentry/Sitecat 支持	需要手动集成	内置 Hook	内置 Hook
错误报告生成	需要 RUST_LIB_BACKTRACE	自动彩色报告	自动彩色报告
性能	最优	略慢（spantrace）	略慢
异步支持	Send + Sync 默认	Send + Sync 默认	Send + Sync 默认
推荐场景	服务端应用	CLI 工具	CLI 工具（开发体验优先）
工程适用性	★★★★★	★★★☆☆	★★★☆☆

服务端应用优先选择 anyhow：性能更好、依赖更少、Sentry 集成更成熟。

---

4. 错误转换与兼容层

4.1 ? 操作符的工作原理

? 操作符在展开时执行以下逻辑：

// 源码
let value = some_fallible_operation()?;

// 展开后（简化版）
let value = match some_fallible_operation() {
    Ok(v) => v,
    Err(e) => {
        let e = From::from(e);  // 隐式调用 From _trait 进行类型转换
        return Err(e);
    }
};

这意味着只要存在 impl From<SourceError> for TargetError，? 就能自动转换错误类型。

4.2 不同错误类型间的桥接

当需要同时使用 thiserror 错误和 anyhow::Error 时：

// 在现代 Rust 中，anyhow::Error 可以自动从任何 std::error::Error 转换
fn library_function() -> Result<Data, MyLibraryError> {
    // ...
}

fn application_function() -> anyhow::Result<Data> {
    // 自动通过 From<dyn Error> 转换
    let data = library_function()?;
    Ok(data)
}

// 反向：从 anyhow 转为具体错误类型（通过 downcast）
fn try_recover(error: &anyhow::Error) -> Option<MyLibraryError> {
    error.downcast_ref::<MyLibraryError>().cloned()
}

4.3 std::io::Error 的自定义种类

Rust 标准库的 io::Error 有一个常被忽视的能力——创建自定义 IO 错误：

use std::io::{Error, ErrorKind};

fn map_storage_error(e: StorageError) -> Error {
    match e {
        StorageError::NotFound { .. } => {
            Error::new(ErrorKind::NotFound, e)
        }
        StorageError::Timeout(_) => {
            Error::new(ErrorKind::TimedOut, e)
        }
        StorageError::ConnectionFailed(_) => {
            Error::new(ErrorKind::ConnectionRefused, e)
        }
    }
}

这对于需要返回 io::Error 的 trait（如 std::io::Read）非常有用。

---

5. 异步错误处理

5.1 async 函数中的错误

异步函数中的错误处理本质上与同步代码一致——Result 仍然有效：

async fn fetch_user(id: u64) -> Result<User, ApiError> {
    let response = reqwest::get(format!("https://api.example.com/users/{}", id))
        .await
        .map_err(ApiError::Network)?;

    if response.status() == 404 {
        return Err(ApiError::UserNotFound(id));
    }

    response.json::<User>()
        .await
        .map_err(ApiError::Deserialize)
}

5.2 join! 和 select! 中的错误处理

在并发场景中，错误处理需要特别小心：

use futures::join;

// join! 策略：所有 future 都完成才返回，任一错误整体失败
async fn fetch_all(user_id: u64) -> Result<(UserProfile, Vec<Order>)> {
    let (profile, orders) = join!(
        fetch_profile(user_id),
        fetch_orders(user_id),
    );
    // 需要分别处理每个 future 的结果
    Ok((profile?, orders?))
}

use futures::select;

// select! 策略：首个完成的 future 胜出，其他被 drop（可能导致隐式 cancel）
async fn fetch_with_timeout(url: &str) -> Result<String> {
    select! {
        result = fetch(url).fuse() => result,
        _ = tokio::time::sleep(Duration::from_secs(5)).fuse() => {
            Err(ServiceError::Timeout(Duration::from_secs(5)))
        }
    }
}

5.3 Stream 中的错误传播

use futures::stream::{self, StreamExt};

async fn process_events() -> Result<()> {
    let events = event_stream(); // impl Stream<Item = Result<Event, StreamError>>

    events
        .try_for_each(|event| async move {
            handle_event(event).await?;
            Ok(())
        })
        .await?;

    Ok(())
}

// try_for_each 会在遇到第一个 Err 时立即终止流

关键概念：Stream + Result 的组合有专门的处理方式，使用 try_for_each、try_collect、try_filter 等扩展方法。

---

6. 生产实践：HTTP API 错误响应

6.1 统一错误响应格式

在 web 服务中，需要统一错误响应结构：

use axum::{response::{IntoResponse, Response}, Json, http::StatusCode};
use serde::Serialize;

#[derive(Serialize)]
struct ErrorResponse {
    error: ErrorDetail,
}

#[derive(Serialize)]
struct ErrorDetail {
    code: String,
    message: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    details: Option<serde_json::Value>,
    request_id: String,
}

impl IntoResponse for ServiceError {
    fn into_response(self) -> Response {
        let (status, code) = match &self {
            Self::Storage(e) => (StatusCode::INTERNAL_SERVER_ERROR, "STORAGE_ERROR"),
            Self::PermissionDenied { .. } => (StatusCode::FORBIDDEN, "PERMISSION_DENIED"),
            Self::InvalidInput(_) => (StatusCode::BAD_REQUEST, "INVALID_INPUT"),
            Self::RateLimited { .. } => (StatusCode::TOO_MANY_REQUESTS, "RATE_LIMITED"),
        };

        let error_response = ErrorResponse {
            error: ErrorDetail {
                code: code.to_string(),
                message: self.to_string(),
                details: None,
                request_id: get_current_request_id(),
            },
        };

        (status, Json(error_response)).into_response()
    }
}

6.2 错误到 HTTP 状态码的映射策略

业务错误              → 4xx 系列
  - 参数校验失败      → 400
  - 未授权            → 401
  - 权限不足          → 403
  - 资源不存在        → 404
  - 冲突（重复创建）  → 409
  - 限流              → 429

基础设施错误          → 5xx 系列
  - 数据库连接失败    → 503
  - 超时              → 504
  - 降级失败          → 500

外部服务错误          → 5xx 系列
  - 上游超时          → 504
  - 上游返回错误      → 502

关键原则：不要把内部错误细节暴露给外部（防止信息泄露），但在错误日志中保留完整的 error chain。

---

7. 可观测性与错误追踪

7.1 tracing 生态集成

use tracing::{error, instrument, Span};

#[instrument(err(Debug), skip(db))]
async fn get_user(db: &Database, id: u64) -> Result<User, ServiceError> {
    let user = db.query_user(id).await.map_err(|e| {
        error!(error = ?e, user_id = id, "database query failed");
        ServiceError::Storage(StorageError::from(e))
    })?;

    Span::current().record("user_id", user.id);
    Ok(user)
}

// 关键：#[instrument(err(Debug))] 自动在 span 中记录 error 事件

7.2 Error Chain 打印

fn print_error_chain(error: &dyn std::error::Error) {
    eprintln!("Error: {}", error);

    let mut source = error.source();
    let mut depth = 1;
    while let Some(e) = source {
        eprintln!("  {}Caused by: {}", "  ".repeat(depth), e);
        source = e.source();
        depth += 1;
    }
}

anyhow 默认的 #Debug 输出已经提供了完整的 error chain，但 thiserror 需要手动启用：

// 在 anyhow 中
println!("{:?}", err); // 自动打印 chain

// 在 thiserror 中
// 需要调用 .source() 手动遍历

---

8. FFI 边界错误处理

8.1 Rust → C 的错误传递

// Rust 侧
#[no_mangle]
pub extern "C" fn parse_config(data: *const u8, len: usize, out: *mut usize) -> i32 {
    let result = std::panic::catch_unwind(|| {
        let slice = unsafe { std::slice::from_raw_parts(data, len) };
        parse_config_inner(slice).map(|config| {
            // ...
        })
    });

    match result {
        Ok(Ok(len)) => {
            unsafe { *out = len; }
            0 // OK
        }
        Ok(Err(e)) => {
            LAST_ERROR.set(e.to_string());
            -1 // 业务错误
        }
        Err(_) => {
            LAST_ERROR.set("internal panic".to_string());
            -2 // Panic
        }
    }
}

8.2 C → Rust 的错误传递

#[derive(thiserror::Error, Debug)]
pub enum FfiError {
    #[error("null pointer argument: {arg}")]
    NullPointer { arg: &'static str },

    #[error("C string is not valid UTF-8")]
    InvalidUtf8(#[from] std::str::Utf8Error),

    #[error("buffer too small: required {required}, got {actual}")]
    BufferTooSmall { required: usize, actual: usize },
}

unsafe fn wrap_c_str<'a>(ptr: *const c_char) -> Result<&'a str, FfiError> {
    if ptr.is_null() {
        return Err(FfiError::NullPointer { arg: "ptr" });
    }
    let c_str = CStr::from_ptr(ptr);
    Ok(c_str.to_str()?)
}

---

9. 测试中的错误断言

9.1 精确错误匹配

#[test]
fn test_parse_invalid_input() {
    let result = parse("invalid");
    assert!(result.is_err());
    assert!(matches!(result.unwrap_err(), ParseError::InvalidFormat { .. }));
}

9.2 错误消息断言

#[test]
fn test_config_error_has_context() {
    let err = load_config("nonexistent.toml").unwrap_err();

    // 使用 anyhow 的 context 链
    let err_str = format!("{:?}", err);
    assert!(err_str.contains("failed to read config"));
    assert!(err_str.contains("nonexistent.toml"));
}

9.3 使用 assert_matches!

use assert_matches::assert_matches;

#[test]
fn test_rate_limiting() {
    let action = || {
        for _ in 0..100 {
            call_api()?;
        }
        Ok(())
    };

    assert_matches!(action(), Err(ServiceError::RateLimited { .. }));
}

---

10. 常见陷阱与反模式

10.1 unwrap() 的滥用

// 反模式：在库代码中使用 unwrap()
pub fn process(data: &[u8]) -> Data {
    let header = parse_header(data).unwrap(); // 可能 panic
    // ...
}

// 正确做法
pub fn process(data: &[u8]) -> Result<Data, ProcessError> {
    let header = parse_header(data)?; // 传播错误
    // ...
}

10.2 过度使用 expect() 替代错误传播

// 反模式
let port = env::var("PORT").expect("PORT must be set");

// 优雅降级
let port = env::var("PORT").unwrap_or_else(|_| "8080".to_string());

// 正确做法（应用启动时验证）
let port: u16 = env::var("PORT")
    .unwrap_or_else(|_| "8080".to_string())
    .parse()
    .context("invalid PORT value")?;

10.3 错误类型过大

// 反模式：用 String 做错误
fn parse_config(input: &str) -> Result<Config, String> {
    Err("something went wrong".to_string())
}

// 正确做法
fn parse_config(input: &str) -> Result<Config, ConfigError>

10.4 丢失 backtrace/source chain

// 反模式：用字符串包装底层错误
#[derive(thiserror::Error, Debug)]
pub enum ServiceError {
    #[error("database error: {0}")]
    Database(String), // source 丢失！
}

// 正确做法：保留 source 链
#[derive(thiserror::Error, Debug)]
pub enum ServiceError {
    #[error("database error: {0}")]
    Database(#[from] DatabaseError), // source 保留
}

---

11. 总结：工程决策树

需要返回错误的代码是库代码还是应用代码？
├── 库代码
│   ├── 错误类型需要精确匹配？ → thiserror
│   ├── 跨平台/序列化需要？   → thiserror + serde
│   └── 性能关键路径？        → 手写 Error impl（避免堆分配）
│
└── 应用代码
    ├── 服务端应用？          → anyhow
    ├── CLI/工具？            → eyre / color-eyre
    └── 需要 sentry 集成？    → anyhow + sentry-anyhow

错误需要跨 FFI 边界？
├── 是 → 转换为 i32/errno + 全局 last_error
└── 否 → 正常 Result 传播

错误响应外部调用者？
├── HTTP API → 实现 IntoResponse，code + message 分离
├── gRPC → tonic::Status 包装
└── 内部 RPC → 保留完整 error chain 反序列化

---

附录：推荐依赖配置

# Cargo.toml
[dependencies]
# 库代码
thiserror = "1.0"

# 应用代码
anyhow = "1.0"

# 可观测性
tracing = "0.1"
tracing-subscriber = "0.3"

# 错误报告（可选）
sentry = "0.34"
sentry-anyhow = "0.34"

[dev-dependencies]
# 测试工具
assert_matches = "1.5"
pretty_assertions = "1.4"
proptest = "1.4"

---

关键洞察：Rust 的错误处理不是"异常"也不是"错误码"——它是一种显式的、类型安全的控制流机制。thiserror 让这种机制在生产代码中变得廉价且可组合。掌握错误处理生态的分层设计，是从 Rust 新手进阶到工程实践者的关键一步。