SuperAPI AI 工具集

error-handling

编程与开发

查看项目

更新于 11-11 23:15

技能介绍

用途

本技能用于指导 React Native 应用中的错误处理设计,聚焦四类问题:错误边界(error boundaries)、API 失败界面、重试流程以及全局处理器。它适合在以下场景使用:

  • 为某个功能添加错误边界,或在功能失败时提供回退界面;
  • 设计 API 调用、mutation 或原生调用失败时用户看到的内容;
  • 添加重试,或判断某个请求不应重试;
  • 审查一个可能失败、但目前只处理正常路径的屏幕。

需要注意边界:将失败上报到崩溃或分析工具属于可观测性(observability)范畴;适用于每次渲染的崩溃规则属于 critical-rules。这些内容不在本技能范围内。

适用性与环境

  • 平台:iOS 与 Android。
  • React Native:0.76 及以上版本,默认采用新架构互操作(New Architecture interop),除非某个清单项另有说明。

严重程度

  • 合并阻断(Merge-blocking):本次改动新增的功能可能在渲染期抛错并导致应用崩溃;或本次改动新增的提交操作会吞掉错误。
  • 应修复(Should-fix):错误文案与重试措辞问题。

主要能力与指导要点

错误隔离

  • 应用根节点以及每个可能独立失败的功能都应被错误边界包裹。
  • 回退界面不得发起网络请求,也不得依赖刚刚抛错的状态。
  • 某个功能失败时,应禁用或替换该功能,同时保持应用其余部分可用。
  • 事件处理和异步工作中的错误需要在其发生处捕获,因为错误边界捕获不到它们。

资料给出的示例对比:

export default function App() {
  return <Navigator />;
}

应改为:

export default function App() {
  return (
    <ErrorBoundary fallback={<AppCrashScreen />}>
      <Navigator />
    </ErrorBoundary>
  );
}

用户所见内容

  • 服务端数据的加载、空和错误状态由 state-and-data 负责。
  • 错误文案应说明发生了什么以及下一步该做什么,而不是直接展示服务端或原生的原始消息。
  • 已被捕获且用户可重试的错误,不应同时以全屏崩溃的形式展示。

重试

  • 重试应是显式按钮或一次有界尝试,而不是无限循环。
  • 网络恢复后重试 POST 请求由 state-and-data 负责。
  • 当服务端支持幂等键时,重试应使用与原始尝试相同的幂等键。

反模式

资料列出三种反模式及其风险与修复方式:

  • 空 catch:用户会对失败的操作看到加载指示或成功状态。修复方式是暴露错误状态并记录非敏感原因。
  • 在回退界面中获取数据:回退界面会抛错并替换自身。修复方式是使用带重试操作的静态回退界面。
  • 每次后台刷新失败都弹窗:会因用户未主动发起的失败而打断用户。修复方式是在拥有该数据的屏幕上内联显示错误。

常见陷阱

  • 错误边界只捕获渲染错误,不捕获 onPress 处理器、定时器或被拒绝的 Promise。
  • 全局未处理拒绝处理器只是上报兜底,不能替代发起工作的那个屏幕上的错误状态。
  • 每次渲染都重置边界会重新挂载已损坏的组件树,并可能造成循环。

限制

资料未提供该技能的收费、价格、具体安装命令或更多平台支持信息;关于崩溃上报与分析工具集成、通用渲染崩溃规则的详细规则,资料指向可观测性与 critical-rules 领域,但未在本页展开。