掌握 anyhow，让你的 Rust 错误处理优雅又安全

一、引言

这是Rust九九八十一难第八篇。敲Rust代码的时候，错误处理是绕不过去的，伴随整个开发周期。Rust自带的很强大，但是也有问题，因此介绍下应用层错误库：anyhow。那自带的有哪些问题呢？

问题一：错误类型泛型爆炸

应用存在多个error来源是，E要同时兼容所有的错误, 举个例子：

fn read_config() -> Result<String, std::io::Error>;
fn parse_config(s: String) -> Result<Config, ParseError>;

调用时需要定义一个枚举 AppError { Io(std::io::Error), Parse(ParseError) }，还要手动实现From，初期成本有点高。

问题二：缺乏错误上下文与 backtrace

Error标准库定义很简约：

pub trait Error: Debug + Display {
    fn source(&self) -> Option<&(dyn Error + 'static)> { None }
}

• 如果通过Result<(), Box<dyn std::error::Error + Send + Sync>> 统一错误，则会失去静态类型信息
• 有内建 backtrace 和上下文字符串（如"连接数据库失败: url=xxx"），做过Java的知道，项目大，且没trace，问题排查起来如同地狱探宝。

二、anyhow核心定义与边界

官方介绍anyhow是面向应用层错误处理，使开发者专注于业务，而不是维护错误枚举。

1、核心类型定义

pub struct Error {
    inner: Box<dyn std::error::Error + Send + Sync + 'static>
}

该设计保证：

• Send + Sync：可在线程间传递，适用于 tokio 等异步运行时
• 'static：满足 Future 的生命周期要求
• Box 动态分发：允许包装任意错误类型，实现统一处理

2、对比与其他库关系，确定边界

库	面向场景	是否需定义错误枚举	是否支持上下文	backtrace	异步兼容性
thiserror	底层库	✅ 需要显式定义	❌（需结合 anyhow）	❌	✅
snafu	嵌入式/严格类型	✅ 强类型枚举	✅ 通过宏生成	✅	✅
eyre	应用层+库	❌ 动态错误	✅ 自动上下文	✅	✅
anyhow	应用层	❌ 动态错误	✅ 自动上下文	✅	✅

结论：

• anyhow + thiserror：不少文章有介绍，算是最佳组合，thiserror 用于定义库错误，anyhow 用于应用聚合
• 对比 snafu：snafu 强调编译期类型安全，适合底层库；anyhow 强调开发效率，适合业务代码
• 对比 eyre ：eyre 为无 Send 版本，在 async + tokio 中使用有限，anyhow在社区使用广泛，所以这次先介绍anyhow应用层使用。

三、anyhow核心API使用

1、基础使用

use anyhow::Result;
use std::fs::File;
use std::io::Read;

fn read_file(path: &str) -> Result<String> {
    let mut s = String::new();
    File::open(path)?.read_to_string(&mut s)?;
    Ok(s)
}

fn main() -> Result<()> {
    let content = read_file("foo.txt")?;
    println!("文件内容: {}", content);
    Ok(())
}

? 自动将 std::io::Error 转换为 anyhow::Error，这样简化了错误类型管理。

2、错误创建方式

a、使用 anyhow! 创建错误

use anyhow::anyhow;

fn fail() -> anyhow::Result<()> {
    Err(anyhow!("Something went wrong: {}", 42))
}

支持类型的格式化输出，比 std::io::Error::new 更简洁

b、使用 bail! 直接返回错误

use anyhow::{Result, bail};

fn check(value: i32) -> Result<()> {
    if value < 0 {
        bail!("value must be non-negative");
    }
    Ok(())
}

bail!相当于 return Err(anyhow!(...)),展开长这样：

 return ::anyhow::__private::Err({
            let error = ::anyhow::__private::format_err(::anyhow::__private::format_args!("value must be non-negative"));
            error
        });

可以理解为自动封装 anyhow::Error

c、使用 ensure! 进行条件校验

github Readme没有介绍，Rust官网有：docs.rs/anyhow/late...

use anyhow::{ensure, Result};

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

可以替代 if !condition { return Err(...) }，可读性更好。

3、上下文增强机制

a、context() 和 with_context()

use anyhow::{Context, Result};
use std::fs::File;

fn read_file(path: &str) -> Result<String> {
    let mut s = String::new();
    File::open(path)
        .with_context(|| format!("failed to open file: {}", path))?
        .read_to_string(&mut s)
        .context("failed to read file content")?;
    Ok(s)
}

调用时每层都插入错误链，最终打印堆栈时显示详细信息。context() 通过 trait Context 提供的 ResultExt 方法实现，内部调用 map_err 将错误包装为带有上下文的 anyhow::Error。与 Java 异常堆栈相比，Rust 的 context 更可控，显示的内容仅限于明确调用 context 的位置

b、链式 Context综合示例

use anyhow::{Context, Result};

fn read_config() -> Result<String> {
    std::fs::read_to_string("config.toml")
        .context("failed to read configuration file")
}

fn parse_config() -> Result<()> {
    let content = read_config().context("config load stage failed")?;
    println!("content: {content}");
    Ok(())
}

fn main() {
    if let Err(e) = parse_config() {
        eprintln!("Error: {e:?}");
        for cause in e.chain() {
            eprintln!("  caused by: {cause}");
        }
    }
}

输出结果：

Error: failed to read configuration file
  caused by: config load stage failed
  caused by: No such file or directory

4、 捕获并包装panic

为了防止程序崩溃和统一打印错误链条，需要捕获panic。包装panic为anyhow error。示例代码如下

fn run_safely() -> Result<(), Error> {
    let result = panic::catch_unwind(|| {
        panic!("Something went wrong");
    });

    match result {
        Ok(_) => Ok(()),
        Err(payload) => {
            let msg = if let Some(s) = payload.downcast_ref::<&str>() {
                s.to_string()
            } else if let Some(s) = payload.downcast_ref::<String>() {
                s.clone()
            } else {
                "Unknown panic".to_string()
            };
            Err(Error::msg(msg))
        }
    }
}

fn main() -> Result<(), Error> {
    run_safely()?;
    Ok(())
}

四、anyhow与 async/await 协作

1、async/await 下的错误传递

• async 函数返回 anyhow::Result<T> 时，? 运算符仍然可用
• anyhow::Error 是 Send + Sync + 'static，保证跨线程安全
• 举例如下：

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

async fn fetch_data(url: &str) -> Result<String> {
    let resp = reqwest::get(url)
        .await
        .with_context(|| format!("failed to GET from {}", url))?;
    let body = resp.text().await.context("failed to read response body")?;
    Ok(body)
}

2、tokio::spawn 与 JoinError

use anyhow::Error;
use tokio;

#[tokio::main]
async fn main() {
    let handle = tokio::spawn(async {
        panic!("task failed");
    });

    let result = handle.await.map_err(|e| Error::new(e));
    if let Err(err) = result {
        eprintln!("Caught error: {:?}", err);
    }
}

JoinError 可被转换为 anyhow::Error，保持统一错误处理

3、 async函数捕获backtrace

• anyhow::Error 内部封装了一个 std::backtrace::Backtrace。

• 在创建 Error 的时候（anyhow!(...) 或 .context() 调用时）就自动捕获堆栈。

• 异步函数中的 .await 不会破坏 backtrace 链，因为 backtrace 是在错误创建时固定下来的。

示例代码如下：

use anyhow::{anyhow, Result};

async fn do_something() -> Result<()> {
    // 模拟错误发生
    let err = anyhow!("async task failed");
    // 打印捕获的 backtrace
    if let Some(bt) = err.backtrace() {
        println!("Captured backtrace:\n{bt}");
    }
    Err(err)
}

#[tokio::main]
async fn main() -> Result<()> {
    // 启动异步任务
    let _ = do_something().await;
    Ok(())
}

运行结果:

Captured backtrace:
   0: anyhow::Error::backtrace
   1: my_crate::do_something
   2: my_crate::main
   ...

注意：设置了环境变量RUST_BACKTRACE=1 cargo run ,backtrace 才会在 Display 中自动展开。

4、async函数捕获panic兜底

• Rust 的异步 panic 不会传播到其他任务，只会导致该 JoinHandle 报错。

• JoinError 提供 .is_panic() 和 .into_panic() 方法。

• 可以将 panic 封装为 anyhow::Error 保持统一错误模型，保证服务不中断。

• 异步场景示例如下：

use anyhow::{Error, Result};
use tokio::task;
use std::panic;

#[tokio::main]
async fn main() -> Result<()> {
    let handle = task::spawn(async {
        panic!("something went terribly wrong");
    });

    match handle.await {
        Ok(_) => println!("Task finished normally"),
        Err(join_err) => {
            // tokio::JoinError::into_panic 提取 panic 内容
            if join_err.is_panic() {
                // 将 panic 转换为 anyhow::Error
                let err: Error = Error::msg(format!("panic caught: {:?}", join_err));
                println!("Recovered from async panic: {err}");
            }
        }
    }

    Ok(())
}

运行结果：

Recovered from async panic: panic caught: JoinError::Panic

重复一句：同步用 std::panic::catch_unwind（与 async 原理一致）

五、两个组合案例

回到引言那部分，在举两个例子，anyhow+thiserror，anyhow+tracing_error

1、anyhow+thiserror

配合错误枚举，应用层再转换为 anyhow::Result<T>

示例：

use anyhow::Result;
use thiserror::Error;

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

fn lib_function() -> std::result::Result<String, MyLibError> {
    let content = std::fs::read_to_string("file.json")?;
    let _val: serde_json::Value = serde_json::from_str(&content)?;
    Ok(content)
}

fn app_function() -> Result<String> {
    let res = lib_function()?; // 自动转换为 anyhow::Error
    Ok(res)
}

补充下：这是anyhow的设计核心之一，任何实现了 Error + Send + Sync + 'static 的类型，都可以自动转为 anyhow::Error。

• ? 的语法糖等价于：

  match expr {
      Ok(v) => v,
      Err(e) => return Err(From::from(e)),
  }

  当 lib_function() 返回 Err(MyLibError) （return Err(From::from(e))）时,调用的是：

  impl From<MyLibError> for anyhow::Error

  这个 From 实现就是上面那段，动完成类型提升，无需手动 map_err()。

2、anyhow+tracing_error

结合 tracing-error crate，tracing-error 提供 InstrumentedErrorLayer，能自动把 anyhow::Error 的链合并为一条漂亮的日志。

use anyhow::{Context, Result};
use futures::future::join_all;
use reqwest;
use tracing::{error, info, instrument};
use tracing_error::ErrorLayer;
use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};

#[tokio::main]
async fn main() -> Result<()> {
    // 初始化 tracing subscriber
    tracing_subscriber::registry()
        .with(tracing_subscriber::fmt::layer()) // 格式化输出
        .with(ErrorLayer::default()) // 捕获 tracing span 上下文
        .init();

    info!("Starting fetch tasks...");

    let urls = vec![
        "https://httpbin.org/get",
        "https://invalid.example",
        "https://httpbin.org/status/404",
    ];

    if let Err(e) = fetch_urls(urls).await {
        error!(error = ?e, "Top-level error occurred");
    }

    Ok(())
}

#[instrument] // 自动为函数创建 tracing span
async fn fetch_urls(urls: Vec<&str>) -> Result<Vec<String>> {
    let futures = urls.into_iter().map(|url| async move {
        fetch_one(url).await
            .with_context(|| format!("fetch failed for URL: {}", url))
    });

    let results = join_all(futures).await;

    // 遍历每个请求结果
    for result in &results {
        if let Err(err) = result {
            // 使用 tracing-error 捕获 span trace
            let span_trace = tracing_error::SpanTrace::capture();
            error!(
                error = ?err,
                trace = ?span_trace,
                "Request failed with context chain"
            );
        }
    }

    // 收集成功结果
    let ok_results = results
        .into_iter()
        .filter_map(Result::ok)
        .collect::<Vec<_>>();

    Ok(ok_results)
}

#[instrument]
async fn fetch_one(url: &str) -> Result<String> {
    let response = reqwest::get(url)
        .await
        .context("HTTP request failed")?;

    let status = response.status();

    if !status.is_success() {
        anyhow::bail!("Received non-success status: {}", status);
    }

    let text = response
        .text()
        .await
        .context("Failed to read response body")?;

    Ok(text)
}

输出：

2025-10-25T15:14:13.343867Z ERROR fetch_urls{urls=["https://httpbin.org/get", "https://invalid.example", "https://httpbin.org/status/404"]}: anyhow_tracing_demo: Request failed with context chain error=fetch failed for URL: https://invalid.example

Caused by:
    0: HTTP request failed
    1: error sending request for url (https://invalid.example/)
    2: client error (Connect)
    3: dns error
    4: failed to lookup address information: nodename nor servname provided, or not known

六、小结

本文解析了 Rust 中 anyhow 错误处理库的使用，从入门到高级使用技巧，并探讨了它的设计哲学。总的来说anyhow是是大型项目 Rust 错误处理的利器；也有缺点，需要配合其他组件使用，甚至自己封装（比如没有行号、文件名），这样才能发挥最大作用。

如果喜欢，请点个关注吧，本人公众号大鱼七成饱。