HarmonyOS 7.0 碰一碰参数校验：来源可信、页面落点和失败提示怎么补齐
这篇只讲一个点：碰一碰深链参数校验。版本边界先说清楚，下面的写法面向 HarmonyOS 7.0 / API 26。老工程不要直接复制，先确认 DevEco Studio、SDK、真机系统和模拟器镜像是否已经切到同一套版本。
这个问题为什么值得单独写
碰一碰入口很短，参数链路却不能短。来源、目标页、参数版本、失败提示都要校验，不然用户碰完之后可能打开错页面，或者打开了但没有上下文。
我现在更倾向于把这种问题拆成一个独立小实验，而不是直接塞进大项目里调。原因很现实：大页面里变量太多，状态、路由、权限、资源加载、设备形态混在一起，最后很难判断到底是哪一层出了问题。
复现场景一：参数缺少页面 ID，应用打开后只能停在首页
先做一个最小页面，只保留一个入口、一个状态变化、一个观察结果。连续触发两次，再切到后台回来。如果这个小页面都不稳定，就不要往复杂页面里搬。
复现场景二：旧版本参数进入新页面，字段名对不上
第二个场景要模拟真实使用：切换窗口、旋转屏幕、折叠展开、弱网恢复、后台再进入。很多 HarmonyOS 问题不是第一次点击就出现，而是在状态恢复和资源重新绑定时才暴露。
最小 Demo
interfaceTouchPayload{source?:stringpage?:stringversion?:number}functionvalidateTouchPayload(p:TouchPayload){if(p.source!=='trusted-device')return{ok:false,reason:'source_invalid'}if(!p.page)return{ok:false,reason:'page_missing'}if((p.version??0)<2)return{ok:false,reason:'version_too_old'}return{ok:true,page:p.page}}这段 Demo 的重点不是代码多，而是验证路径清楚：先让状态变化可见，再把异常兜底补上，最后把日志打到能定位问题的程度。只要这个小实验能稳定复现和修复，后面放到业务页面里才有意义。
三种处理方式对比
| 做法 | 适合什么情况 | 问题 |
|---|---|---|
| 继续沿用旧写法 | 旧页面短期兼容 | 遇到 7.0 新能力边界时不好排查 |
| 页面里临时判断 | 快速验证 | 代码分散，后面容易重复踩坑 |
| 抽成工具函数或组件 | 多页面、多设备、多状态复用 | 前期要把输入输出设计清楚 |
我会选第三种。页面只负责展示，能力判断、版本边界、降级策略放到单独函数或组件里。后面设备形态、系统版本、审核要求变化时，改一个地方就够了。
检查清单
- SDK 和设备系统都确认是 HarmonyOS 7.0 / API 26。
- 至少跑通上面两个复现场景。
- 能看到成功、失败、降级三类日志。
- 页面切到后台再回来，状态不能丢。
- 如果涉及权限或跨设备能力，要准备无权限、弱网、设备不可用三种兜底。
进一步扩展：不要只验证“能跑”
如果要把这个能力真正放到线上，我会再加三类验证：
1. 版本边界验证
同一段代码在 HarmonyOS 5.0、6.0、7.0 上的表现不一定一致。文章里的 Demo 面向 HarmonyOS 7.0 / API 26，所以验证时要把 API level 打进日志。只要发现设备版本低于 26，就不要继续走完整能力路径，而是进入降级逻辑。
2. 设备形态验证
HarmonyOS 的麻烦点在于设备形态多：手机、折叠屏、平板、鸿蒙电脑、穿戴设备都可能带来不同窗口尺寸和交互节奏。只在普通手机竖屏跑通，不代表多设备场景也稳。
3. 异步结果验证
很多问题来自旧请求覆盖新状态。比如用户连续点击两次，第一次请求慢一点回来，如果没有 requestId 或版本号保护，就会把第二次的正确结果覆盖掉。这个问题在卡片刷新、智能体多轮对话、跨设备流转里都很常见。
可以把验证日志统一成下面这样：
interfaceVerifyLog{feature:stringapiLevel:numberscene:stringmode:'full'|'fallback'|'blocked'reason:stringrequestId:number}functionbuildVerifyLog(log:VerifyLog):string{return['feature='+log.feature,'api='+log.apiLevel,'scene='+log.scene,'mode='+log.mode,'reason='+log.reason,'requestId='+log.requestId].join(' | ')}我建议每篇 HarmonyOS 7.0 相关代码都至少保留这种日志。它不影响业务逻辑，但排查问题时非常直接：先看 API，再看场景，再看为什么降级或阻断。
可复用封装
如果一个工程里有多个 7.0 能力点，不建议每个页面都手写判断。可以把版本、设备、窗口、参数校验统一收口：
typeFeatureMode='full'|'fallback'|'blocked'interfaceFeatureInput{apiLevel:numberdeviceReady:booleanwindowStable:booleanpayloadReady:boolean}interfaceFeatureDecision{ok:booleanmode:FeatureMode reason:string}exportclassApi26FeatureGuard{constructor(privatereadonlyname:string){}check(input:FeatureInput):FeatureDecision{if(input.apiLevel<26){return{ok:false,mode:'fallback',reason:this.name+': api level below 26'}}if(!input.deviceReady){return{ok:false,mode:'blocked',reason:this.name+': device is not ready'}}if(!input.windowStable){return{ok:false,mode:'fallback',reason:this.name+': window is changing'}}if(!input.payloadReady){return{ok:false,mode:'blocked',reason:this.name+': payload is empty'}}return{ok:true,mode:'full',reason:this.name+': ready'}}}页面里就不需要到处写 if：
constguard=newApi26FeatureGuard('碰一碰深链参数校验')constdecision=guard.check({apiLevel:26,deviceReady:true,windowStable:true,payloadReady:true})if(!decision.ok){console.info(buildVerifyLog({feature:'碰一碰深链参数校验',apiLevel:26,scene:'demo',mode:decision.mode,reason:decision.reason,requestId:Date.now()}))}这套封装的好处是后面换特性也能复用：3DGS、空间音频、互动卡片、跨设备协同、小艺智能体，本质上都需要先判断“当前环境能不能跑完整能力”。能跑就跑完整能力，不能跑就给降级路径，不能悄悄失败。
上线前我会怎么检查
- 标题里的关键词能直接对应开发者会搜的问题。
- 正文第一屏就说明版本边界，不能让读者误以为 5.0、6.0 工程也能直接照搬。
- 至少两个案例，一个正常路径，一个失败或降级路径。
- 代码能说明核心思路，不写只有概念没有验证点的空段落。
- 图片要解释结构，不只是装饰。
- 如果涉及上架审核，要把权限说明、失败提示、截图材料一起准备。
- 如果涉及多设备，要补手机、折叠屏、平板或桌面窗口中的至少一种差异说明。
总结
碰一碰要把入口做轻，把校验做重。入口越短，兜底越要清楚。
写 HarmonyOS 7.0 的文章，不能只介绍“新增了什么”。更有价值的是把问题怎么发生、怎么复现、怎么修、怎么验证说清楚。这样读者不是看完知道一个名词，而是能把这套排查方法直接拿走。
