HarmonyOS应用实战-启示散页-47-HSP 功能页别自己注册路由让宿主统一掌握入口表HSP 里新增一个页面后最省事的做法是功能包自己写路由名、自己跳过去。短期能跑长期会让宿主不知道实际暴露了哪些入口拆包、灰度、下线和权限拦截时路由治理点散落在多个模块里。这篇文章解决四件事还原这个问题在答案之书这类离线应用里如何出现。明确页面、Service、Repository、AppStorage 或发布清单各自的责任。给出可迁移的 ArkTS/工程代码片段并说明反例为什么会留下隐患。用验证清单和排障表把方案收成可执行检查项。功能页可以来自 HSP入口权不能交给 HSPHSP 适合承载可复用功能页但宿主必须知道哪些页面可以被打开、从哪里打开、用什么参数打开。如果 HSP 自己硬编码宿主路由名就会形成反向依赖功能包知道宿主入口宿主反而不知道功能包暴露了什么。已核对的实现是libraryHSP/Index.ets 导出页面、组件和服务entry 的 Index.ets 集中维护 Navigation 的 pageMap。本文的 HostRouteRegistry 是围绕这个现状提出的治理设计。路由责任拆成导出、登记、跳转三步先写 owner 表再写代码。否则代码能跑起来却很难说明失败时该由谁回滚、重启后该由谁恢复、其他页面该根据什么信号刷新。Owner负责什么不负责什么libraryHSP/Index.ets导出页面 Builder 和服务能力决定宿主入口是否可见libraryHAR/Routes.ets保存稳定 RouteName 常量引入 ArkUI 页面实现entry HostRouteRegistry登记入口、参数约束、灰度和拦截规则把业务页面写进 HSPNavigation pageMap按宿主路由表分发 Builder到处散写 if/elseRouteRecord 让入口表可审计模型要表达本链路需要的稳定事实不要把页面临时状态或底层存储细节暴露出去。这样后续迁移 Preferences schema、拆模块或增加发布检查时调用方不必跟着重写。typeRouteNameHome|DeckEdit|Drawing|ReleaseCheck;interfaceHostRouteRecord{name:RouteName;ownerModule:entry|libraryHSP;requiresDeckId:boolean;enabled:boolean;}这段模型的重点有三点字段命名贴近业务输入输出能覆盖失败分支没有携带 ArkUI 组件状态。页面拿它展示Service 拿它做判断Repository 不需要知道页面长什么样。宿主登记入口并做参数约束Service 是规则 owner。凡是涉及校验、回滚、冲突、恢复、隐私或发布证据的逻辑都不要散落在组件回调里。classHostRouteRegistry{privaterecords:HostRouteRecord[][{name:DeckEdit,ownerModule:libraryHSP,requiresDeckId:true,enabled:true},{name:Drawing,ownerModule:libraryHSP,requiresDeckId:true,enabled:true},{name:ReleaseCheck,ownerModule:entry,requiresDeckId:false,enabled:false}];resolve(name:RouteName,params:Recordstring,string):HostRouteRecord{constrecordthis.records.find((item)item.namenameitem.enabled);if(!record){thrownewError(入口未开放${name});}if(record.requiresDeckId!params.deckId){thrownewError(入口缺少 deckId${name});}returnrecord;}}这里的 Service 不追求复杂抽象只做一件事把输入转成可解释结果。页面可以做乐观交互但最终事实必须从 Service 返回。HAR 只放路由常量不反向依赖 UIRepository 负责稳定读写、默认值和 schema 兼容。它不弹 Toast不决定按钮状态也不拼页面文案。exportconstBookRoutes{Home:Home,DeckEdit:DeckEdit,Drawing:Drawing,ReleaseCheck:ReleaseCheck}asconst;exporttypeBookRouteNametypeofBookRoutes[keyoftypeofBookRoutes];如果这一层缺失页面会被迫知道 store name、key、默认值和异常处理细节。写到后面所有页面都会变成半个仓储层。entry 的 pageMap 是唯一分发点页面只消费结果、展示状态、触发动作。跨页面刷新用轻量信号完整业务对象继续由 Service 重新读取。BuilderfunctionpageMap(name:string,param:object){if(nameBookRoutes.DeckEdit){DeckEditPageBuilder(param);}elseif(nameBookRoutes.Drawing){DrawingPageBuilder(param);}elseif(nameBookRoutes.ReleaseCheck){ReleaseChecklistPageBuilder(param);}}Navigation(this.pathStack){HomePage()}.navDestination(pageMap)这类写法的好处是入口可以扩展页面可以重进数据可以迁移。只要 Service 和 Repository 边界稳定页面不需要关心底层怎么保存。反例短期省事长期失控反例是在 HSP 页面内部直接pathStack.pushPath({ name: SomeHostPage })并把宿主路由名写死。这样 HSP 和 entry 互相知道内部细节功能下线时必须跨模块搜索所有跳转点。更具体地说反例通常有三个共同点直接写持久化、没有失败结果、没有刷新 owner。它们在单次手测里很难暴露但在重启、返回、跨入口或发布复查时会变成真实问题。排查顺序\n1. 先找唯一写入 owner。\n2. 再看失败是否返回可展示结果。\n3. 再看刷新信号是否只通知相关页面。\n4. 最后才检查 UI 展示。验证路径不要只走正常操作扫描 HSP确认没有硬编码宿主专属路由名。移除一个 HSP 导出时宿主入口表能集中暴露编译或启动期问题。缺 deckId 进入 DeckEdit/Drawing 时被 registry 拦下而不是到页面里才崩。新增 ReleaseCheck 入口时只改宿主入口表和 pageMap。验证时建议把“正常路径、异常输入、重启恢复、跨入口刷新、发布态检查”分开记录。构建通过只能证明语法和资源能打包不能证明这些运行链路都已经被真机验证。rg-nPreferencesStore|AppStorage.setOrCreate|Repository|ServiceD:\\ProgramData\\huawei\\lesson\\The_Book_of_Answers\nrg-nquestion|answerText|deckName|hilogD:\\ProgramData\\huawei\\lesson\\The_Book_of_Answers常见问题与处理现象先看哪里处理点击入口无反应registry 是否 enabled先看 HostRouteRecordHSP 拆包后路由找不到宿主是否登记 Builderentry 统一维护 pageMap参数到页面才报错requiresDeckId 是否提前校验入口层拦截无效参数处理这些问题时不要先改 UI 文案。先确认写入 owner、读取 owner 和刷新信号是否一致再看页面是否正确消费结果。若只在页面补一个 Toast用户当次可能看到了提示但重启、返回、跨入口和发布复查仍然会暴露同一个根因。落地取舍这套方案不是为了把轻量应用写重而是为了把真正会跨页面、跨启动、跨发布阶段的事实收住。只影响当前展示节奏的变量可以留在页面会改变用户内容、持久结构、隐私口径或发布证据的逻辑必须进入 Service、Repository 或发布清单。判断点建议位置原因只影响当前按钮、弹层或动画页面State不需要跨入口复用会写本地数据或读持久事实Service Repository需要校验、回滚和恢复会影响其他页面刷新AppStorage 时间戳通知变化不共享完整对象会影响发布、截图、隐私或诊断发布清单或运行账本后续复查需要证据真正落地时可以先从一条最容易复现的路径开始找出唯一写入点补上结果模型再把页面里的直接读写替换成 Service 调用。这个顺序比一次性重构全部页面更稳也更容易在评审时说明每一行代码解决了哪个故障链。评审记录里最好保留对应的命令、截图或复现步骤避免方案只停留在口头约定。小结HSP 可以提供页面但入口治理属于宿主。把 RouteName 放在公共层把 Builder 导出放在 HSP把入口登记放在 entry路由链路就能被审计、灰度和下线而不是靠跨模块搜索碰运气。说明每一行代码解决了哪个故障链。评审记录里最好保留对应的命令、截图或复现步骤避免方案只停留在口头约定。小结HSP 可以提供页面但入口治理属于宿主。把 RouteName 放在公共层把 Builder 导出放在 HSP把入口登记放在 entry路由链路就能被审计、灰度和下线而不是靠跨模块搜索碰运气。