升级 HarmonyOS 7 只修编译错误还不够：API 26 行为变更审计清单怎么做

不才难以繁此生

67人浏览 · 2026-09-21 23:27:03

不才难以繁此生 · 2026-09-21 23:27:03 发布

升级 HarmonyOS 7 只修编译错误还不够：API 26 行为变更审计清单怎么做

升级到 HarmonyOS 7 / API 26 后，编译器报错反而是最好处理的一类问题：位置明确、修改后能立即反馈。真正危险的是代码仍然编译通过，但默认值、布局时机、回调顺序或边界行为已经变化。本文给出一套“找变更、定位调用点、复现旧行为、验证新结果”的升级审计方法。

API 26 升级差异审计从变更到验证

先把问题变成可验证的证据

官方 release notes 与 API diff 用于确认变更事实，工程扫描用于找到受影响调用点，最小复现用于确认行为差异，回归用例用于证明业务结果。四层证据缺一层，都可能把“没有报错”误认为“已经适配”。

签名变化会触发编译错误，行为变化往往不会。
同一个 API 在不同页面可能依赖不同默认值，不能只修第一个调用点。
升级清单要记录“已验证证据”，而不只是“已修改文件”。

案例一：接口签名没变，但默认布局结果改变

为每条官方变更建立唯一键，再用调用点清单计算覆盖率。下面的策略可以阻止“找到三处，只改两处”被标记为完成。

interface ChangeItem { key: string; callSites: string[]; verified: string[] }
function uncovered(item: ChangeItem): string[] {
  const done = new Set(item.verified)
  return item.callSites.filter(site => !done.has(site))
}
const item = { key: 'ARKUI-DEFAULT-001', callSites: ['Home.ets:31', 'Detail.ets:44', 'Edit.ets:22'], verified: ['Home.ets:31', 'Edit.ets:22'] }
console.assert(uncovered(item)[0] === 'Detail.ets:44')

清单会明确显示尚未验证的调用点，不能用“主要页面改好了”掩盖遗漏。

案例二：回调顺序变化只在快速返回页面时出现

普通点击路径看不出问题，就把事件序列记录成状态机输入，覆盖重复回调、迟到回调和页面已销毁三种边界。

type PagePhase = 'active' | 'leaving' | 'destroyed'
type Event = 'request' | 'result' | 'leave' | 'destroy'
function acceptResult(phase: PagePhase, event: Event): boolean {
  return event === 'result' && phase === 'active'
}
console.assert(acceptResult('active', 'result'))
console.assert(!acceptResult('leaving', 'result'))
console.assert(!acceptResult('destroyed', 'result'))

无论 API 26 下回调早到还是迟到，页面销毁后都不会继续更新 UI。系统回调顺序仍需用真机日志确认。

现象、证据与动作

现象	先看什么	下一步动作
编译报错	API 签名与类型差异	按官方定义修改并编译
编译通过但界面变化	默认值与行为变更	建立最小复现
只在快速操作时异常	回调顺序和生命周期	增加事件序列用例
修完又在别页复发	调用点覆盖率	全量扫描并逐项验收

三种做法怎么选

只修编译错误最快，却覆盖不了运行语义；人工逐页点测直观，但难以证明没有遗漏；“官方 diff + 调用点扫描 + 最小复现 + 回归证据”稍慢，却能形成可复查的升级记录，适合正式版本。

能否封装和复用

可以把变更项存成结构化清单，字段包括官方来源、变更类型、调用点、复现步骤、修复提交和验证证据。后续 API 27 升级直接复用流程，而不是重新发明检查表。

最容易踩的三个误区

把 IDE 不再报红当成升级完成，没有检查默认值、回调顺序与边界语义。
只读一篇版本摘要，没有回到具体模块的 API diff 和行为变更说明。
把“已修改”写进清单，却没有修复前复现、修复后日志和受影响调用点覆盖率。

如何避免问题再次出现

升级分支建立后先冻结一份官方变更来源清单，并记录抓取日期。每条变更分配唯一编号，扫描调用点后才允许进入修改阶段；修复时先保留旧行为的最小复现，再补新行为断言。合并前由另一名评审者抽查官方条目、代码位置和验证证据是否一一对应，避免清单只完成了形式。

本文验证到哪一层

本地断言验证了调用点覆盖率和迟到回调拦截。本文没有声称已对具体 API 26 行为在本机编译或真机复现；实际项目应把官方变更条目替换成项目真实调用点并补齐设备证据。

本文中的纯策略代码已在宿主 JavaScript 环境执行断言，用来验证计算、状态转换、排序或清单差异。当前本机仅有 API 24 SDK，且没有 HDC 真机，因此本文不把宿主断言描述为 API 26 工程编译或真机验证。涉及系统接口、设备形态、性能 Trace 或上架审核的结果，仍需在对应 API 26 SDK、设备和 AppGallery Connect 环境中完成端到端验收。