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 实现。

toml
[dependencies]
thiserror = "2"

这是 Cargo.toml 的依赖片段。保存后可运行检查命令,确认依赖解析和派生宏能够正常编译。

bash
cargo check

预期结果

text
Finished `dev` profile [unoptimized + debuginfo] target(s) in <TIME>

首次执行时还可能出现依赖下载和编译记录;<TIME> 会随机器性能和缓存状态变化,关键验证结果是命令成功结束且没有编译错误。

同时声明消息、source 与透明转换

下面包含两种常见边界:Config 变体补充“加载配置失败”的应用语义,并用 #[source] 保留底层原因;Io 变体通过 #[from] 接收 io::Error,再用 #[error(transparent)] 沿用底层错误的显示行为。

rust
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}");
    }
}

预期输出

text
error: 加载配置失败
source: 文件不存在: <PATH>
transparent: disk offline

#[source] 只声明错误链关系,不负责类型转换;#[from] 会为字段类型生成 From,因此 ? 可以把 io::Error 自动转换成 AppError。两者解决的是不同问题。

什么时候使用 transparent

#[error(transparent)] 适合当前层没有新的语义,只需要把底层错误纳入统一返回类型的情况。例如某个库边界统一返回 AppError,而一个 io::Error 不需要额外说明操作对象时,透明变体可以避免重复包装消息。

如果调用者需要知道“读取的是哪份配置”“处理的是哪个订单”,就不应透明透传,而应建立具名变体,并在 #[error(...)] 中加入这一层上下文。否则日志只剩底层技术错误,很难还原业务现场。

保持错误类型可演进

thiserror 主要减少样板代码,并不会替你决定错误边界。公共 API 中仍应谨慎直接暴露第三方库的错误类型,因为依赖一旦进入公开枚举,未来替换库可能演变成破坏性变更。

更稳妥的原则是:领域或应用层错误用自己的变体表达稳定语义;需要保留底层原因时使用 #[source];只有本层确实没有额外语义时才使用透明包装。这样既保留标准错误链,也不会让错误模型被具体依赖绑死。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 thiserror 减少样板代码

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通