HarmonyOS Want 参数入口:应用链接白名单校验【共创稿事节】
业务推广链接带来的参数是外部输入,必须只允许有限的目标路径和标识格式,不能直接拼接内部页面。如果只看首次打开的画面,很难发现潜在缺陷。更有价值的是追踪一次完整的进入、修改、离开和恢复。
具体到「链接入口」这个页面,Want提供载体不代表参数可信,第三方入口可以传入不在业务约束内的内容。本文把讨论范围限定在「应用链接白名单校验」,不把界面能显示和数据已经被正确处理混为一谈。

把问题拆到数据边界
在链接入口里,「Want提供载体不代表参数可信」会影响后续操作。风险是:第三方入口可以传入不在业务约束内的内容。处理办法是入口先进行类型与长度校验。若要确认「异常参数无法直接触达内部路由」,可以安排「ID含空格和控制字符」作为回归用例,结果须符合在解析层拒绝,无业务查询发生。
先明确「显式与隐式用途不同」为什么会失败:把任意外部应用启动都当内部组件调用会产生适配问题。这不是简单刷新界面就能解决的问题,需要按照官方推荐用应用链接承接外部入口。验收时不仅要看到「集成不依赖猜测其他应用的Ability名」,还要确认本次操作没有改动其他不相关的数据。
「路径应当有白名单」与「解析与导航应分层」实际上相互制约。前一条风险表现为直接把URL路径当NavDestination名称存在越权风险;相应的处理是仅允许product和campaign两类已注册目标。增加新的操作入口之后,也应该继续满足「外部字符串不能任意决定内部页面」,不能为新页面单独复制一份规则。

从输入与输出看「标识要限制字符集」:输入环节的风险是异常分隔符和超长id可能影响日志与查询,因此先落实在parseTarget中集中验证格式;输出环节则应验证「非法内容在进入仓储前被拒绝」。结合「链接携带额外敏感字段」这一操作,预期结果为日志不输出原始URI全文,能够帮助定位发生偏差的阶段。
最后审查「查询参数需要确定优先级」这条约束:同一链接出现重复id字段时各解析库处理可能不同,因此应当在入口统一规定选择或拒绝策略。只有业务侧明确承担这项责任,链接解析结果可复现才能成为可以长期复核的标准,而不是某次页面渲染的巧合。
代码落点与最小闭环
对于LinkBinder这个工程,下面的片段把「Want提供载体不代表参数可信」所需的行为收敛到可以定位的代码上。主要涉及parseTarget。在LinkLanding.ets或对应common模块接入时,应明确调用方传入什么,尤其要防止「异常分隔符和超长id可能影响日志与查询」这一风险继续影响后续处理。对应的工程措施是「在parseTarget中集中验证格式」,不能只靠页面文字来表示处理成功。
interface LinkTarget {
type: 'product' | 'campaign';
id: string;
}
function parseTarget(path: string, id: string): LinkTarget | undefined {
if (!/^[A-Za-z0-9-]{1,40}$/.test(id)) { return undefined; }
if (path === '/product') { return { type: 'product', id: id }; }
if (path === '/campaign') { return { type: 'campaign', id: id }; }
return undefined;
}
function destination(target: LinkTarget): string {
return target.type === 'product' ? 'ProductPage' : 'CampaignPage';
}
Want的接收入口先限制为纯业务参数,再决定目的地。它不会根据外部传入的完整页面名直接执行导航。
import { Want } from '@kit.AbilityKit';
function targetFromWant(want: Want): LinkTarget | undefined {
const parameters = want.parameters;
if (!parameters) { return undefined; }
const path = parameters['path'];
const id = parameters['id'];
if (typeof path !== 'string' || typeof id !== 'string') {
return undefined;
}
return parseTarget(path, id);
}
这段实现适合先用静态数据检查「显式与隐式用途不同」和「来源字段不能当身份认证」两条路径。前者要解决把任意外部应用启动都当内部组件调用会产生适配问题,后者要求授权判断仍交由业务会话层完成。代码层只承诺得到可解释的状态,真正的展示和持久化要在调用位置按链接入口的业务流程串起来;这样才不会把界面点击当作仓储提交。
还要注意「前后台重复Want需考虑」:在已有UIAbility中收到新请求可能走onNewWant。由为重复链接定义是否复用页面承担这一职责后,其他入口调用相同函数可以得到一致处理。最后用「ID含空格和控制字符」观察在解析层拒绝,无业务查询发生,检查异常路径是否仍遵守同一语义。
如果计划在此基础上增加新功能,先确认「日志不得泄露完整URI」是否仍成立。记录目标类别和匿名错误原因带来的变化必须被单独验证,而不是假设新增页面会自然继承既有保障。
从组件行为到状态一致性
先确定「来源字段不能当身份认证」的处理界限。链接里写trusted不能证明调用者有权限;具体做法是授权判断仍交由业务会话层完成。验收应观察「跳转入口不绕过数据访问控制」,而不只判断界面是否响应。转到「日志不得泄露完整URI」的路径,也必须遵守同样的数据约束。
把「解析与导航应分层」单独列为检查条件,问题更容易识别:在UIAbility直接修改页面会使测试困难。实施上建议先输出受限LinkTarget,再映射内部目标名,目标是解析逻辑可以独立检验。还要补测「ID含空格和控制字符」,其结果应满足在解析层拒绝,无业务查询发生,不能只看首次进入的画面。
对「前后台重复Want需考虑」而言,先确定谁负责作出判断。因为在已有UIAbility中收到新请求可能走onNewWant,处理时需要为重复链接定义是否复用页面。这样才有机会得到「不会无意新增多个同一页面」的结果;与之关联的「显式与隐式用途不同」也应采用一致的责任划分。

「失败入口需要可理解反馈」容易被顺利路径掩盖。问题在于遇到未知路径时空白页会让用户不知所措,所以应当返回默认首页或显示链接已失效状态。正常结果是错误链接仍能进入正常应用界面;一旦失败,还需保留足以复现的操作状态,特别是「已有UIAbility收到新Want」这类边界场景。
讨论「日志不得泄露完整URI」时应先识别具体风险:链接可能包含个人编号或令牌。采取「记录目标类别和匿名错误原因」后,预期达到排查资料不扩大敏感数据暴露。与此同时,「标识要限制字符集」也可能改变执行条件,不能只用一种固定输入判断是否正确。
验证路径:正常与异常并重
本节把「链接入口」的验证条件具体化。验证应该以官方接口语义、可见的页面状态与可读取的数据为依据,不能把没有在设备上执行的逻辑检查写成性能实测;需要编译、权限或设备支持的步骤,应在对应开发环境中按项目配置完成。
「打开允许的商品链接」不应被正常路径的检查覆盖。这里必须验证解析为product且进入ProductPage,并且确认「失败入口需要可理解反馈」相关字段没有出现旁路修改;否则当前页面看似完成了操作,实际数据却仍可能不一致。
对「打开未知路径」做一次中断后重试,记录最后的可见结果是否符合不给内部Navigation传未知名称。这一用例能同时观察「日志不得泄露完整URI」的边界,重点看排查资料不扩大敏感数据暴露,不必预设任何未经采样的性能指标。
完成「ID含空格和控制字符」之后,直接检查在解析层拒绝,无业务查询发生。如果失败,不要只保存一张截图,而应记录Want提供载体不代表参数可信的触发顺序,以及「入口先进行类型与长度校验」是否被绕过,这些信息才足以支持修正。

先复现「同一个链接被重复触发」。此时的通过条件应写成「按既定重入策略管理已有目的地」,并对照「显式与隐式用途不同」的约束确认状态来源。如果结果偏离,先检查按照官方推荐用应用链接承接外部入口是否真正执行,而不是立即更换页面布局。
针对「已有UIAbility收到新Want」,观察点不仅是操作能否完成,还包括能按入口契约处理新目标,不依赖首次创建。建议保留触发前后的业务标识,尤其在「路径应当有白名单」存在时,核对外部字符串不能任意决定内部页面,才能排除旧状态干扰。
把「链接携带额外敏感字段」独立成一条回归记录:预期日志不输出原始URI全文。若出现异常,沿标识要限制字符集对应的处理逻辑往回定位,检查是否满足「在parseTarget中集中验证格式」这一前置条件。
从这次实现得到的经验
把「链接携带额外敏感字段」保留为发布前回归项,是因为日志不输出原始URI全文。它和「Want提供载体不代表参数可信」共同约束了数据进入系统以及返回用户界面的两个端点。
这次实现最值得保留的是「入口先进行类型与长度校验」与「记录目标类别和匿名错误原因」之间的分工。前者让异常参数无法直接触达内部路由,后者帮助排查资料不扩大敏感数据暴露。下一轮修改前,先把两条规则写进回归条件。
在资源、路由和权限问题上,建议以项目实际 target SDK 和设备 API 能力为准。本例围绕 HarmonyOS API 26.0.0 Release 可查证的公共机制组织,代码片段应放入完整 Stage 工程中按开发者文档补齐工程声明和对应资源。页面与技术图使用的示例状态一致,涉及数据写入及生命周期的部分应在 DevEco Studio 中分别执行编译与交互核查。
官方参考
更多推荐


所有评论(0)