Rust 错误处理最佳实践清单：从库到应用的一整套约定-拓冰建站

Rust 错误处理最佳实践清单：从库到应用的一整套约定

一、错误处理是 Rust 工程的"隐形骨架"

为什么错误处理这么难？因为 The Book 只教了Result和?操作符，但真实项目里你会不断遇到这些问题：

我的库应该用什么错误类型？
不同的 crate 用不同的错误类型，怎么统一？
unwrap 和 expect 到底能不能用？什么时候用？
应用层和库层的错误处理有什么区别？

这篇文章是我从各个项目、各种坑里总结出的一套约定清单。

flowchart TD A["库层（Library）"] --> B["用 thiserror\n定义自定义错误类型"] A --> C["每个错误变体带上下文字段"] A --> D["实现 std::error::Error"] A --> E["暴露 Error 给下游处理"] F["应用层（Application）"] --> G["用 anyhow 简化错误传播"] F --> H["只在确定不会出错时用 unwrap"] F --> I["用户可见错误用中文提示"] F --> J["main 返回 anyhow::Result"]

二、库层的错误处理约定

写库的时候，目标是让下游调用者能精确匹配并处理每一个错误变体。推荐用thiserror：

use std::path::PathBuf; use thiserror::Error; /// 解析器库的错误类型 /// 每个变体都要考虑：调用者能不能据此做出有意义的处理？ #[derive(Error, Debug)] pub enum ParserError { /// 文件不存在——调用者可能想重试或提示用户 #[error("文件不存在: {path}")] FileNotFound { path: PathBuf, }, /// 格式错误——调用者可能想降级处理 #[error("第 {line} 行格式错误: {detail}")] InvalidFormat { line: usize, detail: String, }, /// 编码问题——调用者可能想换编码重试 #[error("编码转换失败: {source}")] EncodingError { #[from] source: std::string::FromUtf8Error, }, /// I/O 错误——来自标准库，直接透传 #[error("I/O 错误: {source}")] Io { #[from] source: std::io::Error, }, } // 必须实现 std::error::Error（thiserror 自动实现了） // 可选：实现 From trait 让 ? 操作符能自动转换 impl From<std::io::Error> for ParserError { fn from(err: std::io::Error) -> Self { if err.kind() == std::io::ErrorKind::NotFound { ParserError::FileNotFound { path: PathBuf::from("unknown"), } } else { ParserError::Io { source: err } } } }

库层核心约定总结：

约定	说明
用`thiserror::Error`derive	一行宏搞定 Display + Error trait 实现
每个变体带上下文字段	`FileNotFound { path }`而不是`FileNotFound(String)`
不要直接`unwrap()`	返回 Result，把决策权交给调用者
暴露具体错误类型	调用者可以用`match`区分不同错误

三、应用层的错误处理约定

应用层关注点在"不要让程序崩溃 + 给用户友好的错误信息"。推荐anyhow：

use anyhow::{Context, Result}; /// 应用入口 fn main() -> Result<()> { // anyhow::Result = Result<T, anyhow::Error> // anyhow::Error 可以包装任何 std::error::Error let config = load_config() .context("加载配置文件失败")?; // context 加上下文信息 let data = process_data(&config) .with_context(|| format!("处理文件 {} 时出错", config.input_path))?; save_result(&data) .context("保存结果失败")?; Ok(()) } fn load_config() -> Result<Config> { let content = std::fs::read_to_string("config.toml") .context("无法读取 config.toml")?; toml::from_str(&content) .context("config.toml 格式错误")? // 自动转换 toml::de::Error // 注意：anyhow 的 context 不改变底层错误类型， // 只是在错误链上加一层描述 }

关于unwrap和expect的纪律：

// ✅ 可以用 unwrap 的场景 let mut map: HashMap<String, i32> = HashMap::new(); map.insert("key".into(), 42); let value = map.get("key").unwrap(); // 刚插入，不可能不存在 // ✅ 可以用 expect 的场景 let home = std::env::var("HOME").expect("操作系统必须提供 HOME 变量"); // ❌ 不应该用 unwrap 的场景 let file = std::fs::File::open("user-input-path").unwrap(); // 用户输错路径就 panic let api_key = std::env::var("API_KEY").unwrap(); // 可能没设置，panic 体验很差

实战踩坑：thiserror 和 anyhow 混用的坑

坑1：在库 crate 里错误地引入了anyhow。一开始我的meta-core里用了anyhow::Result作为函数返回值。外部调用者拿到的是anyhow::Error而非我的ParserError，完全没法match区分错误类型。anyhow只适合二进制 crate（应用层），库 crate 必须用具体错误类型。

坑2：#[from]宏的隐式转换出乎意料。thiserror的#[from]会自动生成From<T> for ParserError，这导致?操作符自动把底层错误往上抛。好处是代码简洁，坏处是中间上下文信息丢了——本来std::io::Error里可能有详细的文件路径信息，但自动转换后只剩一句"I/O 错误"。解法：对关键路径不用#[from]，手动写From实现，在转换时保留原始上下文。

坑3：Box<dyn Error>的"方便"陷阱。快速原型时我喜欢用Box<dyn std::error::Error>做返回值，因为它能吞任何错误。但编译出来的二进制比用具体错误类型大了 8KB，而且downcast_ref检查错误类型有运行时开销。发布时必须替换。

四、错误处理的级别划分

flowchart TD subgraph L1["级别 1：裸 panic（原型阶段）"] P1["fn foo() { File::open(p).unwrap(); }"] end subgraph L2["级别 2：Result + ?（基本可用）"] P2["fn foo() -> Result<()> { File::open(p)?; Ok(()) }"] end subgraph L3["级别 3：自定义错误类型（库发布）"] P3["enum AppError { ... } + thiserror"] end subgraph L4["级别 4：错误上下文 + 用户友好信息（产品级）"] P4["anyhow::context + 中文错误提示 + 日志"] end L1 -->|"代码逐渐成型"| L2 L2 -->|"准备发布"| L3 L3 -->|"用户开始使用"| L4

实际开发节奏建议：