外部拉起最容易被忽略的输入不是缺参数而是“看起来合法”的超长字符串、重复回调和不受支持的URI scheme。如果Want参数直接进入页面路由轻则打开错误页面重则把外部数据带进内部能力。方案面向HarmonyOS 6.1.1 Release SDKAPI 24系统Kit调用进入适配层命令约束、状态归并和恢复策略进入可测试的业务层。范围包含状态与资源生命周期设计、失败恢复和验收合同不包含业务内容生产、服务端协议改造以及特定厂商网页或媒体源的兼容承诺。先把外部输入当成不可信数据方案的RouteRequest只包含route、resourceId、source和requestId。解析器限制字段长度、枚举值和resourceId格式拒绝未知字段进入业务对象。requestId写入短期去重缓存同一个外部事件重复抵达只会复用已生成的导航结果。状态数量不是越多越好。每个状态必须回答三个问题当前允许哪些命令、收到迟到事件怎样处理、页面退出后是否还可以更新UI。下面的状态对象携带operationId新的操作开始后旧操作回调会被拒绝。export enum RouteRequestState { RECEIVED received, PARSED parsed, DENIED denied, WAITING_LOGIN waiting_login, NAVIGATING navigating, CONSUMED consumed } export interface RouteRequestSnapshot { state: RouteRequestState; progress: number; message: string; operationId: number; updatedAt: number; } export type RouteRequestEvent | { type: START; operationId: number } | { type: PROGRESS; operationId: number; progress: number } | { type: SUCCESS; operationId: number } | { type: FAIL; operationId: number; message: string }; export function acceptEvent( snapshot: RouteRequestSnapshot, event: RouteRequestEvent ): boolean { return event.type START || event.operationId snapshot.operationId; }设计对象保存内容不应该保存的内容页面状态可展示阶段、进度、错误摘要系统对象和页面Context适配器Kit实例、监听注册、资源句柄ArkUI组件引用业务记录operationId、版本、恢复点未脱敏的敏感原始数据诊断信息阶段耗时、错误码、能力检测Token、图片原始内容RouteRequest只保留业务必需字段路由分三段Parser负责类型与长度Policy负责允许的目标与登录要求Executor只执行经过批准的命令。登录前把规范化请求存入内存队列认证完成后按requestId恢复一次应用被杀后的外部请求要求用户重新确认不持久化敏感参数。这套分层把系统事实和产品行为分开Kit适配器负责获得事实领域对象决定是否接受事件页面只渲染快照。更换API版本或加入真机能力时只需要替换适配器状态归并和异常策略仍可在模拟器中重复验证。URI解析后再做白名单判断下面是主题专属的接入或核心算法代码。示例刻意保留资源创建、前置条件和清理逻辑因为高频故障往往出现在成功调用之外。import { Want } from kit.AbilityKit; export interface SafeRoute { route: detail | settings | import; resourceId?: string; requestId: string; source: internal | external; } export function parseWant(want: Want): SafeRoute | undefined { const params want.parameters ?? {}; const route String(params[route] ?? ); const requestId String(params[requestId] ?? ); const resourceId String(params[resourceId] ?? ); if (![detail, settings, import].includes(route)) return undefined; if (!/^[a-zA-Z0-9_-]{8,64}$/.test(requestId)) return undefined; if (resourceId !/^[a-zA-Z0-9_-]{1,48}$/.test(resourceId)) return undefined; return { route: route as SafeRoute[route], resourceId: resourceId || undefined, requestId, source: external }; } export class RequestDeduplicator { private consumed: Setstring new Set(); accept(request: SafeRoute): boolean { if (this.consumed.has(request.requestId)) return false; this.consumed.add(request.requestId); return true; } }代码迁入业务工程时应把错误码转换为稳定的领域错误不让页面直接判断系统错误字符串。对于异步回调还要在写入状态前比较operationId或资源版本仅检查组件是否存在无法阻止旧任务污染新页面。登录恢复不能重复消费请求故障输入状态变化恢复动作未知routeParser拒绝进入可解释错误页requestId重复去重器返回false不重复导航需要登录进入WAITING_LOGIN认证后恢复一次URI scheme不允许Policy拒绝不调用外部能力异常注入按钮用于稳定复现应用侧恢复路径。真实错误发生时诊断记录同时保存错误码、权限结果、设备能力和用户可见状态敏感原始数据不进入日志截图只呈现与问题直接相关的结果。错误页也属于路由协议页面层不直接调用Kit而是通过动作按钮驱动同一份状态模型。这样既能在系统能力可用时接真实适配器也能在模拟器缺少硬件时验证错误页面、幂等逻辑和资源清理。Component struct RouteRequestPanel { State stateText: string RECEIVED; State progress: number 0; State logs: string[] []; private append(message: string): void { const time new Date().toLocaleTimeString(); this.logs [${time} ${message}, ...this.logs].slice(0, 8); } private startDemo(): void { this.stateText PARSED; this.progress 20; this.append(开始Ability Kit Want安全路由); } private injectFailure(): void { this.stateText CONSUMED; this.append(已注入可恢复故障); } build() { Column({ space: 12 }) { Text(Ability Kit Want安全路由).fontSize(24).fontWeight(FontWeight.Bold) Text(this.stateText).fontSize(18).fontColor(#2563EB) Progress({ value: this.progress, total: 100 }).width(100%) Row({ space: 12 }) { Button(开始实验).onClick(() this.startDemo()) Button(注入故障).onClick(() this.injectFailure()) } ForEach(this.logs, (item: string) Text(item).fontSize(13)) }.padding(20).width(100%) } }准备正常详情、缺少ID、未知路由、超长参数、非法字符、重复requestId、需要登录、登录取消、错误scheme和内部跳转十组样本。结果表展示解析、策略和执行三个阶段任何失败都必须指出具体阶段。外部Want和内部路由最好共享同一个SafeRoute类型但来源字段必须保留。内部调用可以进入更多页面外部来源只能访问公开白名单不能因为类型相同就获得相同权限。错误页展示requestId的短摘要方便用户反馈但不回显原始URI和全部参数。登录恢复队列设置数量和过期时间超时请求要求重新发起。对于会产生写操作的目标页恢复后仍应展示确认步骤不能把一次外部拉起直接变成不可撤销操作。路由统计按拒绝原因聚合不记录完整参数值以免诊断数据反过来成为隐私泄漏来源。冷启动与已有Ability实例接收新Want要走同一解析入口确保两条生命周期路径执行完全一致的校验。拒绝结果也要可追踪。验收记录至少包括SDK版本、模拟器系统版本、操作顺序、预期状态、实际状态和截图编号。快速点击、返回再进入、故障后重试和页面销毁是必测项涉及资源的主题还要显示活动对象计数涉及异步任务的主题要验证迟到结果不会改变当前页面。十组Want样本的验收结果这套方案的技术闭环由“输入约束—状态模型—Kit适配—异常恢复—可观察验收”组成。业务状态不持有系统对象适配器不直接操作页面异常路径有明确的恢复动作后续SDK升级时可以分别回归每一层。官方资料AbilityKit相关开发文档