SuperAPI AI 工具集

error-handling

编程与开发

查看项目

更新于 10-26 10:19

技能介绍

错误处理技能规定了 React Native ExecuTorch 库中错误的抛出、捕获与分类方式,适用于在库的任意位置(TypeScript、worklet、C++/JSI)处理错误,或新增错误码时参考。

核心原则:库抛出的每个失败都携带机器可读的错误码,调用方依据错误码分支处理;消息文本面向人类,可能在任何版本中改写,绝不能让控制流依赖消息内容,禁止对 e.message 使用正则匹配。

来源与同步:src/core/error.ts 是事实来源,cpp/core/error.h 由人工镜像维护,与其他 TS/JSI 接口(DType 定义、schema 类型、宿主对象接口)的镜像方式一致,均非代码生成。新增错误码必须在两个文件中同时添加。

抛出:统一使用工厂函数 RnExecuTorchError(从 core/error 导入),可在包括 worklet 在内的所有位置使用。它是函数而非类,因为 worklet 运行在独立的 JavaScript 运行时中,类实例跨运行时传递时无法保留类标识或原型链;工厂返回带 name、code 及可选 etRuntimeErrorCode 的普通 Error,能完整跨越所有边界。消息写法需与代码库一致:以函数名作前缀并包含出错的值。

捕获:isRnExecuTorchError(err, code?) 用于类型收窄,可选传入错误码从而省去二次比较。它采用鸭子类型判定并标记为 worklet,可在两种运行时及跨 JSI 边界的值上使用。

错误码集合:LOAD_FAILED、EXECUTION_FAILED、SCHEMA_MISMATCH、INVALID_ARGUMENT、INVALID_STATE、RESOURCE_DISPOSED、RESOURCE_BUSY、DOWNLOAD_FAILED、DOWNLOAD_ABORTED、UNKNOWN。集合刻意保持粗粒度,只有应用能真正据此采取不同恢复动作(重试下载、等待忙资源、重建已释放资源)时才值得新增独立错误码;其余情况仅用于崩溃报告分组,细节写入消息。不得为特定子系统(如分词器失败归入 EXECUTION_FAILED 或 LOAD_FAILED)或调用方错误变体新增代码。新增时需修改 src/core/error.ts 中的 VALID_ERROR_CODES,并在 cpp/core/error.h 的 FOR_ALL_RNEXECUTORCH_ERROR_CODES 中加一行,X-macro 列表会同时展开为枚举、字符串映射和工厂函数,防止三者漂移。

C++/JSI 规则:禁止在库代码中抛 jsi::JSError,须通过工厂抛出 RnExecuTorchException;guarded 是唯一将异常转为 JavaScript 值的位置。每个宿主函数注册必须用 error::guarded(...) 包裹,否则错误码会丢失,包括 VisionCamera 帧处理器使用的同步 worklet 路径(无 wrapAsync 回退)。每个错误码对应一个工厂,抛出点只需命名错误码。头文件包含与命名空间别名须放在文件作用域,绝不能置于平台条件编译分支内。工厂可选第二参数为 executorch::runtime::Error,会以 etRuntimeErrorCode 传到 JS 用于诊断,仅在失败确实来自 ExecuTorch 运行时传入。guard 会让已存在的 jsi::JSError 原样通过,不重写应用自身回调抛出的错误。

示例应用:apps/ 下的错误处理保持原样,作为测试场应直接暴露原始错误(e.message、String(e)),而非转换为友好文案。

禁止事项:不得基于消息文本分支;不得在库代码中抛裸 Error 或 jsi::JSError;不得将 RnExecuTorchError 改为类;不得为应用无法差异化恢复的失败新增错误码;不得用代码生成器镜像 TS 错误码;不得保留过时的 @throws 注释。

验证清单:新增或修改错误处理时,需确认所有抛错点使用对应工厂、未引入原始异常类型、所有 createFromHostFunction 注册均被 guarded 包裹、命名空间别名在 extensions::* 中存在而在 core::* 中省略、头文件包含与别名位于文件作用域、catch 处使用 isRnExecuTorchError(e, 'CODE')、@throws 注释标明异常与错误码、新增错误码有明确恢复路径理由并同步两个文件、apps/ 中的错误处理保持原样。