SuperAPI AI 工具集

error-handling

编程与开发

查看项目

更新于 10-15 21:38

技能介绍

用途:该技能负责在抛出异常与 Result 值之间划定边界,并正确消费 Result。它可与 define-errors(变体设计)、logging(诊断)、query-layer(RPC 呈现)和 hono(响应 API)组合使用。

主要能力:以官方 wellcrafted-dev/wellcrafted 源码与测试为依据。先确定契约:调用方接收 Result<T, E> 时用 trySync/tryAsync 适配抛异常操作;失败有合法回退时在 catch 中返回 Ok(fallback);失败需作为数据传播时返回类型化工厂结果;仅有已知外部失败转为 Err,未知异常重新抛出;周围 API 基于异常时保留其抛出契约;清理在成功、失败、取消或提前返回时都要执行则用 finally。同步操作用 trySync,返回 Promise 的用 tryAsync。

使用方式:defineErrors 工厂已返回 Err(...),将原始 cause 传入工厂,由工厂组合消息,不要在 catch 边界使用原始 Err(cause)。跨故意抛出边界时,用 unwrap(来自 wellcrafted/result)在周围 API 已抛出的通道处解包。消费每个可能的 Err 分支:解构后 error 是原始 E,应返回 Err(error);若保留整个 Result 则原样返回;error !== null 是可靠判别式,绝不构造 Err(null) 或 Err(undefined)。tryAsync 返回 Promise,需明确其归属:本函数检查 Result 时 await;调用方拥有 Promise<Result<...>> 时 return tryAsync(...);不要用裸 void tryAsync(...)。UI 中丢弃前先附加呈现,如 void save().then((result) => toastOnError(result, 'Save failed'))。需要时阅读 references/wrapping-boundaries.md、references/toast-on-error.md、references/http-boundaries.md。

限制:保留原生 try-catch 的场合包括 finally 负责清理、生成器需 yield 失败、框架边界将异常直接转换为响应形状、捕获一个已知异常并重抛其余、周围公共 API 故意抛出。不要把未知编程错误转成通用领域失败。未提供安装命令、收费或平台信息。