Rust thiserror 最佳实践让错误处理既优雅又实用一、Rust 错误处理的两种流派thiserror 与 anyhowRust 的错误处理有两个主流库thiserror 用于库代码anyhow 用于应用代码。我刚开始学 Rust 的时候搞不清什么时候用哪个结果在库代码里用 anyhow导致调用方无法匹配具体错误类型只能打印错误信息。核心区别thiserror 让你定义自己的错误类型调用方可以match不同错误做不同处理anyhow 把所有错误包装成anyhow::Error调用方只能打印或向上传播。库代码用 thiserror因为库的使用者需要根据错误类型做决策应用代码用 anyhow因为应用顶层只需要记录日志和展示错误信息。thiserror 的本质是过程宏帮你自动实现std::error::Errortrait 和Displaytrait。不用 thiserror 的话你需要手写几十行样板代码来实现这两个 trait。二、thiserror 的底层机制过程宏展开与错误链thiserror 通过过程宏在编译期生成代码。当你写#[derive(Error)]时宏会解析枚举的每个变体根据属性生成对应的Display实现和From实现。flowchart TB A[#[derive(Error)]] -- B[编译期宏展开] B -- C[生成 Display impl] B -- D[生成 Error impl] B -- E[生成 From implbr/标注 #[from] 时] C -- F[#[error(\...\)]br/格式化字符串 → fmt::Display] D -- G[source() 方法br/返回底层错误引用] E -- H[FromInnerErrorbr/自动转换] subgraph 错误链 I[顶层错误br/AppError] J[中间层错误br/DbError] K[底层错误br/io::Error] end I --|source| J J --|source| K subgraph 错误处理策略 L[库代码: thiserrorbr/定义具体错误类型] M[应用代码: anyhowbr/统一错误包装] end L -- N[调用方 match 处理] M -- O[顶层统一记录日志]错误链是 thiserror 的核心设计。每个错误可以持有底层错误的引用通过#[source]或#[from]形成链式结构。Error::source()方法沿着链条向上追溯让日志库可以打印完整的错误栈。三、生产级代码实现thiserror 实战模式3.1 基础错误类型定义use thiserror::Error; /// 数据库操作错误 // 为什么用枚举而非结构体枚举让调用方 // 可以 match 不同错误类型做不同处理 // 结构体只能通过字段区分不如枚举直观 #[derive(Debug, Error)] pub enum DbError { // #[error] 属性定义 Display 输出格式 // 为什么用格式化字符串比手写 Display // impl 简洁编译期检查格式参数 #[error(连接数据库失败: {0})] ConnectionFailed(String), #[error(查询超时: {operation} 耗时 {elapsed_ms}ms)] QueryTimeout { operation: String, elapsed_ms: u64, }, // #[from] 自动实现 Fromio::Error // 为什么用 #[from]省去手写 // Fromio::Error for DbError 的 // 样板代码同时标记为错误链的 source #[error(IO 错误)] Io(#[from] std::io::Error), // #[from] 也可以用于自定义错误类型 #[error(数据解析失败)] Parse(#[from] serde_json::Error), #[error(记录未找到: {table}/{id})] NotFound { table: String, id: String, }, #[error(并发冲突: {resource} 被 {holder} 占用)] ConcurrencyConflict { resource: String, holder: String, }, } /// 应用层错误 #[derive(Debug, Error)] pub enum AppError { #[error(数据库错误: {0})] Db(#[from] DbError), #[error(配置错误: {0})] Config(String), #[error(认证失败: {reason})] Auth { reason: String }, #[error(请求限流: 请 {retry_after_secs} 秒后重试)] RateLimited { retry_after_secs: u32 }, // 透明传递直接使用内部错误的 // Display 输出不添加额外信息 // 为什么用 #[error(transparent)] // 有些底层错误的描述已经足够清晰 // 不需要再包装一层 #[error(transparent)] Other(#[from] anyhow::Error), }3.2 错误转换与上下文信息use std::path::PathBuf; /// 文件处理错误展示丰富的上下文信息 #[derive(Debug, Error)] pub enum FileProcessError { // 在错误信息中包含文件路径 // 为什么包含路径只有 文件未找到 // 无法定位问题加上路径才能排查 #[error(文件未找到: {path})] FileNotFound { path: PathBuf, // #[source] 标记底层错误但不用于 // Display 输出 #[source] source: std::io::Error, }, #[error(文件格式错误: {path}, 期望 {expected}, 实际 {actual})] InvalidFormat { path: PathBuf, expected: String, actual: String, }, #[error(文件过大: {path}, 大小 {size}MB 超过限制 {limit}MB)] FileTooLarge { path: PathBuf, size: u64, limit: u64, }, } /// 文件处理函数 fn process_file( path: std::path::Path ) - ResultString, FileProcessError { // 使用 ? 运算符自动转换错误 let content std::fs::read_to_string(path) .map_err(|e| { // 手动构建带上下文的错误 // 为什么用 map_err 而非 ? // ? 只能用于实现了 From 的 // 错误类型这里需要添加 // 文件路径上下文信息 FileProcessError::FileNotFound { path: path.to_path_buf(), source: e, } })?; // 验证格式 if !content.starts_with({) { return Err(FileProcessError::InvalidFormat { path: path.to_path_buf(), expected: JSON 对象.to_string(), actual: 非 JSON 格式.to_string(), }); } // 检查大小 let size_mb content.len() as u64 / 1024 / 1024; if size_mb 100 { return Err(FileProcessError::FileTooLarge { path: path.to_path_buf(), size: size_mb, limit: 100, }); } Ok(content) }3.3 错误处理策略与恢复use std::time::Duration; /// 带重试的错误恢复策略 // 为什么把重试逻辑和错误类型放一起 // 重试策略取决于错误类型——连接超时 // 可以重试数据损坏不应该重试 impl DbError { /// 判断错误是否可重试 pub fn is_retryable(self) - bool { match self { // 网络相关错误可以重试 DbError::ConnectionFailed(_) true, DbError::QueryTimeout { .. } true, // 数据错误不应重试 DbError::NotFound { .. } false, DbError::Parse(_) false, DbError::ConcurrencyConflict { .. } true, // IO 错误需要区分类型 DbError::Io(e) { matches!( e.kind(), std::io::ErrorKind::TimedOut | std::io::ErrorKind::ConnectionReset | std::io::ErrorKind::ConnectionAborted ) } } } /// 获取建议的重试间隔 pub fn retry_delay(self) - Duration { match self { DbError::ConnectionFailed(_) { // 连接失败较长等待 Duration::from_secs(5) } DbError::QueryTimeout { .. } { // 查询超时中等等待 Duration::from_secs(2) } DbError::ConcurrencyConflict { .. } { // 并发冲突短暂等待 Duration::from_millis(100) } _ Duration::from_secs(1), } } } /// 通用重试执行器 async fn retry_on_errorT, F, Fut, E( max_retries: u32, operation: F, ) - ResultT, E where F: Fn() - Fut, Fut: std::future::FutureOutput ResultT, E, E: std::error::Error Clone, { let mut last_error: OptionE None; for attempt in 0..max_retries { match operation().await { Ok(result) return Ok(result), Err(e) { last_error Some(e.clone()); if attempt max_retries { // 这里简化了延迟逻辑 // 实际应根据错误类型 // 决定是否重试和延迟时间 tokio::time::sleep( Duration::from_millis( 100 * 2_u64.pow(attempt) )).await; } } } } Err(last_error.expect(至少有一次错误)) }四、thiserror 的边界不适合的场景快速原型和脚本如果你在写一个一次性脚本或快速验证想法anyhow 比 thiserror 更方便。不需要定义错误类型anyhow!和bail!宏可以快速抛出带上下文的错误。跨 crate 错误聚合当你的应用依赖多个库每个库有自己的错误类型用 thiserror 的#[from]会导致错误枚举膨胀。此时用 anyhow 包装更简洁或者定义一个顶层错误枚举只包含应用关心的错误类别。需要错误码的场景thiserror 的错误类型没有内置错误码。如果你的 API 需要返回数字错误码如 gRPC status code需要手动添加。可以用#[error_code 404]这样的自定义属性但需要额外的宏支持。动态错误类型如果你的错误类型在编译期无法确定如插件系统thiserror 的静态枚举无法满足需求。此时用Boxdyn Error或 anyhow 更合适。五、总结thiserror 的核心价值是让错误类型定义简洁、错误信息可读、错误链可追溯。使用原则库代码用 thiserror 定义具体错误类型应用代码用 anyhow 统一包装。#[from]自动实现 From 和标记 source#[error]定义格式化输出#[source]标记底层错误。错误信息要包含足够的上下文文件路径、操作名称、具体值让调用方不需要翻源码就能定位问题。可重试的错误应该实现is_retryable()方法让重试逻辑和错误类型绑定而非散落在业务代码中。