用途
本技能用于指导 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 领域,但未在本页展开。