Rust 异步编程：错误处理的艺术与实践

常见错误类型

1. IO 错误：网络断开、文件缺失等，通常由 std::io::Error 表示。
2. 超时错误：操作未在规定时间内完成，Tokio 的 timeout 会返回 Elapsed。
3. 取消错误：任务被主动终止，JoinHandle::abort 会产生 JoinError。
4. 业务逻辑错误：如余额不足、用户不存在，需自定义枚举类型。
5. 系统错误：权限不足或内存溢出，底层通常映射为 IO 错误。

异步上下文中的标准 Result 处理

? 操作符的应用

在异步函数中，? 操作符行为与同步一致，遇到 Err 直接返回。但需注意错误类型的转换。

use tokio::fs::File;
use tokio::io::AsyncReadExt;
use std::error::Error;

async fn read_file_and_parse() -> Result<Vec<u32>, Box<dyn Error>> {
    let mut file = File::open("numbers.txt").await?;
    let mut content = String::new();
    file.read_to_string(&mut content).await?;
    let numbers: Vec<u32> = content
        .lines()
        .map(|line| line.parse::<u32>())
        .collect::<Result<_, _>>()?;
    Ok(numbers)
}

unwrap/expect 的风险

在异步任务中使用 unwrap() 极其危险，一旦失败会导致整个任务崩溃且难以恢复。务必使用 match 或 ?。

// 危险示例
async fn read_file_dangerous() {
    let mut file = File::open("nonexistent.txt").await.unwrap(); // 任务崩溃
    let mut content = String::new();
    file.read_to_string(&mut content).await.unwrap();
}

// 安全示例
async fn read_file_safe() -> Result<(), Box<dyn std::error::Error>> {
    let mut file = File::open("nonexistent.txt").await?;
    let mut content = String::new();
    file.read_to_string(&mut content).await?;
    Ok(())
}

Box 的使用

当需要统一不同来源的错误时，Box<dyn Error> 是常用方案，它能容纳任何实现了 Error trait 的类型。

自定义异步错误类型的设计

thiserror 与 anyhow 的选择

• thiserror：适合库开发，编译期生成代码，零开销。
• anyhow：适合应用开发，提供丰富的错误链信息，运行时开销略高。

使用 thiserror 定义错误

利用宏可以快速实现 Error trait，并支持自动转换（#[from]）。

use thiserror::Error;
use tokio::time::error::Elapsed;

#[derive(Error, Debug)]
pub enum AppError {
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),
    #[error("Timeout error: {0}")]
    Timeout(#[from] Elapsed),
    #[error("Business error: {0}")]
    Business(#[from] BusinessError),
}

#[derive(Error, Debug)]
pub enum BusinessError {
    #[error("User not found")]
    UserNotFound,
    #[error("Insufficient balance")]
    InsufficientBalance,
}

实战：库与应用的分层处理

在库内部使用 thiserror 暴露明确的错误类型，在应用层使用 anyhow 进行聚合和展示。

// lib.rs
use thiserror::Error;

#[derive(Error, Debug)]
pub enum MyLibError {
    #[error("Network error: {0}")]
    Network(#[from] reqwest::Error),
}

pub async fn fetch_data() -> Result<String, MyLibError> {
    // ...
}

// main.rs
use my_lib::fetch_data;
use anyhow::Result;

async fn process() -> Result<()> {
    let data = fetch_data().await?;
    Ok(())
}

超时与取消错误的处理

超时控制

使用 tokio::time::timeout 包裹长时间运行的操作，捕获 Elapsed 错误。

use tokio::time::{timeout, Duration};

async fn run_with_timeout() -> Result<(), AppError> {
    let result = timeout(Duration::from_secs(3), long_running_op()).await;
    match result {
        Ok(_) => Ok(()),
        Err(_) => Err(AppError::Timeout),
    }
}

任务取消

通过 JoinHandle::abort 取消任务，并在 await 时检查 is_cancelled()。

use tokio::task::JoinError;

let handle = tokio::spawn(task());
handle.abort();
let result = handle.await;
if let Err(e) = result {
    if e.is_cancelled() {
        // 处理取消逻辑
    }
}

组合策略

结合 oneshot 通道与 select! 宏，可实现优雅的内部取消信号传递。

并发任务的错误聚合

join! 与 try_join!

• join! 等待所有任务完成，不中断。
• try_join! 任一任务失败立即返回错误。

use tokio::join;
use tokio::try_join;

let (res1, res2) = join!(task1(), task2());
let result = try_join!(task1(), task2());

批量任务处理

使用 futures::future::try_join_all 处理动态数量的任务列表。

use futures::future::try_join_all;

let tasks = (0..5).map(|i| task(i));
let results = try_join_all(tasks).await?;

异步错误的传递与传播

错误链构建

利用 #[source] 属性保留原始错误堆栈，便于排查。

use thiserror::Error;

#[derive(Error, Debug)]
pub enum AppError {
    #[error("Failed to fetch: {0}")]
    Fetch(#[source] reqwest::Error),
}

跨任务传递

通过 tokio::sync::oneshot 将子任务的错误结果回传给父任务。

实战项目：异步 API 错误体系

以 Axum + SQLx 为例，构建统一的错误响应中间件。

依赖配置

[dependencies]
axum = "0.7"
tokio = { version = "1", features = ["full"] }
sqlx = { version = "0.7", features = ["runtime-tokio-rustls"] }
thiserror = "1.0"
tracing = "0.1"

错误类型定义

use axum::{http::StatusCode, response::IntoResponse};
use thiserror::Error;

#[derive(Error, Debug)]
pub enum AppError {
    #[error("Database error: {0}")]
    Database(#[from] sqlx::Error),
    #[error("Validation failed: {0}")]
    Validation(String),
    #[error("User not found")]
    NotFound,
}

impl IntoResponse for AppError {
    fn into_response(self) -> axum::response::Response {
        let status = match self {
            AppError::Database(_) => StatusCode::INTERNAL_SERVER_ERROR,
            AppError::Validation(_) => StatusCode::BAD_REQUEST,
            AppError::NotFound => StatusCode::NOT_FOUND,
        };
        (status, format!("{{\"error\": \"{}\"}}", self)).into_response()
    }
}

路由与中间件

在 Axum 中注册错误处理中间件，确保所有异常都被捕获并格式化。

调试与排查技巧

使用 tracing 记录

启用 tracing 库记录错误上下文，包括调用栈和变量状态。

use tracing::error;

if let Err(e) = fetch_data().await {
    error!("Fetch failed: {:?}", e);
}

tokio-console 定位

对于复杂的异步死锁或泄漏，可使用 tokio-console 观察任务调度情况。

最佳实践总结

1. 避免 panic：异步任务中尽量不抛 panic，转为 Result。
2. 统一错误类型：库端用 thiserror，应用端用 anyhow。
3. 错误链完整：保留原始错误以便溯源。
4. 资源清理：确保任务取消后释放资源，防止泄漏。

掌握这些模式，能显著提升 Rust 异步系统的健壮性与可维护性。