SuperAPI AI 工具集

m06-error-handling

编程与开发

查看项目

更新于 10-15 10:31

技能介绍

用途

本技能用于指导 Rust 中的错误处理(Error Handling)。它的核心问题是:这个失败是预期内的,还是程序缺陷(bug)? 在决定错误处理策略之前,技能建议先回答三个问题:

  • 这在正常运行中可能失败吗?
  • 谁应该处理这个失败?
  • 调用者需要什么上下文?

主要能力

技能将错误处理拆解为语言机制与设计决策两个层面,并提供以下内容:

  • 错误到设计问题的映射:例如遇到 unwrap panic 时,不应只说“用 ?”,而应问“这里 None/Err 真的可能发生吗?”;遇到 ? 类型不匹配时,应问“错误类型设计是否正确?”;遇到丢失错误上下文时,应问“调用者需要知道什么?”;遇到错误变体过多时,应问“错误粒度是否合适?”
  • 思考提示:处理错误前先判断失败类型(预期失败用 Result<T, E>,正常缺失用 Option,缺陷/不变量违反用 panic!,不可恢复用 panic!);再判断由谁处理(调用者用 ? 传播,当前函数用 match/if-let,用户需要友好错误信息,程序员需要带消息的 panic);最后判断需要什么上下文(错误类型用 thiserror 变体,调用链用 anyhow::Context,调试信息用 anyhow 或 tracing)。
  • 向上追溯(Trace Up):当错误策略不清晰时,引导检查领域模型(m09-domain)、领域错误处理需求(domain-*)等。
  • 向下追溯(Trace Down):从设计到实现,给出具体选择,例如库代码用 thiserror 定义类型化错误,应用代码用 anyhow 获得更顺手的错误处理,正常缺失用 Option<T>,缺陷或不变量违反用 panic!、assert!、unreachable!,需要带上下文传播时用 .context("what was happening")。
  • 快速参考表:列出 Result<T, E>(可恢复错误)、Option<T>(正常缺失)、?(传播错误)、unwrap()(仅开发/测试)、expect()(不变量成立时)、panic!(不可恢复)的使用场景与示例。
  • 库与应用的区别:库使用 thiserror 为消费者提供类型化错误;应用使用 anyhow 获得更顺手的错误处理;混合场景在边界用 thiserror,内部用 anyhow。
  • 决策流程图:从“失败是否预期”出发,逐步导向 Option、Result、thiserror、anyhow、panic!、assert! 等选择;以及使用 ? 后是否需要上下文。
  • 常见错误与修复:unwrap() panic(未处理的 None/Err,改用 ? 或 match)、类型不匹配(不同错误类型,改用 anyhow 或 From)、丢失上下文(? 无上下文,添加 .context())、无法使用 ?(缺少 Result 返回类型,返回 Result<(), E>)。
  • 反模式:到处 .unwrap()(生产环境 panic,改用 .expect("reason") 或 ?)、静默忽略错误(隐藏 bug,应处理或传播)、对预期错误使用 panic!(用户体验差且无法恢复,应使用 Result)、到处使用 Box(丢失类型信息,应使用 thiserror)。

使用方式

本技能以文档形式提供,内容包含核心问题、思考提示、追溯路径、快速参考表、决策流程图、常见错误表和反模式表。使用者可在编写或审查 Rust 代码时,按流程图和参考表选择错误处理策略。技能本身未提供安装命令或代码示例之外的运行方式,相关安装信息暂未提供。

适用场景

  • 在 Rust 项目中决定何时返回 Result、何时返回 Option、何时 panic。
  • 设计库的公开错误类型,或为应用选择错误处理 crate。
  • 审查代码中过多的 unwrap、丢失的错误上下文、不合理的错误粒度。
  • 需要区分可恢复错误、正常缺失、程序缺陷与不可恢复失败时。

限制

本技能聚焦 Rust 错误处理的设计与实现指导,未提供具体项目的完整代码、性能数据或与其他语言的对比。官方文本(official_text)暂未提供。相关技能包括 m13-domain-error(领域错误策略)、m11-ecosystem(crate 边界)、m05-type-driven(类型安全错误)、m14-mental-model(心智模型)。