Rust / 系统课时
用 thiserror 减少样板代码
用 thiserror 减少样板代码
手写 Display、Error::source 和 From 很容易产生重复代码。thiserror 用派生宏把这些规则直接声明在错误类型旁边:消息写进 #[error(...)],底层原因标记为 #[source],需要自动转换时再使用 #[from]。
学习目标
- 使用
thiserror::Error派生标准错误实现 - 理解
#[error]、#[source]、#[from]与transparent的作用 - 判断什么时候补充领域上下文,什么时候透明透传底层错误
把错误契约写在类型定义上
在 Cargo.toml 中加入依赖后,错误枚举只需要声明每个变体如何展示以及是否包含底层原因。宏会生成 Display 和 std::error::Error,存在 #[from] 时还会生成相应的 From 实现。
[dependencies]
thiserror = "2"这是 Cargo.toml 的依赖片段。保存后可运行检查命令,确认依赖解析和派生宏能够正常编译。
cargo check预期结果
Finished `dev` profile [unoptimized + debuginfo] target(s) in <TIME>首次执行时还可能出现依赖下载和编译记录;<TIME> 会随机器性能和缓存状态变化,关键验证结果是命令成功结束且没有编译错误。
同时声明消息、source 与透明转换
下面包含两种常见边界:Config 变体补充“加载配置失败”的应用语义,并用 #[source] 保留底层原因;Io 变体通过 #[from] 接收 io::Error,再用 #[error(transparent)] 沿用底层错误的显示行为。
use std::{error::Error as StdError, io};
use thiserror::Error;
#[derive(Debug, Error)]
#[error("文件不存在: {path}")]
struct FileMissing {
path: String,
}
#[derive(Debug, Error)]
enum AppError {
#[error("加载配置失败")]
Config {
#[source]
source: FileMissing,
},
#[error(transparent)]
Io(#[from] io::Error),
}
fn load_config() -> Result<(), AppError> {
Err(AppError::Config {
source: FileMissing {
path: "<PATH>".to_owned(),
},
})
}
fn passthrough_io() -> Result<(), AppError> {
Err(io::Error::other("disk offline"))?
}
fn main() {
if let Err(err) = load_config() {
println!("error: {err}");
if let Some(source) = StdError::source(&err) {
println!("source: {source}");
}
}
if let Err(err) = passthrough_io() {
println!("transparent: {err}");
}
}预期输出
error: 加载配置失败
source: 文件不存在: <PATH>
transparent: disk offline#[source] 只声明错误链关系,不负责类型转换;#[from] 会为字段类型生成 From,因此 ? 可以把 io::Error 自动转换成 AppError。两者解决的是不同问题。
什么时候使用 transparent
#[error(transparent)] 适合当前层没有新的语义,只需要把底层错误纳入统一返回类型的情况。例如某个库边界统一返回 AppError,而一个 io::Error 不需要额外说明操作对象时,透明变体可以避免重复包装消息。
如果调用者需要知道“读取的是哪份配置”“处理的是哪个订单”,就不应透明透传,而应建立具名变体,并在 #[error(...)] 中加入这一层上下文。否则日志只剩底层技术错误,很难还原业务现场。
保持错误类型可演进
thiserror 主要减少样板代码,并不会替你决定错误边界。公共 API 中仍应谨慎直接暴露第三方库的错误类型,因为依赖一旦进入公开枚举,未来替换库可能演变成破坏性变更。
更稳妥的原则是:领域或应用层错误用自己的变体表达稳定语义;需要保留底层原因时使用 #[source];只有本层确实没有额外语义时才使用透明包装。这样既保留标准错误链,也不会让错误模型被具体依赖绑死。