SuperAPI AI 工具集

m13-domain-error

编程与开发

查看项目

更新于 10-15 10:32

技能介绍

用途

该技能用于在设计领域错误处理时提供策略指导。其核心问题是:谁需要处理这个错误,以及他们应如何恢复?在设计错误类型之前,需要先回答:这是面向用户还是内部的?是否可能恢复?调试需要哪些上下文?

主要能力

错误分类

技能提供了一张错误分类表,按受众和恢复方式划分:

  • 面向用户:受众为最终用户,恢复方式是引导操作,例如 InvalidEmail、NotFound。
  • 内部:受众为开发者,恢复方式是调试信息,例如 DatabaseError、ParseError。
  • 系统:受众为运维/SRE,恢复方式是监控/告警,例如 ConnectionTimeout、RateLimited。
  • 瞬时:受众为自动化流程,恢复方式是重试,例如 NetworkError、ServiceUnavailable。
  • 永久:受众为人工,恢复方式是调查,例如 ConfigInvalid、DataCorrupted。

思考提示

在设计错误类型之前,技能建议思考以下问题:

  • 谁看到这个错误?最终用户需要友好且可操作的消息;开发者需要详细且可调试的信息;运维需要结构化且可告警的信息。
  • 能否恢复?瞬时错误可带退避重试;可降级错误可使用回退值;永久错误应快速失败并告警。
  • 需要什么上下文?调用链可使用 anyhow::Context;请求 ID 可使用结构化日志;输入数据可作为错误负载。

向上追溯

技能提供向上追溯至领域约束(第 3 层)的指引。例如,对于“应如何处理支付失败?”这一问题,应询问重试的业务规则是什么,检查 domain-fintech(交易要求)和 SLA(可用性要求)。相关追溯包括:重试策略追溯至 domain-,询问可接受的延迟是多少;用户体验追溯至 domain-,询问用户应看到什么消息;合规追溯至 domain-*,询问审计需要记录什么。

向下追溯

技能提供向下追溯至实现(第 1 层)的指引。例如,“需要类型化错误”可追溯至 m06-error-handling(库使用 thiserror)和 m04-zero-cost(Error 枚举设计);“需要错误上下文”可追溯至 m06-error-handling(anyhow::Context)和日志(带字段的 tracing);“需要重试逻辑”可追溯至 m07-concurrency(异步重试模式)以及 tokio-retry、backoff 等 crate。

恢复模式快速参考

技能列出了恢复模式及其适用场景和实现方式:

  • 重试:适用于瞬时故障,实现方式为指数退避。
  • 回退:适用于降级模式,实现方式为缓存/默认值。
  • 熔断:适用于级联故障,实现方式为 failsafe-rs。
  • 超时:适用于慢操作,实现方式为 tokio::time::timeout。
  • 隔离:适用于隔离场景,实现方式为独立线程池。

错误层级示例

技能提供了一个使用 thiserror 的错误枚举示例,将错误分为面向用户(Validation)、瞬时(ServiceUnavailable)和内部(Internal)三类,并实现了 is_retryable 方法判断是否可重试。

重试模式示例

技能提供了一个使用 tokio_retry 的重试函数示例,采用指数退避策略,从 100 毫秒开始,最大延迟 10 秒,最多重试 5 次。

常见错误

技能列出了常见错误及改进建议:对所有错误使用同一类型会导致缺乏可操作性,应按受众分类;重试所有错误会浪费资源,应只重试瞬时错误;无限重试会导致自我 DoS,应设置最大尝试次数和退避;暴露内部错误存在安全风险,应使用用户友好的消息;缺少上下文会导致难以调试,应处处使用 .context()。

反模式

技能列出了反模式及改进建议:字符串错误缺乏结构,应使用 thiserror 类型;对可恢复错误使用 panic! 会导致糟糕的用户体验,应使用带上下文的 Result;忽略错误会导致静默失败,应记录或传播;到处使用 Box 会丢失类型信息,应使用 thiserror;在正常路径中处理错误会影响性能,应尽早验证。

使用方式

该技能以文档形式提供设计指导,包含分类表、思考提示、追溯指引、代码示例和反模式列表。开发者可在设计 Rust 项目的领域错误处理策略时参考这些内容。

适用场景

适用于需要设计领域错误处理策略的 Rust 项目,尤其是在需要按受众和可恢复性对错误进行分类、制定重试或回退策略、以及建立错误层级时。

限制

该技能为设计指导文档,不包含自动化工具或运行时功能。具体实现需结合相关技能(如 m06-error-handling、m07-concurrency、m09-domain)和领域特定技能(domain-*)。