Rust 错误处理：thiserror 与 anyhow

目录

1. 概述
2. Rust 标准库错误处理
3. thiserror 详解
4. anyhow 详解
5. 对比分析
6. 最佳实践
7. 实际应用场景

概述

Rust 的错误处理机制基于 Result<T, E> 类型，但在实际开发中，标准库的错误处理往往不够灵活和便捷。thiserror 和 anyhow 是两个流行的第三方库，它们解决了标准库错误处理的不同痛点。

核心问题

• std: 样板代码多，错误类型定义繁琐
• thiserror: 简化自定义错误类型的定义
• anyhow: 简化错误传播和上下文添加

Rust 标准库错误处理

基本用法

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

// 自定义错误类型（标准库方式）
#[derive(Debug)]
enum MyError {
    Io(std::io::Error),
    Parse(std::num::ParseIntError),
    Custom(String),
}

impl fmt::Display for MyError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self {
            MyError::Io(err) => write!(f, "IO error: {}", err),
            MyError::Parse(err) => write!(f, "Parse error: {}", err),
            MyError::Custom(msg) => write!(f, "Custom error: {}", msg),
        }
    }
}

impl Error for MyError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        match self {
            MyError::Io(err) => Some(err),
            MyError::Parse(err) => Some(err),
            MyError::Custom(_) => None,
        }
    }
}

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

impl From<std::num::ParseIntError> for MyError {
    fn from(err: std::num::ParseIntError) -> Self {
        MyError::Parse(err)
    }
}

fn read_number_from_file(path: &str) -> Result<i32, MyError> {
    let content = std::fs::read_to_string(path)?;
    let number = content.trim().parse::<i32>()?;
    Ok(number)
}

标准库的问题

1. 样板代码过多: 需要手动实现 Display、Error、From 等 trait
2. 错误链处理复杂: 手动处理错误的 source 链
3. 上下文信息缺失: 难以添加额外的上下文信息
4. 类型安全与灵活性矛盾: 严格的类型系统与灵活的错误处理之间的平衡

thiserror 详解

thiserror 是一个过程宏库，专门用于简化自定义错误类型的定义。

基本用法

use thiserror::Error;

#[derive(Error, Debug)]
enum MyError {
    #[error("IO error")]
    Io(#[from] std::io::Error),

    #[error("Parse error")]
    Parse(#[from] std::num::ParseIntError),

    #[error("Custom error: {message}")]
    Custom { message: String },

    #[error("Invalid input: expected {expected}, got {actual}")]
    InvalidInput { expected: String, actual: String },
}

fn read_number_from_file(path: &str) -> Result<i32, MyError> {
    let content = std::fs::read_to_string(path)?;
    let number = content.trim().parse::<i32>()?;

    if number < 0 {
        return Err(MyError::InvalidInput {
            expected: "positive number".to_string(),
            actual: number.to_string(),
        });
    }

    Ok(number)
}

高级特性

1. 透明错误传播

#[derive(Error, Debug)]
enum AppError {
    #[error("Database error")]
    Database(#[from] sqlx::Error),

    #[error("Network error")]
    Network(#[from] reqwest::Error),

    // transparent: 直接传播底层错误
    #[error(transparent)]
    Other(#[from] anyhow::Error),
}

2. 嵌套错误处理

#[derive(Error, Debug)]
enum OuterError {
    #[error("Inner error occurred")]
    Inner(#[from] InnerError),
}

#[derive(Error, Debug)]
enum InnerError {
    #[error("Something went wrong: {reason}")]
    Failed { reason: String },
}

3. 带源错误的自定义消息

#[derive(Error, Debug)]
enum ConfigError {
    #[error("Failed to read config file")]
    ReadError(#[source] std::io::Error),

    #[error("Invalid configuration format")]
    ParseError(#[source] toml::de::Error),
}

thiserror 解决的问题

1. 消除样板代码: 自动生成 Display、Error 实现
2. 简化 From 转换: #[from] 属性自动生成转换
3. 格式化支持: 内置字符串插值支持
4. 源错误链: 自动处理错误链关系

anyhow 详解

anyhow 提供了灵活的错误处理机制，特别适合应用层代码。

基本用法

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

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

    let config: Config = toml::from_str(&content)
        .with_context(|| "Failed to parse config file")?;

    if config.port == 0 {
        bail!("Port cannot be zero");
    }

    Ok(config)
}

fn process_data(data: &[u8]) -> Result<String> {
    if data.is_empty() {
        return Err(anyhow!("Data cannot be empty"));
    }

    let text = std::str::from_utf8(data)
        .context("Invalid UTF-8 data")?;

    Ok(text.to_uppercase())
}

高级特性

1. 错误上下文链

use anyhow::{Context, Result};

fn deep_function() -> Result<()> {
    std::fs::read_to_string("nonexistent.txt")
        .context("Reading input file")
        .context("Initializing application")
        .context("Starting server")?;
    Ok(())
}

// 错误输出：
// Starting server
//
// Caused by:
//     0: Initializing application
//     1: Reading input file
//     2: No such file or directory (os error 2)

2. 自定义错误创建

use anyhow::{anyhow, bail, ensure, Result};

fn validate_input(value: i32) -> Result<()> {
    ensure!(value > 0, "Value must be positive, got: {}", value);
    Ok(())
}

fn process_request(request: &str) -> Result<String> {
    if request.is_empty() {
        bail!("Request cannot be empty");
    }

    if request.len() > 1000 {
        return Err(anyhow!("Request too long: {} characters", request.len()));
    }

    Ok(request.to_uppercase())
}

3. 错误降级和类型转换

use anyhow::Result;

fn handle_specific_error() -> Result<()> {
    let result = some_operation().map_err(|e| {
        if let Some(io_err) = e.downcast_ref::<std::io::Error>() {
            if io_err.kind() == std::io::ErrorKind::NotFound {
                return anyhow!("Required file not found");
            }
        }
        e
    })?;

    Ok(())
}

anyhow 解决的问题

1. 简化错误传播: Result<T> 等价于 Result<T, anyhow::Error>
2. 丰富的上下文: context() 方法添加错误上下文
3. 类型擦除: 统一的错误类型，便于传播
4. 便捷的错误创建: anyhow!、bail!、ensure! 宏

对比分析

功能对比表

特性	std	thiserror	anyhow
样板代码	多	少	最少
类型安全	强	强	弱（类型擦除）
错误上下文	手动	支持	优秀
性能开销	低	低	中等
学习曲线	陡峭	温和	平缓
适用场景	库代码	库代码	应用代码

代码对比

同一功能的三种实现

// 1. 标准库方式
#[derive(Debug)]
enum StdError {
    Io(std::io::Error),
    Parse(std::num::ParseIntError),
}

impl std::fmt::Display for StdError {
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        match self {
            StdError::Io(e) => write!(f, "IO error: {}", e),
            StdError::Parse(e) => write!(f, "Parse error: {}", e),
        }
    }
}

impl std::error::Error for StdError {}

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

impl From<std::num::ParseIntError> for StdError {
    fn from(e: std::num::ParseIntError) -> Self {
        StdError::Parse(e)
    }
}

// 2. thiserror 方式
#[derive(thiserror::Error, Debug)]
enum ThisError {
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),

    #[error("Parse error: {0}")]
    Parse(#[from] std::num::ParseIntError),
}

// 3. anyhow 方式
use anyhow::Result;

fn anyhow_function() -> Result<i32> {
    let content = std::fs::read_to_string("file.txt")
        .context("Reading file")?;
    let number = content.parse::<i32>()
        .context("Parsing number")?;
    Ok(number)
}

最佳实践

选择原则

1. 库代码: 优先使用 thiserror
   • 需要精确的错误类型
   • 为用户提供清晰的 API
   • 性能敏感场景
2. 应用代码: 优先使用 anyhow
   • 快速原型开发
   • 复杂的错误传播链
   • 需要丰富的上下文信息
3. 混合使用:
   • 库层使用 thiserror 定义精确错误类型
   • 应用层使用 anyhow 处理和传播错误

代码组织模式

// errors.rs - 使用 thiserror 定义库错误
#[derive(thiserror::Error, Debug)]
pub enum DatabaseError {
    #[error("Connection failed: {source}")]
    Connection { source: std::io::Error },

    #[error("Query failed: {query}")]
    Query { query: String },

    #[error("Transaction failed")]
    Transaction,
}

// lib.rs - 库接口
pub type Result<T> = std::result::Result<T, DatabaseError>;

pub fn connect() -> Result<Connection> {
    // 库实现
}

// main.rs - 应用代码使用 anyhow
use anyhow::{Context, Result};

fn main() -> Result<()> {
    let conn = mylib::connect()
        .context("Failed to connect to database")?;

    // 应用逻辑
    Ok(())
}

错误处理策略

1. 分层错误处理

// 底层：具体错误类型
#[derive(thiserror::Error, Debug)]
enum DatabaseError {
    #[error("Connection timeout")]
    Timeout,
    #[error("Invalid query: {query}")]
    InvalidQuery { query: String },
}

// 中层：领域错误类型
#[derive(thiserror::Error, Debug)]
enum ServiceError {
    #[error("Database error")]
    Database(#[from] DatabaseError),
    #[error("Validation error: {message}")]
    Validation { message: String },
}

// 上层：应用错误处理
fn handle_request() -> anyhow::Result<Response> {
    let data = service::get_data()
        .context("Failed to retrieve data")?;
    Ok(Response::new(data))
}

2. 错误恢复模式

use anyhow::{Context, Result};

fn resilient_operation() -> Result<String> {
    // 尝试主要方法
    match primary_method() {
        Ok(result) => return Ok(result),
        Err(e) => {
            tracing::warn!("Primary method failed: {}", e);
        }
    }

    // 回退到备用方法
    fallback_method()
        .context("Both primary and fallback methods failed")
}

实际应用场景

场景 1: Web API 服务

// 使用 thiserror 定义 API 错误
#[derive(thiserror::Error, Debug)]
pub enum ApiError {
    #[error("Invalid request: {message}")]
    BadRequest { message: String },

    #[error("Resource not found")]
    NotFound,

    #[error("Internal server error")]
    Internal(#[from] anyhow::Error),
}

impl warp::reject::Reject for ApiError {}

// 应用代码使用 anyhow
async fn handle_user_request(id: u64) -> Result<User, ApiError> {
    let user = database::get_user(id)
        .await
        .context("Failed to query user database")?
        .ok_or(ApiError::NotFound)?;

    Ok(user)
}

场景 2: CLI 工具

use anyhow::{Context, Result, bail};
use clap::Parser;

#[derive(Parser)]
struct Args {
    #[arg(short, long)]
    input: String,
    #[arg(short, long)]
    output: String,
}

fn main() -> Result<()> {
    let args = Args::parse();

    let input_data = std::fs::read(&args.input)
        .with_context(|| format!("Failed to read input file: {}", args.input))?;

    if input_data.is_empty() {
        bail!("Input file is empty");
    }

    let processed = process_data(&input_data)
        .context("Failed to process data")?;

    std::fs::write(&args.output, processed)
        .with_context(|| format!("Failed to write output file: {}", args.output))?;

    println!("Processing complete!");
    Ok(())
}

场景 3: 异步任务处理

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

async fn process_batch(items: Vec<Item>) -> Result<Vec<ProcessedItem>> {
    let tasks: Vec<_> = items
        .into_iter()
        .enumerate()
        .map(|(i, item)| {
            task::spawn(async move {
                process_item(item)
                    .await
                    .with_context(|| format!("Failed to process item {}", i))
            })
        })
        .collect();

    let mut results = Vec::new();
    for (i, task) in tasks.into_iter().enumerate() {
        let result = task
            .await
            .with_context(|| format!("Task {} panicked", i))??;
        results.push(result);
    }

    Ok(results)
}

性能考虑

错误创建开销

use criterion::{black_box, criterion_group, criterion_main, Criterion};

// std::Error 开销最小
fn std_error_creation() -> Result<(), Box<dyn std::error::Error>> {
    Err("error message".into())
}

// thiserror 开销较小
#[derive(thiserror::Error, Debug)]
#[error("Custom error: {message}")]
struct CustomError {
    message: String,
}

fn thiserror_creation() -> Result<(), CustomError> {
    Err(CustomError {
        message: "error message".to_string(),
    })
}

// anyhow 开销中等（因为类型擦除）
fn anyhow_creation() -> anyhow::Result<()> {
    anyhow::bail!("error message")
}

内存使用

• std: 最小内存占用
• thiserror: 类似 std，但可能因字符串插值增加开销
• anyhow: 稍高内存使用（因为动态分发和上下文存储）

总结

何时使用什么

场景	推荐方案	理由
公共库 API	thiserror	类型安全，清晰的错误契约
内部应用逻辑	anyhow	灵活性，丰富的上下文
性能关键路径	std	最小开销
快速原型	anyhow	开发效率高
错误恢复逻辑	anyhow	便于错误分类和处理

关键收益

1. thiserror:
   • 减少 80% 的错误处理样板代码
   • 保持类型安全和性能
   • 提供清晰的 API 契约
2. anyhow:
   • 简化错误传播链
   • 丰富的调试信息
   • 提高开发效率
3. 组合使用:
   • 库层精确，应用层灵活
   • 最佳的开发体验
   • 维护良好的错误边界

通过合理选择和使用这些工具，可以显著提升 Rust 项目的错误处理质量和开发效率。