【HarmonyOS 7新能力｜022】ModularObjectExtensionAbility入门实战：从能力边界到最小可运行链路
跨应用调用最容易被低估的地方，不是“能不能把方法调通”，而是能力暴露之后如何保持边界清晰。调用方身份不可信、参数版本不一致、对象被长期占用、异常细节泄漏，都可能让一条方便的调用链变成稳定性或安全问题。
本文以ModularObjectExtensionAbility场景为背景，搭建“发现能力—构造请求—校验来源—创建对象—路由方法—返回结果—释放资源”的应用侧最小链路。文中接口、类型与适配器均为教学封装，不代表 HarmonyOS 7 官方 API 签名；真实工程必须以当前 SDK、设备能力和华为官方文档为准。
一、先定义能力边界，而不是先写实现
模块化对象适合把一组相关、可独立授权的操作收敛成稳定契约，例如文档转换、设备状态查询或受控的数据计算。它不应该成为“万能远程对象”，更不能把页面实例、数据库连接和平台上下文直接交给调用方。
第一版只开放两个只读操作：创建指定类型的会话对象，以及在对象上执行白名单方法。删除数据、修改账户、静默拉起页面等高风险动作不进入最小链路。这样验收目标很明确：未知来源拒绝、未知方法拒绝、错误参数拒绝、超时可恢复、对象释放后不能继续调用。
二、用窄契约隔离平台实现
先定义应用层模型，使业务代码不依赖平台回调对象。请求中携带协议版本、调用标识、对象标识、方法名和最小参数；结果只暴露可预期的状态码。
type MethodName = 'getSummary' | 'calculate' interface ObjectRequest { protocolVersion: 1 requestId: string objectId: string method: MethodName payload: Record<string, string | number | boolean> } interface ObjectResult { ok: boolean code: 'OK' | 'UNAUTHORIZED' | 'INVALID_ARGUMENT' | 'NOT_FOUND' | 'TIMEOUT' data?: Record<string, 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: ReadonlyMap<string, 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']): Promise<ObjectResult> close(): Promise<void> } class ObjectRegistry { private readonly objects = new Map<string, 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): Promise<ObjectResult> { 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 withDeadline<T>(task: Promise<T>, timeoutMs: number): Promise<T> { return Promise.race([ task, new Promise<T>((_, reject) => { setTimeout(() => reject(new Error('deadline exceeded')), timeoutMs) }) ]) }超时只是调用方停止等待，不等于底层任务必然停止。耗时服务还应支持取消令牌或分阶段检查，避免后台继续占用资源。
九、幂等不能只靠前端禁用按钮
跨应用调用可能因超时、进程恢复或网络桥接而重试。同一个requestId必须获得同一语义结果，尤其是会修改状态的操作。可以缓存短期结果，也可以持久化“请求号—业务结果”关系。
class ResultCache { private readonly values = new Map<string, 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) }适配表的价值在升级时兑现：每次目标版本变更，先对照表过一遍已知坑，能省下一整轮盲目排查。
