Rust 错误处理模式：从 Result 到 thiserror/anyhow 的生产级代码组织

Rust 错误处理模式：从 Result 到 thiserror/anyhow 的生产级代码组织

一、Rust 错误处理的"没有异常"哲学：为什么 unwrap 是技术债

Rust 没有异常机制，取而代之的是 Result<T, E> 和 Option<T> 两个枚举类型。初学时最容易犯的错误是到处 .unwrap()——编译通过了，代码能跑了，但生产环境中一个 unwrap 就是一次潜在的 panic。panic 在 Rust 中是不可恢复的崩溃，它会终止当前线程，如果是在主线程则整个进程退出。在服务端程序中，一次 panic 可能导致正在处理的请求丢失、数据库连接泄漏、文件描述符未关闭。

Rust 的错误处理哲学是"让错误可见"：编译器强制你处理每一个可能的错误点，要么用 match 显式处理，要么用 ? 操作符向上传播。这种设计在开发阶段增加了代码量，但在维护阶段大幅减少了"忘了处理错误"导致的线上事故。从 unwrap 到 ? 的转变，是从"代码能跑"到"代码可靠"的关键一步。

二、Rust 错误处理的层次模型与传播机制

flowchart TB
    A[错误发生点<br/>IO/解析/网络/逻辑] --> B{错误类型}

    B -->|可恢复| C[Result&lt;T, E&gt;<br/>显式错误传播]
    B -->|不可恢复| D[panic!<br/>程序崩溃]

    C --> E[错误传播方式]
    E --> F[? 操作符<br/>自动提前返回 Err]
    E --> G[match 显式处理<br/>分支逻辑]
    E --> H[map_err 转换<br/>错误类型映射]

    subgraph 错误类型体系
        I[库 Crate<br/>thiserror 自定义错误类型<br/>实现 Error trait]
        J[应用 Crate<br/>anyhow 统一错误类型<br/>上下文附加]
    end

    I -->|定义| K[具体错误枚举<br/>DatabaseError/ParseError/...]
    J -->|聚合| L[anyhow::Error<br/>统一错误容器]

    K -->|转换| L

    subgraph 生产级错误链
        M[底层错误<br/>io::Error/serde_json::Error]
        N[中间层包装<br/>添加上下文信息]
        O[顶层报告<br/>用户友好的错误消息]
    end

    M --> N --> O

? 操作符的本质：它不是语法糖那么简单。? 做了三件事——检查 Result，如果是 Err 则提前返回，如果是 Ok 则解包值；在返回前，它会调用 From::from 将底层错误类型转换为目标错误类型。这意味着只要实现了 From<SourceError> for TargetError，? 就能自动完成错误类型转换，无需手动 map_err。

三、生产级错误处理的代码实现

库层：thiserror 定义精确错误类型

// 使用 thiserror 为库定义精确的错误类型
// 调用方可以 match 具体变体，做出不同处理
use thiserror::Error;

/// 数据库操作错误类型
/// 每个变体对应一种具体的失败场景
#[derive(Error, Debug)]
pub enum DatabaseError {
    /// 连接失败：网络不可达或认证失败
    #[error("数据库连接失败: {source}")]
    ConnectionFailed {
        #[source]
        source: std::io::Error,
    },

    /// 查询超时：SQL 执行超过时间限制
    #[error("查询超时: {sql} 执行超过 {timeout_ms}ms")]
    QueryTimeout {
        sql: String,
        timeout_ms: u64,
    },

    /// 数据未找到：查询条件无匹配记录
    #[error("数据未找到: {table} 表中无匹配 {key}={value} 的记录")]
    NotFound {
        table: String,
        key: String,
        value: String,
    },

    /// 约束冲突：唯一索引或外键冲突
    #[error("约束冲突: {constraint} - {detail}")]
    ConstraintViolation {
        constraint: String,
        detail: String,
    },

    /// 连接池耗尽：所有连接被占用
    #[error("连接池耗尽: 最大连接数 {max}, 等待超时 {timeout_ms}ms")]
    PoolExhausted {
        max: u32,
        timeout_ms: u64,
    },
}

/// 配置解析错误类型
#[derive(Error, Debug)]
pub enum ConfigError {
    #[error("配置文件不存在: {path}")]
    FileNotFound { path: String },

    #[error("配置格式错误: {detail}")]
    ParseError {
        detail: String,
        #[source]
        source: serde_json::Error,
    },

    #[error("配置值无效: 字段 {field} 的值 {value} 不合法")]
    InvalidValue { field: String, value: String },
}

应用层：anyhow 统一错误处理

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

/// 应用层服务：使用 anyhow 统一错误类型
/// anyhow::Error 是类型擦除的容器，可以持有任何实现了 Error trait 的类型
pub struct UserService {
    db_pool: DatabasePool,
}

impl UserService {
    /// 创建用户：演示 anyhow 的上下文附加模式
    pub async fn create_user(&self, name: &str, email: &str) -> Result<User> {
        // 参数校验：使用 bail! 提前返回错误
        if name.is_empty() {
            bail!("用户名不能为空");
        }
        if !email.contains('@') {
            bail!("邮箱格式不合法: {}", email);
        }

        // 数据库操作：用 .context() 附加业务上下文
        // 当底层 DatabaseError 发生时，错误信息会包含上下文描述
        let user = self.db_pool
            .insert_user(name, email)
            .await
            .context(format!("创建用户失败: name={}, email={}", name, email))?;

        // 后处理：每一步都可能失败，每一步都需要上下文
        self.send_welcome_email(&user)
            .await
            .context("发送欢迎邮件失败")?;

        tracing::info!("用户创建成功: id={}", user.id);
        Ok(user)
    }

    /// 查询用户：演示错误链的完整传播
    pub async fn get_user(&self, id: u64) -> Result<User> {
        self.db_pool
            .find_user_by_id(id)
            .await
            .context(format!("查询用户失败: id={}", id))?
            .ok_or_else(|| anyhow!("用户不存在: id={}", id))
    }

    async fn send_welcome_email(&self, user: &User) -> Result<()> {
        // 模拟邮件发送
        tracing::info!("发送欢迎邮件至: {}", user.email);
        Ok(())
    }
}

/// 简化的数据库连接池
struct DatabasePool;

impl DatabasePool {
    async fn insert_user(&self, _name: &str, _email: &str) -> std::result::Result<User, DatabaseError> {
        // 模拟数据库操作
        Ok(User { id: 1, name: String::new(), email: String::new() })
    }

    async fn find_user_by_id(&self, id: u64) -> std::result::Result<Option<User>, DatabaseError> {
        if id == 0 {
            Err(DatabaseError::QueryTimeout {
                sql: "SELECT * FROM users WHERE id = ?".to_string(),
                timeout_ms: 5000,
            })
        } else {
            Ok(Some(User { id, name: "test".to_string(), email: "test@test.com".to_string() }))
        }
    }
}

#[derive(Debug)]
pub struct User {
    pub id: u64,
    pub name: String,
    pub email: String,
}

错误处理的分层策略

/// 错误处理的分层策略：库层精确，应用层统一
///
/// 原则：
/// - 库 Crate（可被他人依赖）：使用 thiserror 定义具体错误类型
///   调用方需要 match 不同变体做出不同响应
/// - 应用 Crate（最终可执行程序）：使用 anyhow 统一错误类型
///   不需要区分错误类型，只需要记录和展示
/// - 边界层（API 入口）：将 anyhow::Error 转换为 HTTP 响应

/// API 层：将 anyhow 错误转换为 HTTP 响应
pub fn error_to_http_response(error: &anyhow::Error) -> (u16, String) {
    // 检查是否为特定错误类型，返回对应 HTTP 状态码
    if let Some(db_err) = error.downcast_ref::<DatabaseError>() {
        return match db_err {
            DatabaseError::NotFound { .. } => (404, db_err.to_string()),
            DatabaseError::ConstraintViolation { .. } => (409, db_err.to_string()),
            DatabaseError::PoolExhausted { .. } => (503, "服务暂时不可用".to_string()),
            _ => (500, "内部服务器错误".to_string()),
        };
    }

    if let Some(config_err) = error.downcast_ref::<ConfigError>() {
        return match config_err {
            ConfigError::FileNotFound { .. } => (500, "服务配置错误".to_string()),
            ConfigError::InvalidValue { .. } => (400, config_err.to_string()),
            _ => (500, "内部服务器错误".to_string()),
        };
    }

    // 未知错误：返回 500，不暴露内部细节
    tracing::error!("未处理的错误: {:?}", error);
    (500, "内部服务器错误".to_string())
}

/// 错误报告：生成用户友好的错误描述
pub fn format_error_chain(error: &anyhow::Error) -> String {
    let mut parts = Vec::new();
    let mut source = error.source();
    let mut depth = 0;

    // 遍历错误链，逐层展示
    while let Some(err) = source {
        parts.push(format!("  {}: {}", depth, err));
        source = err.source();
        depth += 1;
    }

    if parts.is_empty() {
        error.to_string()
    } else {
        format!("{}\n错误链:\n{}", error, parts.join("\n"))
    }
}

use std::error::Error;

四、错误处理的工程权衡与常见反模式

thiserror vs anyhow 的选择边界：库 Crate 必须用 thiserror，因为调用方需要根据错误类型做分支处理；应用 Crate 用 anyhow，因为最终只需要记录和展示。反模式是在库中返回 anyhow::Error——调用方无法 match 具体错误，只能做字符串匹配，这比 Java 的 checked exception 还糟糕。

过度嵌套的 map_err：当错误类型不匹配时，需要 map_err 转换。如果调用链很长，每层都 map_err 会让代码变得冗长。? 操作符配合 From trait 实现可以消除大部分 map_err，但前提是错误类型体系设计合理——底层错误应该能自动转换为上层错误。

错误信息的安全边界：生产环境中，错误信息不应暴露内部实现细节（如数据库表名、文件路径、SQL 语句）。对外返回通用错误描述，详细信息只写入日志。anyhow 的 Debug 格式包含完整错误链，适合日志；Display 格式只包含最外层描述，适合返回给用户。

panic 的合理使用场景：只有两种情况可以接受 panic——逻辑上不可能发生的分支（如 Option::unwrap 在已经校验过的值上）和初始化阶段的致命错误（如配置文件缺失导致无法启动）。运行时的可恢复错误必须用 Result，绝不 panic。

五、总结

Rust 错误处理的核心是"让错误在类型系统中可见，在编译期被处理"。落地建议：第一，库 Crate 用 thiserror 定义精确错误枚举，让调用方可以 match 分支处理；第二，应用 Crate 用 anyhow 统一错误类型，用 .context() 附加业务上下文；第三，实现 From trait 消除手动 map_err，让 ? 操作符自动转换错误类型；第四，API 边界层用 downcast 将 anyhow 错误映射为 HTTP 状态码，对外不暴露内部细节；第五，生产环境中禁止 unwrap，所有可恢复错误走 Result 传播。错误处理不是负担，是 Rust 给的"编译期保险"——编译器替你检查了每一个错误路径。