升级 API 26 后流量统计全失败：GET_NETWORK_STATS 权限迁移清单

升级目标版本后，设置页的“本月图片流量”全部变成 0。接口错误被 catch 后统一返回空数组，监控只看到业务结果为 0，无法区分没有流量、缺权限还是连接对象已经注销。

本文交付：一个 NetworkStatsGuard、module.json5 迁移片段、权限/生命周期错误矩阵，以及用户可理解的降级显示。。

复现与验证

1. 升级 target API 后保留一份未声明权限的对照包。
2. 分别执行统计查询与 NetConnection.unregister。
3. 记录权限声明、运行时检查、错误码、统计区间和对象 ID。
4. 对照平台统计、本地估算与不可用三种 UI。
5. 确认空结果只有在查询成功且区间确实无流量时出现。

官方依据与版本边界

官方变更页：https://developer.huawei.com/consumer/cn/doc/doccenter-release-notes/js-apidiff-networkkit-7003

1. Network Kit 的流量统计相关能力在 API 26 标注 GET_NETWORK_STATS 权限。
2. 权限声明与运行时能力检测要同时存在。
3. NetConnection.unregister 增加错误码 201。
4. 失败日志要区分权限、对象生命周期和统计区间。

本文依据 HarmonyOS 7.0.0 Release（API 26）官方变更说明梳理接口，并对状态模型、分支选择和异常映射做了宿主侧 TypeScript 测试。当前本机 SDK 为 API 24，且没有连接 HDC 设备，因此不把示例描述为 API 26 编译通过、真机性能数据或上架审核结论。接入前请在 API 26 工程中按文末清单完成编译、设备与回归验证。

可复用的 ArkTS 集成片段

// module.json5
+{
+  "module": {
+    "requestPermissions": [
+      { "name": "ohos.permission.GET_NETWORK_STATS" }
+    ]
+  }
+}
+
+type StatsResult =
+  | { kind: 'platform'; bytes: number }
+  | { kind: 'estimated'; bytes: number; reason: string }
+  | { kind: 'unavailable'; reason: string }
+
+export async function readStats(fallbackBytes: number): Promise<StatsResult> {
+  try {
+    const bytes = await queryPlatformNetworkStats()
+    return { kind: 'platform', bytes }
+  } catch (error) {
+    const code = (error as BusinessError).code
+    if (code === 201) return { kind: 'estimated', bytes: fallbackBytes, reason: 'permission-or-lifecycle' }
+    return { kind: 'unavailable', reason: 'network-stats-error-' + code }
+  }
+}

代码刻意把平台调用和业务状态分开：平台返回什么就记录什么，页面只消费稳定状态。接入时还应补齐项目的日志域、错误码类型和生命周期释放。

两种行为不同的案例

案例一：月度图片流量看板

缺权限时显示“当前版本无法读取统计”，不把失败伪装成 0 MB。

案例二：节省流量模式

统计不可用时回退到本地请求计数，只影响估算精度，不阻断图片加载。

图中的每条箭头都应对应一条可查询日志：输入、平台调用、状态映射、UI 或降级结果。只有 UI 变化而没有中间证据，后续仍然难以区分接口失败和页面逻辑错误。

取舍与落地清单

把所有错误降级为 0 能让页面“永不报错”，代价是统计语义失真。显式的 platform、estimated、unavailable 三态会增加 UI 分支，却能避免运营和用户依据错误数据做判断。

• 已用 API 26 工程编译，并记录 SDK 与设备版本
• 已覆盖“月度图片流量看板”和“节省流量模式”两类行为
• 已记录成功、失败、降级三条路径的输入与结果
• 已核对监听、对象或任务的释放与幂等行为
• 已把本文宿主测试替换为项目自己的真机证据

小结

一个 NetworkStatsGuard、module.json5 迁移片段、权限/生命周期错误矩阵，以及用户可理解的降级显示。。建议先在最小页面复现，再接入完整“中式美食”流程；先证明状态链正确，再谈动画、缓存或埋点优化。