1 / 4概念
Error
Rust 没有异常,失败是普通返回值:Result<T, E> 表示可恢复错误,Option<T> 表示值可能缺失,panic! 表示不变量被破坏。判断标准不是“错误类型写得多细”,而是调用方能否区分失败原因、日志能否还原调用链、panic 是否只出现在真正的 bug 上。
1 概念
1.1 一句话定义
错误是值:Result<T, E> 把成功与失败放进同一个枚举,? 在 Err 时通过 From 转换并提前返回,thiserror 生成具体错误类型,anyhow 在应用层聚合上下文,panic! 用于不可恢复的违约。
1.2 它解决什么问题
- 异常把失败路径藏在签名之外,调用方容易忘记处理;错误信息层层丢失,日志只剩“操作失败”。
- 每层都定义新错误类型,调用方无法匹配,类型爆炸。
unwrap把可恢复错误升级成进程崩溃。- 业务失败与编程错误混在一起,无法决定重试还是告警。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| 枚举、泛型与 trait 基础 | OOP |
dyn 对象与 trait 对象安全 | OOP、AOP |
异步任务失败与 JoinError | Async |
| 日志、指标与追踪后端 | 可观测性章节 |
| FFI 的 panic 边界、退出码与信号 | Interop、平台章节 |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
Result<T, E> | 成功值或错误值 | 不是异常 |
Option<T> | 有值或无值 | 不携带失败原因 |
? | 失败时提前返回 | 不是 try/catch |
From | 错误类型转换 | 一个来源只能有一个 From |
Error trait | 错误的标准契约 | Display 与 Debug 分工不同 |
| source | 下层错误 | 不自动打印 |
| thiserror | 生成错误类型实现 | 面向库作者 |
| anyhow | 类型擦除的应用错误 | 面向应用层 |
| context | 附加的上下文消息 | 不是新的错误类型 |
| panic | 不可恢复的终止 | 不是业务错误 |
| unwind / abort | 栈展开 / 直接终止 | 后者不可捕获 |
2 机制
2.1 心智模型
把错误传播想成一条显式的异常栈:每一层只做三件事之一——处理、添加上下文、转换成上层类型。? 是传送带,From 是转换器,source() 把链条串起来。panic! 是另一条轨道,它越过所有返回类型直接终止进程,因此只应承载“程序写错了”这一种含义。
2.2 机制拆解
Result是枚举:Ok(T)与Err(E)同大小竞争,编译器用 niche 优化压缩布局;Result<(), ()>只占 1 字节。?的脱糖:等价于match expr { Ok(v) => v, Err(e) => return Err(From::from(e)) };在返回Option的函数里对Option使用时不调用From。From与#[from]:thiserror的#[from]同时生成From实现;同一错误类型只能有一个同源From,多来源要手写或用#[source]。Errortrait:Display给用户看,Debug给开发者看,source()返回下层错误;默认实现返回None,链路因此容易断。- thiserror:derive 生成
Display、Error、From;#[error("...")]支持字段插值,#[source]标记下层。 - anyhow:
anyhow::Error是类型擦除的错误容器,context/with_context追加消息,bail!/ensure!提前返回;代价是调用方无法match具体变体。 - panic 策略:默认
unwind,panic = "abort"关闭展开以减小体积;catch_unwind只能捕获展开,且要求UnwindSafe。
2.3 完整枚举
Rust 的失败通道,按“能否恢复、是否携带原因”枚举:
| 通道 | 类型/机制 | 可恢复 | 携带原因 | 传播方式 | 成本 |
|---|---|---|---|---|---|
| 具体错误 | Result<T, MyError> | 是 | 是 | ? + From | 0 |
| 擦除错误 | Result<T, Box<dyn Error>> | 是 | 是(动态) | ? + From | 1 次间接 |
| 应用聚合 | anyhow::Result<T> | 是 | 是 + 上下文 | ? + context | 装箱 |
| 缺失值 | Option<T> | 是 | 否 | ?/ok_or | 0 |
| 不变量违约 | panic!(unwind) | 否 | 否(有位置) | 展开 | 展开开销 |
| 直接终止 | panic = "abort" | 否 | 否 | 立即终止 | 最低 |
| 捕获展开 | catch_unwind | 部分 | 否 | 返回 Result | 展开开销 |
| 主函数返回 | Termination | 是 | 是 | 返回 Err | 0 |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
Result<(), ()> | 1 字节 | 只有标签 |
Result<u32, ()> | 8 字节 | 对齐到 4 字节后填充 |
Result<&u8, ()> | 8 字节 | 指针 niche 优化 |
Result<u64, u64> | 16 字节 | 无 niche,需独立标签 |
Option<&T> | 8 字节 | 空指针 niche |
result_large_err 阈值 | 128 字节 | clippy 默认告警线 |
| panic 默认策略 | unwind | panic = "abort" 可改为终止 |
? 运行时成本 | 0 | 一次 match |
3 实践
3.1 最小示例
只用标准库定义错误枚举、实现 Error::source、用 ? 转换并手动遍历错误链:
use std::{error::Error, fmt, num::ParseIntError};
#[derive(Debug)]
enum ConfigError {
Missing(&'static str),
BadPort(ParseIntError),
}
impl fmt::Display for ConfigError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
ConfigError::Missing(key) => write!(f, "missing key: {key}"),
ConfigError::BadPort(err) => write!(f, "invalid port: {err}"),
}
}
}
impl Error for ConfigError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
match self {
ConfigError::BadPort(err) => Some(err),
ConfigError::Missing(_) => None,
}
}
}
impl From<ParseIntError> for ConfigError {
fn from(err: ParseIntError) -> Self {
ConfigError::BadPort(err)
}
}
fn port(raw: Option<&str>) -> Result<u16, ConfigError> {
let raw = raw.ok_or(ConfigError::Missing("port"))?;
let port: u16 = raw.trim().parse()?;
Ok(port)
}
fn main() -> Result<(), ConfigError> {
println!("port = {}", port(Some("8080"))?);
if let Err(err) = port(Some("abc")) {
eprintln!("handled: {err}");
let mut source = err.source();
while let Some(cause) = source {
eprintln!(" caused by: {cause}");
source = cause.source();
}
}
Ok(())
}
读法:ok_or 把 Option 升级成带原因的 Result;parse()? 触发 From<ParseIntError>,把底层错误包进 BadPort。source() 返回 Some(err),遍历循环打印出“invalid port: invalid digit found in string”与“caused by: invalid digit found in string”两级链条。main 返回 Result,成功退出码 0,失败时 Debug 打印后退出 1。
3.2 常用操作与参数
| 操作 | 写法 | 说明 |
|---|---|---|
| 加消息 | f().map_err(|e| AppError::Load(e))? | 保留下层错误 |
| 附上下文 | f().context("load config")? | anyhow 专用 |
| 缺失转错误 | opt.ok_or(MyError::Missing)? | ok_or_else 延迟构造 |
| 提前返回 | bail!("bad input: {input}") | anyhow 宏 |
| 条件校验 | ensure!(n > 0, "n must be positive") | anyhow 宏 |
| 公共枚举 | #[non_exhaustive] pub enum E | 允许新增变体 |
| 擦除类型 | Box<dyn Error + Send + Sync> | 跨层聚合 |
3.3 标准流程
- 先给失败分类:缺失、校验失败、外部依赖失败、不变量违约。
- 缺失用
Option,可恢复失败用Result,不变量违约才用panic!。 - 库的公开 API 定义具体错误枚举,加
#[non_exhaustive],实现Display/Error/source。 - 应用层用
anyhow聚合,在跨模块边界补context,只在入口打印一次错误链。 - 需要重试或映射状态码时按错误变体分类,不靠字符串匹配;用 CI 规则守住
unwrap。
3.4 与相邻技术的组合
- thiserror + anyhow:库内部用 thiserror 保留可匹配的变体,边界处转成 anyhow 加上下文。
- HTTP 服务:错误枚举映射为状态码与响应体,内部细节只记日志不返回给客户端。
- 重试策略:按错误变体判定可重试性,
429/超时与参数错误不能用同一策略。
3.5 选型维度
| 场景 | 选择 | 理由 |
|---|---|---|
| 库的公开 API | thiserror 枚举 + #[non_exhaustive] | 调用方可匹配、可演进 |
| 应用入口与业务流程 | anyhow::Result | 上下文与聚合优先 |
| 仅表示缺失 | Option<T> | 没有失败原因可承载 |
| 不变量校验 | expect("...") | 出现即 bug |
| FFI 边界 | 错误码 + 不 panic | 跨语言不能展开 |
3.6 决策规则
- 调用方需要
match的失败,必须用具体枚举,不要用anyhow。 - 错误的
Display写“发生了什么”,source保留“为什么”,不要把两者混在一句里。 - 每个跨层边界补一次上下文,不要每层都包一层。
unwrap只允许出现在测试与已证明的不变量处;生产路径改?或expect并写明不变量。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
| 具体枚举(thiserror) | 可匹配、可文档化、零成本 | 变体多、需维护 | 库、协议解析 |
anyhow | 上下文丰富、样板少 | 无法匹配、装箱 | 应用层、CLI |
Box<dyn Error> | 标准库自带、简单 | 类型擦除、不够结构化 | 小工具、原型 |
| C 风格错误码 | 跨语言、ABI 稳定 | 丢上下文、易忽略 | FFI 边界 |
3.8 何时不该用
- 值只是可能缺失、没有失败语义时,不要硬造
Result。 - 函数体内部的不变量已经由类型保证时,不必再返回
Result。 - 库中不要暴露
anyhow::Error,它剥夺了调用方的匹配能力。 - 需要跨 FFI 且调用方无法处理 Rust 错误时,用错误码并在边界记录日志。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
进程被 unwrap 打崩 | 外部输入走了 unwrap | 改 ? 或 expect 并校验 |
| 日志只有顶层消息 | source() 未实现或未打印 | 实现 #[source] 并遍历错误链 |
clippy 报 result_large_err | 错误枚举超过 128 字节 | Box 大字段或改用 anyhow |
#[from] 冲突 | 同一来源类型出现两次 | 手写 From 或改 #[source] |
| 调用方无法匹配 | 库暴露了 anyhow | 改为具体枚举 |
panic = "abort" 下捕获失效 | catch_unwind 依赖展开 | 改为显式返回 Result |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
用 unwrap 处理用户输入 | 进程崩溃 | ? + 校验 |
map_err(|_| MyError::Unknown) | 丢失根因 | 保留 source |
用 String 当错误类型 | 无法分类、无 source | 结构化枚举 |
| 用 panic 表达业务失败 | 调用方无法恢复 | Result |
| 错误消息带密钥或 SQL | 泄露敏感信息 | 脱敏后记录 |
4.3 可观测信号
编译期:#[must_use] 与 unused_must_use 告警、clippy::result_large_err、clippy::unwrap_used(restriction 组)、thiserror 的 source 缺失。运行期:按错误变体聚合的错误率、tracing 中错误链深度、exit code 分布、panic 计数与 backtrace 采样。评审侧:新增错误变体是否破坏匹配、source 是否接通、Display 是否泄露内部细节。
4.4 安全 / 性能 / 一致性边界
- 安全:错误消息可能包含路径、SQL、令牌;对外响应要脱敏。跨 FFI 的 panic 必须阻止,
panic = "abort"可作兜底。 - 性能:
Result本身零成本,但大错误枚举的搬运、anyhow的装箱、format!的分配与source链遍历都会进入热路径。 - 一致性:错误类型是公共 API,变体删除与语义变更都属破坏性变更;
#[non_exhaustive]是演进的最低成本。 - 可运维性:错误必须能稳定聚合(变体名、错误码),不能靠自由文本;重试与告警规则应以变体为准。