【HarmonyOS 7新能力022】ModularObjectExtensionAbility入门实战从能力边界到最小可运行链路跨应用调用最容易被低估的地方不是“能不能把方法调通”而是能力暴露之后如何保持边界清晰。调用方身份不可信、参数版本不一致、对象被长期占用、异常细节泄漏都可能让一条方便的调用链变成稳定性或安全问题。本文以ModularObjectExtensionAbility场景为背景搭建“发现能力—构造请求—校验来源—创建对象—路由方法—返回结果—释放资源”的应用侧最小链路。文中接口、类型与适配器均为教学封装不代表 HarmonyOS 7 官方 API 签名真实工程必须以当前 SDK、设备能力和华为官方文档为准。一、先定义能力边界而不是先写实现模块化对象适合把一组相关、可独立授权的操作收敛成稳定契约例如文档转换、设备状态查询或受控的数据计算。它不应该成为“万能远程对象”更不能把页面实例、数据库连接和平台上下文直接交给调用方。第一版只开放两个只读操作创建指定类型的会话对象以及在对象上执行白名单方法。删除数据、修改账户、静默拉起页面等高风险动作不进入最小链路。这样验收目标很明确未知来源拒绝、未知方法拒绝、错误参数拒绝、超时可恢复、对象释放后不能继续调用。二、用窄契约隔离平台实现先定义应用层模型使业务代码不依赖平台回调对象。请求中携带协议版本、调用标识、对象标识、方法名和最小参数结果只暴露可预期的状态码。type MethodName getSummary | calculate interface ObjectRequest { protocolVersion: 1 requestId: string objectId: string method: MethodName payload: Recordstring, string | number | boolean } interface ObjectResult { ok: boolean code: OK | UNAUTHORIZED | INVALID_ARGUMENT | NOT_FOUND | TIMEOUT data?: Recordstring, string | number | boolean }requestId用于幂等和追踪objectId指向受控对象实例。不要接受任意方法字符串后用反射执行也不要把内部异常栈原样返回。三、建立完整的调用状态机调用不是一个瞬时函数而是一段有终点的状态流。把状态显式化才能覆盖取消、超时和对象释放等边界。type CallState | received | authorizing | validating | executing | completed | rejected | released interface CallTrace { requestId: string state: CallState startedAt: number deadlineAt: number }任何状态只能向允许的下一状态迁移。进入completed、rejected或released后都视为终态迟到的异步结果只能丢弃不能再次更新业务数据。四、来源校验必须早于对象创建校验顺序应是“解析最小头部—识别来源—检查授权—再解析完整载荷”。如果先创建对象或读取数据再判断来源是否合法拒绝发生得太晚副作用可能已经产生。interface CallerIdentity { bundleName: string signatureDigest: string } function isAllowed(caller: CallerIdentity, allowlist: ReadonlyMapstring, string): boolean { const expected allowlist.get(caller.bundleName) return expected ! undefined expected caller.signatureDigest }示例中的身份字段只是应用侧抽象。真实身份、权限和签名信息应通过平台正式提供的可信接口获取不能相信调用方在普通业务参数里自报的包名或身份。五、参数校验要同时检查结构与语义类型正确不代表语义正确。calculate的数值可能超出允许区间getSummary的资源标识可能属于另一个租户超长文本还可能造成内存压力。function validate(req: ObjectRequest): string | null { if (req.protocolVersion ! 1) return unsupported protocol if (!/^[a-zA-Z0-9-]{8,64}$/.test(req.requestId)) return invalid requestId if (!/^[a-zA-Z0-9_-]{1,48}$/.test(req.objectId)) return invalid objectId if (Object.keys(req.payload).length 16) return payload too large return null }建议为每个方法再维护独立校验器而不是让一个大函数处理所有参数。拒绝信息用于本地诊断对外只返回稳定错误码避免暴露规则细节。六、对象注册表负责生命周期对象注册表不能只是一个永不清理的Map。每个实例都要有所有者、创建时间、最后访问时间、当前状态和过期策略调用结束、调用方断开或达到空闲期限时应释放其持有资源。interface ManagedObject { id: string ownerKey: string state: active | closing | closed lastAccessAt: number execute(method: MethodName, payload: ObjectRequest[payload]): PromiseObjectResult close(): Promisevoid } class ObjectRegistry { private readonly objects new Mapstring, ManagedObject() getForOwner(id: string, ownerKey: string): ManagedObject | undefined { const item this.objects.get(id) return item?.state active item.ownerKey ownerKey ? item : undefined } }所有权检查避免调用方猜中objectId后访问别人的对象。关闭过程应可重复调用并确保即使某一步清理失败也不会重新回到活动状态。七、方法路由采用显式白名单路由层只认识契约中声明的方法。每个分支负责调用对应服务并把内部结果转换为可序列化的数据不把函数、平台对象、文件句柄或超大二进制对象跨边界传递。async function dispatch(target: ManagedObject, req: ObjectRequest): PromiseObjectResult { switch (req.method) { case getSummary: return target.execute(getSummary, req.payload) case calculate: return target.execute(calculate, req.payload) default: return { ok: false, code: NOT_FOUND } } }即使 ArkTS 的联合类型已限制方法名运行时数据仍来自跨进程或跨应用边界因此运行时检查不能省略。八、并发与超时要由编排层统一处理同一对象上的两个写操作是否允许并行取决于业务语义。最稳妥的默认策略是对象内串行、对象间并行纯查询可在证明线程安全后单独放宽。每次调用都设置截止时间超时后禁止迟到结果落库。async function withDeadlineT(task: PromiseT, timeoutMs: number): PromiseT { return Promise.race([ task, new PromiseT((_, reject) { setTimeout(() reject(new Error(deadline exceeded)), timeoutMs) }) ]) }超时只是调用方停止等待不等于底层任务必然停止。耗时服务还应支持取消令牌或分阶段检查避免后台继续占用资源。九、幂等不能只靠前端禁用按钮跨应用调用可能因超时、进程恢复或网络桥接而重试。同一个requestId必须获得同一语义结果尤其是会修改状态的操作。可以缓存短期结果也可以持久化“请求号—业务结果”关系。class ResultCache { private readonly values new Mapstring, ObjectResult() read(key: string): ObjectResult | undefined { return this.values.get(key) } write(key: string, value: ObjectResult): void { this.values.set(key, value) } }幂等键要与可信调用方身份组合使用避免不同调用方碰巧使用相同请求号而共享结果。缓存还应设置容量与有效期。十、错误映射保持稳定且克制平台错误、业务错误和调用方错误需要在适配层统一收敛。权限失败映射为UNAUTHORIZED字段错误映射为INVALID_ARGUMENT对象不存在或不属于当前调用方统一映射为NOT_FOUND避免通过差异化响应枚举对象。日志中可记录请求号、匿名化来源键、方法名、耗时、结果码和协议版本但不要记录完整载荷、凭据、个人信息或签名材料。对外结果可稳定对内诊断可精确两者不冲突。十一、版本升级采用兼容窗口契约升级不要直接修改旧字段含义。新增可选字段时给出默认值破坏性变化提升协议版本并在一段时间内同时保留旧版适配器。调用方请求不支持的版本时应获得明确但不泄露内部实现的错误。建议用契约样例做回归测试旧版合法请求仍能运行缺失可选字段使用默认值未知字段被忽略或明确拒绝新版结果不会让旧调用方误解。版本淘汰前还要通过统计确认旧调用量已降到可接受范围。十二、用失败场景完成验收最小链路至少覆盖授权调用成功未知来源被拒绝且未创建对象伪造业务参数不能绕过平台身份未知方法被拒绝超长载荷被拒绝对象跨所有者访问失败重复请求不产生重复副作用释放后调用失败超时结果不回写日志不含敏感载荷。还要模拟应用进程重启和调用方异常退出确认临时对象能清理、持久幂等记录能恢复。完成这些检查后再扩展更多对象类型和方法比一开始开放大而全的接口更可靠。模块化对象的价值不在于把所有能力都跨应用暴露而在于用清晰契约交付一小段可授权、可隔离、可升级的能力。只要守住可信身份、窄接口、生命周期、幂等、超时和稳定错误六条边界跨应用调用才能从“演示可用”走向“工程可维护”。十三、接入前检查清单ModularObjec正式接入前工程侧要过一遍检查清单SDK 版本与目标 API 版本匹配、权限在清单中声明且按需申请、能力开关在专用配置层管理、包体积增量符合预算。任何一项不过就先停带着不匹配的版本往上冲排错成本会翻倍。interface PrecheckItem { name: string; pass: boolean; note?: string } const checklist: PrecheckItem[] [ { name: SDK/API版本匹配, pass: false }, { name: 权限声明完整, pass: false }, { name: 开关集中管理, pass: false }, { name: 包体积增量预算, pass: false }, ] const allPass checklist.every(x x.pass)检查清单跑通的标志是新建工程按清单接入一次成功且不依赖任何口头经验。做不到说明文档还缺关键步骤。十四、常见坑与版本适配记录ModularObjec最常踩的坑集中在三处示例代码用的旧接口在新版本被拆分、默认配置与生产预期不一致、调试环境与真机行为有差异。每踩一个坑就记进版本适配表注明坑点、影响版本、修复方式与验证方式。interface Pitfall { issue: string; sinceApi: string; fix: string; verifiedOn: string[] } const pitfalls: Pitfall[] [] function knownPit(api: string): Pitfall[] { return pitfalls.filter(p p.sinceApi api) }适配表的价值在升级时兑现每次目标版本变更先对照表过一遍已知坑能省下一整轮盲目排查。
【HarmonyOS 7新能力022】ModularObjectExtensionAbility入门实战从能力边界到最小可运行链路跨应用调用最容易被低估的地方不是“能不能把方法调通”而是能力暴露之后如何保持边界清晰。调用方身份不可信、参数版本不一致、对象被长期占用、异常细节泄漏都可能让一条方便的调用链变成稳定性或安全问题。本文以ModularObjectExtensionAbility场景为背景搭建“发现能力—构造请求—校验来源—创建对象—路由方法—返回结果—释放资源”的应用侧最小链路。文中接口、类型与适配器均为教学封装不代表 HarmonyOS 7 官方 API 签名真实工程必须以当前 SDK、设备能力和华为官方文档为准。一、先定义能力边界而不是先写实现模块化对象适合把一组相关、可独立授权的操作收敛成稳定契约例如文档转换、设备状态查询或受控的数据计算。它不应该成为“万能远程对象”更不能把页面实例、数据库连接和平台上下文直接交给调用方。第一版只开放两个只读操作创建指定类型的会话对象以及在对象上执行白名单方法。删除数据、修改账户、静默拉起页面等高风险动作不进入最小链路。这样验收目标很明确未知来源拒绝、未知方法拒绝、错误参数拒绝、超时可恢复、对象释放后不能继续调用。二、用窄契约隔离平台实现先定义应用层模型使业务代码不依赖平台回调对象。请求中携带协议版本、调用标识、对象标识、方法名和最小参数结果只暴露可预期的状态码。type MethodName getSummary | calculate interface ObjectRequest { protocolVersion: 1 requestId: string objectId: string method: MethodName payload: Recordstring, string | number | boolean } interface ObjectResult { ok: boolean code: OK | UNAUTHORIZED | INVALID_ARGUMENT | NOT_FOUND | TIMEOUT data?: Recordstring, string | number | boolean }requestId用于幂等和追踪objectId指向受控对象实例。不要接受任意方法字符串后用反射执行也不要把内部异常栈原样返回。三、建立完整的调用状态机调用不是一个瞬时函数而是一段有终点的状态流。把状态显式化才能覆盖取消、超时和对象释放等边界。type CallState | received | authorizing | validating | executing | completed | rejected | released interface CallTrace { requestId: string state: CallState startedAt: number deadlineAt: number }任何状态只能向允许的下一状态迁移。进入completed、rejected或released后都视为终态迟到的异步结果只能丢弃不能再次更新业务数据。四、来源校验必须早于对象创建校验顺序应是“解析最小头部—识别来源—检查授权—再解析完整载荷”。如果先创建对象或读取数据再判断来源是否合法拒绝发生得太晚副作用可能已经产生。interface CallerIdentity { bundleName: string signatureDigest: string } function isAllowed(caller: CallerIdentity, allowlist: ReadonlyMapstring, string): boolean { const expected allowlist.get(caller.bundleName) return expected ! undefined expected caller.signatureDigest }示例中的身份字段只是应用侧抽象。真实身份、权限和签名信息应通过平台正式提供的可信接口获取不能相信调用方在普通业务参数里自报的包名或身份。五、参数校验要同时检查结构与语义类型正确不代表语义正确。calculate的数值可能超出允许区间getSummary的资源标识可能属于另一个租户超长文本还可能造成内存压力。function validate(req: ObjectRequest): string | null { if (req.protocolVersion ! 1) return unsupported protocol if (!/^[a-zA-Z0-9-]{8,64}$/.test(req.requestId)) return invalid requestId if (!/^[a-zA-Z0-9_-]{1,48}$/.test(req.objectId)) return invalid objectId if (Object.keys(req.payload).length 16) return payload too large return null }建议为每个方法再维护独立校验器而不是让一个大函数处理所有参数。拒绝信息用于本地诊断对外只返回稳定错误码避免暴露规则细节。六、对象注册表负责生命周期对象注册表不能只是一个永不清理的Map。每个实例都要有所有者、创建时间、最后访问时间、当前状态和过期策略调用结束、调用方断开或达到空闲期限时应释放其持有资源。interface ManagedObject { id: string ownerKey: string state: active | closing | closed lastAccessAt: number execute(method: MethodName, payload: ObjectRequest[payload]): PromiseObjectResult close(): Promisevoid } class ObjectRegistry { private readonly objects new Mapstring, ManagedObject() getForOwner(id: string, ownerKey: string): ManagedObject | undefined { const item this.objects.get(id) return item?.state active item.ownerKey ownerKey ? item : undefined } }所有权检查避免调用方猜中objectId后访问别人的对象。关闭过程应可重复调用并确保即使某一步清理失败也不会重新回到活动状态。七、方法路由采用显式白名单路由层只认识契约中声明的方法。每个分支负责调用对应服务并把内部结果转换为可序列化的数据不把函数、平台对象、文件句柄或超大二进制对象跨边界传递。async function dispatch(target: ManagedObject, req: ObjectRequest): PromiseObjectResult { switch (req.method) { case getSummary: return target.execute(getSummary, req.payload) case calculate: return target.execute(calculate, req.payload) default: return { ok: false, code: NOT_FOUND } } }即使 ArkTS 的联合类型已限制方法名运行时数据仍来自跨进程或跨应用边界因此运行时检查不能省略。八、并发与超时要由编排层统一处理同一对象上的两个写操作是否允许并行取决于业务语义。最稳妥的默认策略是对象内串行、对象间并行纯查询可在证明线程安全后单独放宽。每次调用都设置截止时间超时后禁止迟到结果落库。async function withDeadlineT(task: PromiseT, timeoutMs: number): PromiseT { return Promise.race([ task, new PromiseT((_, reject) { setTimeout(() reject(new Error(deadline exceeded)), timeoutMs) }) ]) }超时只是调用方停止等待不等于底层任务必然停止。耗时服务还应支持取消令牌或分阶段检查避免后台继续占用资源。九、幂等不能只靠前端禁用按钮跨应用调用可能因超时、进程恢复或网络桥接而重试。同一个requestId必须获得同一语义结果尤其是会修改状态的操作。可以缓存短期结果也可以持久化“请求号—业务结果”关系。class ResultCache { private readonly values new Mapstring, ObjectResult() read(key: string): ObjectResult | undefined { return this.values.get(key) } write(key: string, value: ObjectResult): void { this.values.set(key, value) } }幂等键要与可信调用方身份组合使用避免不同调用方碰巧使用相同请求号而共享结果。缓存还应设置容量与有效期。十、错误映射保持稳定且克制平台错误、业务错误和调用方错误需要在适配层统一收敛。权限失败映射为UNAUTHORIZED字段错误映射为INVALID_ARGUMENT对象不存在或不属于当前调用方统一映射为NOT_FOUND避免通过差异化响应枚举对象。日志中可记录请求号、匿名化来源键、方法名、耗时、结果码和协议版本但不要记录完整载荷、凭据、个人信息或签名材料。对外结果可稳定对内诊断可精确两者不冲突。十一、版本升级采用兼容窗口契约升级不要直接修改旧字段含义。新增可选字段时给出默认值破坏性变化提升协议版本并在一段时间内同时保留旧版适配器。调用方请求不支持的版本时应获得明确但不泄露内部实现的错误。建议用契约样例做回归测试旧版合法请求仍能运行缺失可选字段使用默认值未知字段被忽略或明确拒绝新版结果不会让旧调用方误解。版本淘汰前还要通过统计确认旧调用量已降到可接受范围。十二、用失败场景完成验收最小链路至少覆盖授权调用成功未知来源被拒绝且未创建对象伪造业务参数不能绕过平台身份未知方法被拒绝超长载荷被拒绝对象跨所有者访问失败重复请求不产生重复副作用释放后调用失败超时结果不回写日志不含敏感载荷。还要模拟应用进程重启和调用方异常退出确认临时对象能清理、持久幂等记录能恢复。完成这些检查后再扩展更多对象类型和方法比一开始开放大而全的接口更可靠。模块化对象的价值不在于把所有能力都跨应用暴露而在于用清晰契约交付一小段可授权、可隔离、可升级的能力。只要守住可信身份、窄接口、生命周期、幂等、超时和稳定错误六条边界跨应用调用才能从“演示可用”走向“工程可维护”。十三、接入前检查清单ModularObjec正式接入前工程侧要过一遍检查清单SDK 版本与目标 API 版本匹配、权限在清单中声明且按需申请、能力开关在专用配置层管理、包体积增量符合预算。任何一项不过就先停带着不匹配的版本往上冲排错成本会翻倍。interface PrecheckItem { name: string; pass: boolean; note?: string } const checklist: PrecheckItem[] [ { name: SDK/API版本匹配, pass: false }, { name: 权限声明完整, pass: false }, { name: 开关集中管理, pass: false }, { name: 包体积增量预算, pass: false }, ] const allPass checklist.every(x x.pass)检查清单跑通的标志是新建工程按清单接入一次成功且不依赖任何口头经验。做不到说明文档还缺关键步骤。十四、常见坑与版本适配记录ModularObjec最常踩的坑集中在三处示例代码用的旧接口在新版本被拆分、默认配置与生产预期不一致、调试环境与真机行为有差异。每踩一个坑就记进版本适配表注明坑点、影响版本、修复方式与验证方式。interface Pitfall { issue: string; sinceApi: string; fix: string; verifiedOn: string[] } const pitfalls: Pitfall[] [] function knownPit(api: string): Pitfall[] { return pitfalls.filter(p p.sinceApi api) }适配表的价值在升级时兑现每次目标版本变更先对照表过一遍已知坑能省下一整轮盲目排查。
