Rust 异步编程错误处理：从原理到实战

异步错误的常见分类

1. IO 错误：网络断开、文件不存在等，通常对应 std::io::Error。
2. 超时错误：操作未在规定时间内完成，Tokio 的 timeout 会返回 Elapsed。
3. 取消错误：任务被主动终止（如 abort），返回 JoinError。
4. 业务逻辑错误：自定义的错误类型，如用户不存在、余额不足。
5. 系统错误：权限不足、内存溢出等底层问题。

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

? 操作符的妙用

在异步函数中，? 操作符的行为与同步一致。遇到 Err 时，它会立即返回该错误，并自动进行类型转换。这比手动 match 要简洁得多。

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() 或 expect() 是危险的。一旦触发 panic，整个任务都会崩溃，且可能无法优雅地清理资源。生产环境应始终使用 match 或 ?。

Box 的统一处理

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

use tokio::time::{timeout, Duration};
use std::error::Error;

async fn async_operation() -> Result<(), Box<dyn Error>> {
    let result = timeout(Duration::from_secs(2), tokio::time::sleep(Duration::from_secs(3))).await?;
    Ok(result)
}

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

thiserror vs anyhow

• thiserror：专为定义库级错误设计，编译期生成实现，零开销。
• anyhow：适合应用层快速开发，支持错误链，容错性强。

使用 thiserror 构建类型安全错误

利用宏可以大幅减少样板代码：

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 简化调用。这样既保证了库的稳定性，又提升了应用的开发效率。

超时与取消错误的处理

超时控制

Tokio 的 timeout 包装器非常实用。它会将超时异常转换为 Elapsed 错误，我们可以将其映射为自定义的业务错误。

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

#[derive(Error, Debug)]
pub enum AppError {
    #[error("Operation timed out")]
    Timeout,
    #[error("Other error: {0}")]
    Other(#[from] anyhow::Error),
}

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

任务取消机制

使用 JoinHandle::abort 可以强制终止子任务。注意捕获 JoinError 并判断是否因取消导致，避免误判其他错误。

并发任务的错误聚合

join! 与 try_join!

• join! 等待所有任务完成，不关心单个任务是否失败。
• try_join! 只要有一个任务失败，立即返回错误，适合需要原子性的场景。

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

// 使用 try_join! 确保要么全成功，要么全失败
let result = try_join!(task1(), task2()).await;

动态任务列表

对于数量不确定的任务，可以使用 futures::future::try_join_all 来聚合。

异步错误的传递与传播

错误链构建

利用 thiserror 的 #[source] 属性，可以保留原始错误信息，方便排查深层原因。

跨任务通信

通过 tokio::sync::oneshot 通道，可以在父子任务间传递错误状态，确保父任务能感知子任务的失败。

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

我们构建一个基于 Axum 和 SQLx 的用户管理 API，重点展示如何统一错误响应。

架构设计

• HTTP 框架：Axum
• 数据库：SQLx (PostgreSQL)
• 错误管理：thiserror + IntoResponse
• 日志：tracing

核心代码结构

错误定义 (src/errors.rs)

use thiserror::Error;
use axum::{http::StatusCode, response::IntoResponse, Json};
use serde::{Serialize, Deserialize};

#[derive(Error, Debug)]
pub enum AppError {
    #[error("Database error: {0}")]
    Database(#[from] sqlx::Error),
    #[error("Request validation error: {0}")]
    Validation(String),
    #[error("User not found")]
    UserNotFound,
    #[error("Internal server error")]
    InternalServerError,
}

#[derive(Debug, Serialize, Deserialize)]
pub struct ErrorResponse {
    pub error: String,
    pub code: u16,
    pub message: String,
}

impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        let (status, code, message) = match self {
            AppError::Database(e) => {
                tracing::error!("DB error: {:?}", e);
                (StatusCode::INTERNAL_SERVER_ERROR, 500, "Internal server error")
            }
            AppError::Validation(msg) => (StatusCode::BAD_REQUEST, 400, msg.as_str()),
            AppError::UserNotFound => (StatusCode::NOT_FOUND, 404, "User not found"),
            AppError::InternalServerError => (StatusCode::INTERNAL_SERVER_ERROR, 500, "Server error"),
        };
        let body = ErrorResponse {
            error: self.to_string(),
            code,
            message: message.to_string(),
        };
        (status, Json(body)).into_response()
    }
}

路由与服务层 (src/routes.rs & src/service.rs)

服务层负责业务逻辑验证，路由层负责将结果转换为 HTTP 响应。通过 ? 操作符，错误会自动传递给 IntoResponse 实现。

async fn create_user_handler(
    State(pool): State<PgPool>,
    Json(req): Json<CreateUserRequest>,
) -> Result<Json<User>, AppError> {
    let user = create_user_service(&pool, req).await?;
    Ok(Json(user))
}

调试与监控

在生产环境中，结合 tracing 记录错误堆栈，并使用 tokio-console 观察任务调度情况，能快速定位异步泄漏或死锁问题。

总结

异步错误处理不仅仅是语法糖，更是系统设计的一部分。理解 Result 在异步上下文中的行为，合理选择 thiserror 或 anyhow，以及正确处理超时和取消，是编写健壮 Rust 应用的关键。在实际项目中，建议建立统一的错误中间件，将底层细节屏蔽，向上层提供清晰的业务语义。