SuperAPI AI 工具集

error-handling-typed-results

编程与开发

查看项目

更新于 10-18 18:01

技能介绍

该技能用于在 React Native(含 Expo Router)项目中建立一套类型化错误处理主干,目标是让预期失败以类型化的 Result 值传递,让每个调用方被类型系统强制穷尽处理,只有真正的程序缺陷才抛出异常。

用途与核心思路:把“预期失败”定义为正确程序中可能发生的情况,例如未找到、离线、存储已满、输入非法、被取消、数据行损坏,这些都必须返回 Result<T, F>;而违反不变量的情况才抛出 new Error(message, { cause })。原因是异常形式的预期失败要么让处理函数崩溃,要么被调用方吞掉。

主要能力与规则:

  1. 单一 Result 类型:来自 src/core/result.ts,形如 { ok: true, value } | { ok: false, error },附带 ok、err、attempt、attemptAsync,禁止第二个 Result/Either 或第三方 result 库。
  2. 失败即类型化种类:失败是 kebab-case 的 kind 加类型化参数,例如 err({ kind: 'task-title-taken', title }),禁止 err('...')、err(new Error())、Result<T, string | Error | unknown> 或在失败中夹带 message。
  3. 边界转换一次:适配器、仓库、ApiClient、解析器捕获供应商错误并返回边界的失败族,适配器内不允许 await 逃出 try/catch 或 attemptAsync。
  4. 每个 catch 必须映射、带兜底记录或带 { cause } 重抛;仅控制台输出、仅注释或 .catch(() => undefined) 视为不合格;纯装饰性副作用可在适配器内以 // best-effort: <原因> 注释忽略。
  5. 记录意外错误时保留原始错误,预期失败不记录。
  6. 失败必须用 switch 或 Record<F['kind'], ...> 穷尽处理,绝不丢弃 Result;返回 Result 的调用不能是裸语句、forEach 回调体或 on* 箭头函数体。
  7. UI 按键选文案,绝不展示 error.message;每个失败族一个消息表,键存在于所有 locale。
  8. 全局错误网:由根布局首个 app 导入安装,组合根连接错误日志,所有构建启用 Hermes 拒绝跟踪,缓冲直到连接,sink 在 try/catch 内调用。
  9. 根路由导出 ErrorBoundary,记录错误并提供唯一出路,不自动重试、不在 effect 或定时器中跳转,兜底界面保持简单且不读取无默认值的 context。
  10. 错误路径绝不销毁数据:catch 内禁止 delete、drop、clear、truncate、reset;坏记录隔离,其余照常加载;比应用更新的数据保持原样。
  11. 用户写入失败保留输入并提示,模型只在 ok 后清空表单,写入不允许 fire-and-forget。

使用方式:工作流分为机制选择、补全 Result 模块、设计失败族、边界转换、处理与展示、保护数据、安装全局网、添加根错误边界、测试、运行检查器、真机验证。检查器为两个零依赖脚本,需在仓库根运行,直到输出 RESULT: PASS。完成定义包括 typecheck、eslint --max-warnings 0、jest --ci 通过。技能附带 references 下的多份参考文档、templates 下的 Result 模块、错误网、崩溃恢复组件及各自测试,以及 examples 下的任务失败族、仓库、表单模型与触觉适配器示例。

适用场景:需要统一错误词汇、避免吞错、防止错误路径丢数据、要求国际化错误提示、希望在编译期发现未处理失败种类的 React Native 项目。

限制:技能自身不提供产品功能、收费或平台信息;其规则依赖特定目录结构与模板文件,部分检查在根布局尚未创建时允许 SKIP;真机发布构建验证需手工完成。