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

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

一、Rust 没有 try-catch，但它的错误处理比异常更安全

从 Python 转到 Rust，最不习惯的就是没有 try-catch。Python 里 try: ... except Exception as e: ... 一套走天下，Rust 里每个可能失败的操作都返回 Result<T, E>，你必须处理 Ok 和 Err。刚开始觉得烦，后来发现这恰恰是 Rust 的优势——编译器逼着你处理每一个可能的错误，不会出现"异常被吞掉"的情况。

这篇文章记录我从 unwrap() 满天飞到合理使用 ?、thiserror 和错误分层的全过程，都是实际项目中踩过的坑。

二、Rust 错误处理的层次体系

flowchart TB
    A[Rust 错误处理] --> B[可恢复错误<br/>Result<T, E>]
    A --> C[不可恢复错误<br/>panic!]

    B --> B1[错误传播<br/>? 运算符]
    B --> B2[错误转换<br/>From trait]
    B --> B3[错误聚合<br/>thiserror / anyhow]

    B3 --> B4[thiserror<br/>库的错误类型定义]
    B3 --> B5[anyhow<br/>应用的错误传播]

    C --> C1[逻辑不可能失败<br/>assert! / unreachable!]
    C --> C2[内存耗尽等<br/>不可恢复场景]

    B1 --> D[错误分层<br/>领域错误 → 基础错误]
    B2 --> D

    D --> D1[IO 错误<br/>std::io::Error]
    D --> D2[解析错误<br/>自定义 ParseError]
    D --> D3[业务错误<br/>自定义 AppError]

    style B4 fill:#e3f2fd
    style B5 fill:#fff3e0
    style D fill:#e8f5e9

Rust 错误处理的核心原则：可恢复错误用 Result，不可恢复错误用 panic!。库代码用 thiserror 定义精确的错误类型，应用代码用 anyhow 简化错误传播。错误分层是关键——底层错误（IO、解析）通过 From trait 自动转换为上层错误（业务错误），调用者只需要处理业务错误。

三、代码实现与分析

3.1 从 unwrap 到 ? 的进化

use std::fs;
use std::io;
use std::num::ParseIntError;

/// 阶段1：unwrap 满天飞（新手写法，生产代码不要这样）
fn read_config_bad(path: &str) -> Config {
    let content = fs::read_to_string(path).unwrap();  // 💥 文件不存在就 panic
    let port: u16 = content.trim().parse().unwrap();   // 💥 解析失败就 panic
    Config { port }
}

/// 阶段2：显式 match（正确但冗长）
fn read_config_verbose(path: &str) -> Result<Config, AppError> {
    let content = match fs::read_to_string(path) {
        Ok(c) => c,
        Err(e) => return Err(AppError::Io(e)),
    };

    let port: u16 = match content.trim().parse() {
        Ok(p) => p,
        Err(e) => return Err(AppError::Parse(e)),
    };

    Ok(Config { port })
}

/// 阶段3：? 运算符（简洁且安全）
fn read_config_good(path: &str) -> Result<Config, AppError> {
    let content = fs::read_to_string(path)?;  // 自动转换错误类型
    let port: u16 = content.trim().parse()?;   // 自动转换错误类型
    Ok(Config { port })
}

#[derive(Debug)]
struct Config {
    port: u16,
}

3.2 thiserror：库的错误类型定义

use thiserror::Error;

/// 应用级错误类型：用 thiserror 派生 Error trait
#[derive(Debug, Error)]
enum AppError {
    /// IO 错误：自动实现 From<io::Error>
    #[error("IO 错误: {0}")]
    Io(#[from] io::Error),

    /// 解析错误：自动实现 From<ParseIntError>
    #[error("配置解析失败: {0}")]
    Parse(#[from] ParseIntError),

    /// 数据库错误
    #[error("数据库错误: {message}")]
    Database {
        message: String,
        #[source]
        source: Box<dyn std::error::Error + Send + Sync>,
    },

    /// 业务逻辑错误
    #[error("用户 {user_id} 不存在")]
    UserNotFound { user_id: u64 },

    /// 权限错误
    #[error("权限不足: 需要 {required}, 当前 {actual}")]
    PermissionDenied { required: String, actual: String },

    /// 验证错误：包含多个字段
    #[error("数据验证失败: {fields:?}")]
    Validation { fields: Vec<String> },
}

/// 使用示例
fn find_user(user_id: u64) -> Result<User, AppError> {
    // ? 自动将 io::Error 转换为 AppError::Io
    let data = fs::read_to_string("users.txt")?;

    // 业务错误直接构造
    if user_id > 1000 {
        return Err(AppError::UserNotFound { user_id });
    }

    // 解析错误自动转换
    let port: u16 = data.trim().parse()?;

    Ok(User { id: user_id, name: data })
}

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

/// 批量验证：收集所有错误而非遇到第一个就返回
fn validate_user(name: &str, age: u8) -> Result<(), AppError> {
    let mut errors = Vec::new();

    if name.is_empty() {
        errors.push("姓名不能为空".to_string());
    }
    if age < 18 {
        errors.push("年龄必须 >= 18".to_string());
    }

    if errors.is_empty() {
        Ok(())
    } else {
        Err(AppError::Validation { fields: errors })
    }
}

3.3 anyhow：应用的错误传播

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

/// anyhow 适合应用代码：不需要定义精确的错误类型
/// 重点是快速传播错误并添加上下文信息
fn load_application_config(path: &str) -> Result<AppConfig> {
    let content = fs::read_to_string(path)
        .with_context(|| format!("读取配置文件失败: {}", path))?;

    let config: AppConfig = toml::from_str(&content)
        .context("解析配置文件失败")?;

    // 验证配置
    if config.port == 0 {
        // bail! 提前返回错误
        bail!("端口号不能为 0");
    }

    if config.database_url.is_empty() {
        bail!("数据库 URL 不能为空");
    }

    Ok(config)
}

/// 错误链：每一层都添加上下文
async fn connect_database(url: &str) -> Result<DbConnection> {
    let pool = sqlx::PgPool::connect(url)
        .await
        .context("创建连接池失败")?;

    sqlx::query("SELECT 1")
        .execute(&pool)
        .await
        .context("数据库健康检查失败")?;

    Ok(DbConnection { pool })
}

/// 处理错误链：打印完整的错误上下文
fn handle_error(err: anyhow::Error) {
    eprintln!("错误: {}", err);
    // 打印错误链
    for cause in err.chain() {
        eprintln!("  原因: {}", cause);
    }
}

#[derive(Debug)]
struct AppConfig {
    port: u16,
    database_url: String,
}

struct DbConnection {
    pool: sqlx::PgPool,
}

// 模拟 toml 解析
mod toml {
    use anyhow::Result;
    use serde::de::DeserializeOwned;

    pub fn from_str<T: DeserializeOwned>(s: &str) -> Result<T> {
        todo!()
    }
}

// 模拟 sqlx
mod sqlx {
    pub struct PgPool;
    impl PgPool {
        pub async fn connect(_url: &str) -> anyhow::Result<Self> {
            todo!()
        }
    }
    pub fn query(_sql: &str) -> Query { Query }
    pub struct Query;
    impl Query {
        pub async fn execute(&self, _pool: &PgPool) -> anyhow::Result<()> { todo!() }
    }
}

四、错误处理的边界与权衡

thiserror vs anyhow 的选择：thiserror 适合库代码——调用者需要精确匹配错误类型做不同处理。anyhow 适合应用代码——调用者只需要打印错误或向上传播。如果不确定，先用 anyhow，等需要精确匹配时再重构为 thiserror。

错误转换的隐式性：From trait 让 ? 自动转换错误类型，非常方便但也可能隐藏错误。如果底层错误被转换为上层错误后丢失了原始信息，调试时很难定位。建议在 From 实现中保留 #[source]，确保错误链完整。

panic 的合理使用场景：panic 适合"逻辑上不可能失败"的场景（如 Vec::get(0) 在确认非空后调用）。但在库代码中，应该尽量避免 panic——调用者可能不知道某个方法会 panic。如果必须 panic，在文档中用 # Panics 段落明确说明。

错误日志 vs 错误返回：不是所有错误都需要返回给调用者。有些错误（如监控上报失败）应该记录日志但不影响业务流程。建议用 if let Err(e) = ... { log::warn!(...) } 处理这类"可忽略但需记录"的错误，而不是用 ? 传播。

五、总结

Rust 的错误处理没有 try-catch，但 Result + ? + thiserror/anyhow 的组合比异常更安全——编译器逼着你处理每一个可能的错误。本文的关键实践为：库代码用 thiserror 定义精确的错误类型和 From 转换、应用代码用 anyhow + context() 快速传播错误并添加上下文、用 bail! 提前返回业务错误、用错误链保留完整的调试信息。从 unwrap() 到 ? 的进化，是从"写能跑的代码"到"写可靠的代码"的关键一步。

补充落地建议：围绕“Rust 错误处理模式：从 Result 到 thiserror 的生产级代码组织”继续推进时，应把验证标准写成可执行清单，而不是停留在经验判断。性能类方案要给出基准数据，架构类方案要给出故障隔离方式，AI 类方案要给出输出质量和人工兜底策略。每一次迭代都应回答三个问题：收益是否可量化，失败是否可回滚，维护成本是否被团队接受。

如果短期资源有限，可以先保留最关键的观测指标，包括处理耗时、失败率、资源占用和人工介入次数。等这些指标稳定后，再扩展自动化能力。这样的节奏更慢，但风险更低，也更符合生产级技术文章强调的工程可验证性。