I18n 错误码从 string 变成 number 后，最先坏的往往不是编译，而是埋点和重试规则

I18n 错误码从 string 变成 number 后最先坏的往往不是编译而是埋点和重试规则国际化接口失败后页面仍能捕获异常但“参数错误”突然全部进入未知错误监控面板也多出一组新的数字维度。代码没有崩是因为旧判断写成 error.code 401而 HarmonyOS 7 将部分新增 I18n 接口的错误码类型从 string 调整为 number。类型变化会同时击中分支判断、序列化、指标聚合和重试策略。先做兼容矩阵关注点正确理解容易误判边界读取接受 unknown先确认 code 的真实类型业务语义映射到项目稳定错误不让页面比较平台数字监控维度统一序列化格式迁移期保留原始类型字段这张表的作用不是替代官方接口文档而是把平台边界翻译成项目可以执行的判断。升级适配先确认触发条件再决定代码改动没有进入触发条件的模块不应为了“看起来统一”被一起重写。旧环境与新环境的分叉兼容层不要简单调用 Number(code)因为空字符串、对象和非十进制文本会制造新错误。只接受有限的数字或纯数字字符串再映射成项目内部语义。type StableError invalid-argument|not-supported|unknown; function normalizeCode(code: unknown): number | null { if (typeof code number Number.isInteger(code)) return code; if (typeof code string /^\d$/.test(code)) return Number(code); return null; } function classify(code: unknown): StableError { const value normalizeCode(code); return value 401 ? invalid-argument : value 801 ? not-supported : unknown; } if (classify(401) ! invalid-argument || normalizeCode() ! null) throw new Error(错误码归一化失败);示例故意把平台调用外面的决策抽成纯函数一方面能在没有设备时先验证分支另一方面能清楚标记哪些结论仍需 API 26 编译和真机证据。错误码不再只是字符串埋点系统常把 code 当字符串维度。迁移期应同时记录 normalizedCode 和 sourceType观察旧包、新包是否还有混合输入等覆盖率稳定后再删除兼容逻辑。function metric(code: unknown) { return { normalizedCode: normalizeCode(code) ?? -1, sourceType: typeof code }; } const m metric(401); if (m.normalizedCode ! 401 || m.sourceType ! number) throw new Error(指标字段异常);真实工程还要把超时、重复回调、前后台切换和版本回退纳入测试。只跑一次成功流程无法证明升级后的边界已经被正确处理。发布前验证表最稳的方案是在 Kit 调用边界统一错误不让 UI、领域层和埋点各自兼容一次。重试必须建立在明确可恢复错误白名单上不能因为 code 解析失败就默认重试。建议把适配封装成“平台边界层 稳定业务语义 页面展示”三段。平台变化只修改第一段业务语义通过枚举或结果对象表达页面不直接比较底层错误码、权限字符串或系统版本。这样既能复用也能在下一次版本升级时快速定位。发布前检查清单官方变更是否真的作用于当前 target、应用模型与产品品类。两个案例是否分别覆盖成功路径和容易误判的失败路径。代码中的常量、权限和错误码是否来自当前接口文档而不是旧博客。降级方案是否保持数据正确、交互可理解并且不会扩大权限。目标设备验证结果是否与宿主逻辑测试分开记录。复现与对照怎么做先准备一组最小输入只保留本文讨论的一个变化点再准备一组接近生产的组合输入加入页面切换、重复调用、取消或权限拒绝。两组输入都应在升级前后各跑一次记录“触发条件、决策结果、平台返回、最终状态”四列。若旧版本无法复现也要留下原因不能拿新版本的一次成功反推兼容性。对照测试至少包含三类第一类验证正常路径第二类故意制造边界输入第三类验证降级后数据是否仍然正确。性能相关场景还要固定图片尺寸、调用次数或设备状态避免把环境波动误判为接口变化。遇到结果不一致时先缩小到最小样本再回到完整流程验证不能只修改 UI 文案掩盖底层差异。如果项目同时维护多个系统版本测试报告还应标出兼容分支何时启用、何时可以删除。临时分支没有退出条件往往会在下一次升级中变成新的故障源。建议把删除条件写成可核对的版本覆盖率和线上异常率而不是一句“后续再清理”。证据边界本文依据华为开发者官网 2026 年 9 月更新的 HarmonyOS 7API 26Release 行为变更说明以及 2026 年 8 月更新的 Beta1 行为变更说明整理。文中的纯 TypeScript 判定函数已在宿主 Node.js 环境跑过断言用来验证状态分支ArkTS、权限、签名和系统组件片段仍需在 API 26 SDK、目标设备与正式签名条件下完成编译和真机验收。本文不把宿主测试写成真机结论。建议保存的验收记录系统版本、targetSdkVersion、应用模型和签名类型。触发输入、接口返回、错误码与最终页面状态。成功路径、拒绝路径、取消路径和重复调用路径。升级前后对照结果以及是否启用了临时兼容分支。不在日志中保存完整账号、文件路径、媒体 URI 或设备敏感信息。官方资料HarmonyOS 7 API 26 Release 针对所有应用的行为变更HarmonyOS 7 API 26 Beta1 针对所有应用的行为变更