SuperAPI AI 工具集

rust-error-handling

编程与开发

查看项目

更新于 10-26 16:21

技能介绍

用途

该技能用于指导 Rust 项目的错误处理设计,重点是划清「库」与「应用」之间的错误处理边界。它面向需要为 Rust 库设计公共错误类型、或为二进制/顶层应用组织错误传播与上下文的开发场景。

主要能力

  • 选型规则:库(有其他代码依赖、发布 API)应使用 thiserror,构建调用方可匹配的类型化错误枚举;应用(二进制、顶层)应使用 anyhow,采用 anyhow::Result<T>、处处使用 ? 并使用 .context() 添加追踪信息;仅有一两个变体的简单场景可用手写 std::error::Error 实现,避免引入依赖。
  • 关键约束:绝不在库的公共 API 中暴露 anyhow::Error,因为它会擦除类型,调用方无法匹配或处理具体失败;thiserror 的设计目标是不出现在公共 API 中,因此与手写实现之间切换不构成破坏性变更。
  • 上下文链:在应用代码的每一层用 .context("...") / .with_context(|| ...) 把「No such file or directory」变成可追踪的链条。
  • 转换简化:使用 #[from] 让 ? 将源错误提升为枚举变体,零样板;#[from] 隐含 #[source],不可同时书写两者。
  • 可恢复错误与 panic 的取舍:错误是值,panic 是缺陷;对调用方可合理恢复的情况使用 Result,panic!/unwrap/expect 仅用于保护被破坏的不变量。
  • 参考与模板:提供 thiserror-libraries.md、anyhow-applications.md、error-design.md 三份概念参考,以及 library-error.md、application-error.md 两份模板。
  • 校验清单:库错误为派生 thiserror::Error 的类型化枚举且公共 API 无 anyhow;应用返回 anyhow::Result<T> 并添加 .context(...);用 #[from] 做源转换且不冗余写 #[source];对易错值用 ? 而非 unwrap();panic 仅守护真实不变量并给出原因;cargo clippy 干净。

使用方式

该技能定义了强制的代理工作流:先用 fuse-ai-pilot:explore-codebase 判断当前 crate 是库(发布 API、被其他代码依赖)还是二进制/应用,据此选择工具;再用 fuse-ai-pilot:research-expert 在编写 derive 前确认当前 thiserror / anyhow API(验证链:在 docs.rs/thiserror 与 docs.rs/anyhow 上使用 fuse-browser 快速路径 → Context7 → Exa);编写完成后运行 fuse-ai-pilot:sniper 与 cargo clippy。

适用场景

适用于为 Rust 库设计公共错误枚举、为二进制程序组织错误传播与上下文信息、审查 crate 是否存在 anyhow 泄漏到公共 API 的问题,以及在项目中统一 thiserror 与 anyhow 的使用边界。

限制

通用所有权/借用设计不属于本技能,归 rust-core-language;异步运行时相关的错误处理未覆盖。