【OpenHarmony/HarmonyOs 】51统一错误处理从散落 catch 到可恢复的 ArkTS 错误体系 本文基于当前项目CloudDBService.ets、LoginPage.ets、Index.ets、ChatPage.ets与ChatDetailPage.ets的真实异常处理展开。项目已经使用try/catch/finally避免页面崩溃也具备 Mock 降级与加载态但错误仍以未知对象、原始字符串和页面级分支分散存在本文给出统一错误模型、分层职责、用户提示与恢复策略。一、为什么 catch 越多错误处理不一定越好当前代码在登录、初始化、查询、订阅和发送消息处都写了 catch。这能阻止异常直接击穿页面却容易形成新的问题同一异常在多层重复打印页面直接展示 SDK message有的失败降级为 Mock有的静默忽略调用方无法判断是否可重试finally虽结束 loading却没有形成明确错误状态未知对象被随意JSON.stringify。统一错误处理的目标不是减少 catch 数量而是明确每一层应该负责什么。二、项目当前的真实模式Cloud DB 服务初始化失败后重新抛出try{awaitAGConnectCloudDB.initialize(context); }catch(err) { hilog.error(0x0000,CloudDBService,Cloud DB Initialization failed: JSON.stringify(err));thrownewError(JSON.stringify(err)); }登录页捕获后把错误字符串直接拼到界面catch(e) { let errStr JSON.stringify(e);this.message getStr(this.currentLang).login_failed : errStr; }聊天列表失败时直接使用 Mockcatch(e) {this.chatList this.getFallbackChatList(); }finally{this.isLoading false; }三种处理各有合理部分但缺少共同语言。三、统一错误模型应该回答什么一个可用的应用错误至少应回答错误属于哪个业务域稳定错误码是什么用户应该看到什么是否可以重试是否允许降级是否需要重新登录内部诊断追踪 ID 是什么原始异常是否保留在受控内存中。四、推荐的错误类型exportenumAppErrorKind{NETWORKNETWORK,AUTHAUTH,DATABASEDATABASE,VALIDATIONVALIDATION,PERMISSIONPERMISSION,NOT_FOUNDNOT_FOUND,CONFLICTCONFLICT,CANCELLEDCANCELLED,UNKNOWNUNKNOWN}exportclassAppErrorextendsError{readonlycode:string;readonlykind:AppErrorKind;readonlyretryable:boolean;readonlyuserMessageKey:string;readonlytraceId:string;constructor(code:string, kind: AppErrorKind, retryable:boolean, userMessageKey:string, traceId:string) {super(code);this.code code;this.kind kind;this.retryable retryable;this.userMessageKey userMessageKey;this.traceId traceId; } }注意示例强调结构具体 API 和构造方式需要结合当前 ArkTS 编译规则验证。五、错误码为什么必须稳定错误 message 可能变化SDK 升级后英文文案变化系统语言变化云端返回字段变化开发者调整提示语。错误码应保持稳定例如AUTH_LOGIN_CANCELLED AUTH_SESSION_EXPIREDCLOUDDB_ZONE_UNAVAILABLECLOUDDB_QUERY_FAILEDCHAT_SEND_FAILED PERMISSION_CAMERA_DENIED VALIDATION_MESSAGE_EMPTY页面根据 code 或 kind 决定行为不依赖脆弱的 message 文本判断。六、分层职责SDK 适配层把 AGC、Cloud DB 与系统 API 的异常转换为AppError。服务层补充业务操作上下文决定是否重试、是否降级但不直接操作 UI。ViewModel 或页面逻辑层把错误映射为加载、空、错误、离线或需登录状态。UI 层展示本地化文案和恢复按钮不解析 SDK 异常对象。日志层只记录安全错误码、阶段与追踪 ID不复制用户数据。七、错误标准化函数推荐所有 catch 首先标准化functionnormalizeError(error:Object, operation:string):AppError{if(errorinstanceofAppError) {returnerror; }returnnewAppError( operation _UNKNOWN, AppErrorKind.UNKNOWN,false,error_unknown, createTraceId() ); }实际适配器应优先识别 SDK 明确错误码未知情况才进入 UNKNOWN。不要通过 message 包含某个英文单词来判断网络、权限或取消。八、用户提示与诊断信息必须分离用户需要的是发生了什么是否影响当前操作下一步可以做什么。工程师需要的是错误码操作阶段追踪 ID耗时重试次数。不能把后者原样拼接到前者。推荐 UI 文案消息发送失败请检查网络后重试。推荐内部日志eventchat_send_failedcodeCHAT_SEND_TIMEOUTtrace7F2Aretry1九、页面状态不能只有 isLoading建议状态至少包含enumLoadPhase {IDLEIDLE, LOADING LOADING, CONTENT CONTENT, EMPTY EMPTY, ERROR ERROR, OFFLINE OFFLINE}这样页面可以区分首次加载失败有旧数据但刷新失败Cloud DB 不可用且已降级真实空数据用户取消会话过期。十、哪些错误适合重试通常可重试临时网络不可用超时服务暂时繁忙订阅中断Zone 初始化竞态。通常不可自动重试参数校验失败权限被用户拒绝登录被用户取消数据不存在业务冲突认证会话失效且需要用户操作。重试策略必须由错误类型驱动而不是任何 catch 都 setTimeout。十一、逐项统一错误处理核验检查项 1AGC 初始化检查目标SDK 异常转换为稳定 AppError。常见反例直接 throw JSON 字符串。推荐动作映射初始化错误码与可重试性。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 2Cloud DB Zone检查目标区分未初始化、打开失败和已关闭。常见反例统一当 unknown。推荐动作建立 ZONE_UNAVAILABLE 等明确代码。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 3登录取消检查目标识别用户主动取消。常见反例显示“登录失败”并自动重试。推荐动作返回 CANCELLED 且不打 error。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 4登录网络错误检查目标提示检查网络并允许重试。常见反例展示 SDK 原始 message。推荐动作映射 AUTH_NETWORK_ERROR。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 5会话过期检查目标清理本地状态并回登录。常见反例无限重试原请求。推荐动作使用 AUTH_SESSION_EXPIRED。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 6游客登录检查目标Cloud DB 失败可降级。常见反例初始化失败阻止游客进入。推荐动作按业务要求标记 fallback。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 7用户同步检查目标同步失败不一定阻止登录。常见反例次要操作失败覆盖主流程成功。推荐动作区分关键与非关键副作用。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 8用户查询检查目标首次失败进入错误态。常见反例无条件展示 Mock 且不提示。推荐动作标记数据来源与重试入口。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 9聊天列表检查目标保留旧数据并提示刷新失败。常见反例catch 后清空内容。推荐动作区分 initial_error 与 refresh_error。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 10消息订阅检查目标建立失败可手动重连。常见反例只 console.error 后静默。推荐动作维护 subscription state。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 11订阅中断检查目标记录断线并退避重连。常见反例每次回调立即无限重订阅。推荐动作设置最大次数和抖动。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 12发送消息检查目标发送失败保留本地失败气泡。常见反例catch 后消息消失。推荐动作使用 sending、sent、failed 状态。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 13重复发送检查目标以客户端消息 ID 幂等。常见反例重试生成新 ID。推荐动作同一操作复用 idempotency key。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 14消息为空检查目标本地校验并阻止请求。常见反例交给 Cloud DB 报错。推荐动作返回 VALIDATION_MESSAGE_EMPTY。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 15附件失败检查目标按选择、读取、上传、发送分阶段。常见反例全部显示“操作失败”。推荐动作建立阶段化错误码。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 16权限拒绝检查目标提示去设置或取消。常见反例当系统异常反复请求。推荐动作使用 PERMISSION_DENIED。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 17路由参数检查目标入口校验类型与必填值。常见反例使用空 targetUid 继续查询。推荐动作返回 ROUTE_PARAM_INVALID。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 18数据不存在检查目标显示空或已删除状态。常见反例当成系统错误。推荐动作使用 NOT_FOUND。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 19并发冲突检查目标提示刷新后重试。常见反例静默覆盖新数据。推荐动作使用 CONFLICT 与版本控制。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 20点赞失败检查目标回滚乐观更新。常见反例UI 数字永久错误。推荐动作保存旧值并按结果恢复。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 21删除失败检查目标恢复被移除的本地项。常见反例先删 UI 后失败无提示。推荐动作使用事务式 UI 状态。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 22心情发布检查目标防止重复点击。常见反例多次并发创建。推荐动作提交期锁定并使用唯一请求 ID。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 23私密日记检查目标权限错误不能降级为公开。常见反例失败后自动改成公开保存。推荐动作安全边界错误禁止降级。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 24搜索超时检查目标保留关键词并允许重试。常见反例清空输入。推荐动作错误状态与输入状态分离。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 25搜索竞态检查目标旧错误不能覆盖新结果。常见反例任意 catch 设置 ERROR。推荐动作校验 requestVersion。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 26分页失败检查目标保留已加载数据和游标。常见反例重置整个列表。推荐动作使用 load_more_error。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 27无更多数据检查目标作为正常结束状态。常见反例记录 error。推荐动作使用 hasMorefalse。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 28空结果检查目标与失败状态明确区分。常见反例空数组统一显示失败。推荐动作建立 EMPTY phase。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 29Mock 降级检查目标用户或测试可识别来源。常见反例伪装为云端成功。推荐动作使用 degradedtrue。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 30缓存回退检查目标展示缓存并提示可能过期。常见反例缓存命中掩盖请求失败。推荐动作记录 stale 状态。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 31加载超时检查目标结束 loading 并提供恢复。常见反例转圈无限持续。推荐动作超时映射为 retryable error。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 32finally检查目标只做无条件清理。常见反例finally 覆盖成功状态。推荐动作状态迁移在 try/catch 内完成。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 33嵌套 try检查目标每层有明确责任。常见反例空 catch 吞掉初始化错误。推荐动作次要错误也应可观测。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 34空 catch检查目标禁止无解释吞异常。常见反例catch (e) {}。推荐动作至少转换、降级或返回状态。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 35重新抛出检查目标保留稳定错误类型。常见反例throw new Error(JSON.stringify(err))。推荐动作throw AppError 或标准化结果。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 36未知类型检查目标安全处理 Object/unknown 来源。常见反例强制 any 后访问字段。推荐动作通过适配器和 instanceof 判断。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 37Error message检查目标仅作内部安全摘要。常见反例把 message 当错误码。推荐动作code 与 message 分离。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 38错误码检查目标全局唯一且稳定。常见反例页面自定义中文字符串。推荐动作域_操作_原因格式。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 39错误类型检查目标覆盖网络、认证、数据库等域。常见反例所有错误都是 UNKNOWN。推荐动作优先使用 SDK code 映射。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 40可重试性检查目标由类型决定。常见反例UI 自己猜测。推荐动作AppError.retryable 明确输出。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 41降级性检查目标安全评估后决定。常见反例所有错误都回退 Mock。推荐动作权限与隐私错误禁止降级。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 42严重级别检查目标区分提示、警告和阻断。常见反例任何失败都弹模态框。推荐动作按影响范围选择 UI。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 43用户文案检查目标本地化且可行动。常见反例显示 JSON 异常。推荐动作使用 userMessageKey。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 44诊断文案检查目标包含 code 与 trace。常见反例与用户提示混在一起。推荐动作只进入安全日志。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 45追踪 ID检查目标每次操作稳定。常见反例使用 UID 作为 trace。推荐动作生成无身份含义的短 ID。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 46日志去重检查目标责任边界只记一次。常见反例服务层和页面层重复 error。推荐动作下层转换上层最终记录。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 47Toast检查目标适合短暂且非阻断错误。常见反例重要错误一闪而过。推荐动作按严重度选择状态区或对话框。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 48错误页检查目标适合首屏无法继续。常见反例局部按钮失败跳整页。推荐动作局部错误局部呈现。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 49内联提示检查目标靠近输入或操作对象。常见反例所有校验都 Toast。推荐动作表单错误绑定字段。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 50重试按钮检查目标只对 retryable 显示。常见反例权限拒绝也显示重试。推荐动作提供去设置等正确动作。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 51取消按钮检查目标用户可退出长流程。常见反例强制等待不可取消请求。推荐动作取消映射为正常状态。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 52防重复检查目标处理中禁用提交。常见反例按钮可连续触发。推荐动作isSubmitting 独立管理。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 53请求版本检查目标只接受最新意图结果。常见反例旧失败覆盖新成功。推荐动作比较单调递增版本。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 54页面销毁检查目标忽略或取消后续回调。常见反例离页后更新 State。推荐动作维护 active 标识或取消句柄。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 55超时控制检查目标每类操作有合理期限。常见反例所有请求共用一个超时。推荐动作登录、查询、上传分别配置。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 56指数退避检查目标临时错误逐步延迟。常见反例固定 100ms 高频重试。推荐动作增加上限与随机抖动。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 57最大重试检查目标存在明确上限。常见反例后台无限循环。推荐动作超限转手动恢复。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 58网络恢复检查目标恢复时触发受控重试。常见反例每个页面同时请求。推荐动作集中协调恢复事件。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 59离线写入检查目标明确队列和冲突策略。常见反例假装已同步成功。推荐动作展示 pending_sync。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 60幂等设计检查目标写操作可安全重放。常见反例重试产生重复数据。推荐动作使用稳定业务 ID。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 61事务边界检查目标关联写入共同成功或补偿。常见反例半成功无处理。推荐动作定义补偿动作。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 62回滚失败检查目标升级错误并保留证据。常见反例继续假装已恢复。推荐动作使用 ROLLBACK_FAILED。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 63数据解析检查目标校验字段完整与类型。常见反例JSON.parse 失败崩溃。推荐动作映射 DATA_INVALID。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 64旧数据兼容检查目标未知枚举有回退。常见反例直接强转模型。推荐动作区分可修复与不可读。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 65本地存储检查目标读写失败可解释。常见反例把 null、空串、损坏混为一类。推荐动作建立 STORAGE 错误域。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 66资源读取检查目标缺失资源在构建或测试发现。常见反例运行时显示空文案。推荐动作错误键纳入校验。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 67国际化键检查目标错误码映射有效 key。常见反例直接把 code 显示给用户。推荐动作缺失时使用通用安全文案。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 68权限状态检查目标区分首次拒绝与永久拒绝。常见反例只显示 denied。推荐动作提供对应恢复路径。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 69相机能力检查目标区分无设备、权限和调用失败。常见反例统一 UNKNOWN。推荐动作系统错误适配到业务域。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 70相册选择检查目标用户取消不是 error。常见反例取消时弹失败。推荐动作使用 CANCELLED 正常结束。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 71文件上传检查目标区分读取、网络和服务失败。常见反例统一“发送失败”。推荐动作阶段化状态支持针对性重试。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 72大文件检查目标本地校验大小。常见反例上传后才报错。推荐动作使用 VALIDATION_FILE_TOO_LARGE。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 73不支持格式检查目标在选择后立即提示。常见反例SDK 抛异常后显示内部信息。推荐动作建立格式校验码。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 74数据库权限检查目标禁止自动改为公开查询。常见反例权限失败后全表查询。推荐动作安全错误必须阻断。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 75数据库索引检查目标识别配置错误并阻断发布。常见反例当网络错误自动重试。推荐动作使用 DATABASE_INDEX_REQUIRED。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 76对象模型检查目标Schema 不匹配有明确诊断。常见反例转换异常只显示 unknown。推荐动作记录模型版本和安全 code。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 77订阅快照检查目标回调错误进入统一通道。常见反例只 console.error。推荐动作触发订阅状态变化。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 78监听释放检查目标释放失败记录 warn。常见反例完全忽略。推荐动作保证生命周期最终一致。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 79窗口加载检查目标加载失败保留错误码。常见反例完整序列化窗口异常。推荐动作能力层标准化。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 80备份恢复检查目标区分版本不兼容与 IO 失败。常见反例一律成功日志。推荐动作失败向系统正确返回。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 81启动守卫检查目标鉴权异常安全回登录。常见反例无限停留 loading。推荐动作设置最终路由状态。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 82关键与非关键检查目标主流程与附加同步分开。常见反例头像同步失败导致登录失败。推荐动作定义 operation criticality。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 83批量操作检查目标返回逐项结果或整体策略。常见反例首个失败后状态未知。推荐动作明确 all-or-nothing。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 84部分成功检查目标UI 清楚展示成功与失败项。常见反例统一提示成功。推荐动作使用 PartialResult 模型。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 85错误聚合检查目标多个并发失败保留主因。常见反例只显示最后一个错误。推荐动作按优先级选择主错误。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 86错误优先级检查目标认证和权限高于普通网络提示。常见反例Toast 相互覆盖。推荐动作集中调度提示。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 87全局处理器检查目标只兜底未处理异常。常见反例取代所有局部业务处理。推荐动作局部恢复优先全局防崩溃。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 88未捕获异常检查目标安全上报并终止危险流程。常见反例继续使用未知状态。推荐动作清理关键状态后提示重启。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 89Promise 拒绝检查目标所有异步入口显式处理。常见反例调用 async 不 await。推荐动作返回 Promise 并在边界捕获。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 90回调错误检查目标转换为同一错误模型。常见反例Object 类型随处传递。推荐动作在 SDK 回调边界适配。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 91构建检查检查目标错误类型符合 ArkTS 规则。常见反例依赖 any 与对象字面量推断。推荐动作明确接口、类和返回类型。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 92单元测试检查目标覆盖每个错误映射。常见反例只测成功路径。推荐动作使用表驱动错误码用例。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 93恢复测试检查目标验证重试后状态闭合。常见反例只验证出现错误提示。推荐动作覆盖失败到成功迁移。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 94弱网测试检查目标覆盖超时、断网和切网。常见反例只在稳定 Wi-Fi 测试。推荐动作注入延迟和失败。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 95竞态测试检查目标旧成功和旧失败都被丢弃。常见反例只测响应顺序正常。推荐动作反转返回时序。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 96生命周期测试检查目标离页后不更新 UI。常见反例只看无崩溃。推荐动作检查监听和任务释放。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 97安全测试检查目标用户文案无内部信息。常见反例错误页显示堆栈。推荐动作扫描 code、URL、token 模式。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 98可访问性检查目标错误被读屏感知。常见反例仅红色边框。推荐动作增加文本和状态语义。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 99统计指标检查目标按稳定 code 聚合错误率。常见反例按 message 分组。推荐动作监控 code、operation、version。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 100告警阈值检查目标关键错误有明确阈值。常见反例任何单次错误都告警。推荐动作结合比例、时间窗和影响用户数。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 101灰度发布检查目标比较新旧错误分布。常见反例上线后才发现映射遗漏。推荐动作灰度观察 UNKNOWN 占比。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 102UNKNOWN 治理检查目标持续降低未知错误比例。常见反例UNKNOWN 成为永久垃圾桶。推荐动作定期分析并补充适配。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 103错误文档检查目标code 含义和恢复动作一致。常见反例文档与代码两套命名。推荐动作从代码枚举生成清单。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 104代码评审检查目标检查 catch 是否履行职责。常见反例看到 catch 就认为安全。推荐动作审查转换、状态、提示、日志。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 105发布检查检查目标P0/P1 错误路径已验证。常见反例只测 happy path。推荐动作按业务关键度建立矩阵。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。检查项 106最终标准检查目标错误可识别、可解释、可恢复、可观测。常见反例catch 后不崩溃就算完成。推荐动作形成端到端闭环。验证证据错误码、页面状态、用户提示、日志事件与恢复结果。通过标准调用方无需解析 SDK 原始异常即可做出正确决策。十二、推荐改造路线阶段 1盘点检索所有 catch、throw、Promise 拒绝、回调错误和直接展示的异常字符串。阶段 2建模建立AppErrorKind、稳定 code、retryable、userMessageKey 与 traceId。阶段 3适配先为 AGC Auth、Cloud DB、系统权限和文件选择器建立错误适配器。阶段 4页面状态把isLoading message升级为 IDLE、LOADING、CONTENT、EMPTY、ERROR、OFFLINE。阶段 5恢复为可重试错误接入退避、手动重试、幂等和竞态隔离。阶段 6观测日志只记录安全 code、operation 与 trace并统计 UNKNOWN 比例。阶段 7测试覆盖取消、权限、断网、超时、部分成功、离页回调与恢复成功。十三、常见反模式速查反模式结果正确方向throw new Error(JSON.stringify(err))类型与语义丢失转换为稳定 AppErrorUI 展示 SDK message内部信息泄露且不可本地化userMessageKey所有错误都自动重试重复请求与糟糕体验retryable 驱动catch 后无状态用户看见静默失败明确 ERROR 或 DEGRADED空 catch故障不可观测转换、降级或传播多层重复 error 日志噪声与重复告警责任边界记录一次取消也算失败用户被错误责备CANCELLED 正常结束Mock 冒充云端成功数据来源不透明degraded 状态只用 isLoading空、错、离线混在一起明确页面状态机重试生成新业务 ID重复写入幂等键十四、总结统一错误处理不是创建一个工具类后把所有 catch 搬进去。真正完整的体系应贯穿SDK 异常标准化服务层业务语义补充页面状态机本地化且可行动的用户提示安全日志和稳定错误指标重试、降级、回滚与幂等恢复。当调用方只依赖稳定错误码和明确能力而不再猜测 SDK message 时错误才从“偶发异常”变成了可以设计、测试和治理的产品状态。