HarmonyOS应用实战-启示散页-47-HSP 功能页别自己注册路由：让宿主统一掌握入口表

HarmonyOS应用实战-启示散页-47-HSP 功能页别自己注册路由：让宿主统一掌握入口表

HSP 里新增一个页面后，最省事的做法是功能包自己写路由名、自己跳过去。短期能跑，长期会让宿主不知道实际暴露了哪些入口；拆包、灰度、下线和权限拦截时，路由治理点散落在多个模块里。

这篇文章解决四件事：

1. 还原这个问题在答案之书这类离线应用里如何出现。
2. 明确页面、Service、Repository、AppStorage 或发布清单各自的责任。
3. 给出可迁移的 ArkTS/工程代码片段，并说明反例为什么会留下隐患。
4. 用验证清单和排障表把方案收成可执行检查项。

功能页可以来自 HSP，入口权不能交给 HSP

HSP 适合承载可复用功能页，但宿主必须知道哪些页面可以被打开、从哪里打开、用什么参数打开。如果 HSP 自己硬编码宿主路由名，就会形成反向依赖：功能包知道宿主入口，宿主反而不知道功能包暴露了什么。

已核对的实现是：libraryHSP/Index.ets 导出页面、组件和服务，entry 的 Index.ets 集中维护 Navigation 的 pageMap。本文的 HostRouteRegistry 是围绕这个现状提出的治理设计。

路由责任拆成导出、登记、跳转三步

先写 owner 表，再写代码。否则代码能跑起来，却很难说明失败时该由谁回滚、重启后该由谁恢复、其他页面该根据什么信号刷新。

RouteRecord 让入口表可审计

模型要表达本链路需要的稳定事实，不要把页面临时状态或底层存储细节暴露出去。这样后续迁移 Preferences schema、拆模块或增加发布检查时，调用方不必跟着重写。

type RouteName = 'Home' | 'DeckEdit' | 'Drawing' | 'ReleaseCheck';

interface HostRouteRecord {
  name: RouteName;
  ownerModule: 'entry' | 'libraryHSP';
  requiresDeckId: boolean;
  enabled: boolean;
}

这段模型的重点有三点：字段命名贴近业务；输入输出能覆盖失败分支；没有携带 ArkUI 组件状态。页面拿它展示，Service 拿它做判断，Repository 不需要知道页面长什么样。

宿主登记入口并做参数约束

Service 是规则 owner。凡是涉及校验、回滚、冲突、恢复、隐私或发布证据的逻辑，都不要散落在组件回调里。

class HostRouteRegistry {
  private records: 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: Record<string, string>): HostRouteRecord {
    const record = this.records.find((item) => item.name === name && item.enabled);
    if (!record) {
      throw new Error(`入口未开放：${name}`);
    }
    if (record.requiresDeckId && !params.deckId) {
      throw new Error(`入口缺少 deckId：${name}`);
    }
    return record;
  }
}

这里的 Service 不追求复杂抽象，只做一件事：把输入转成可解释结果。页面可以做乐观交互，但最终事实必须从 Service 返回。

HAR 只放路由常量，不反向依赖 UI

Repository 负责稳定读写、默认值和 schema 兼容。它不弹 Toast，不决定按钮状态，也不拼页面文案。

export const BookRoutes = {
  Home: 'Home',
  DeckEdit: 'DeckEdit',
  Drawing: 'Drawing',
  ReleaseCheck: 'ReleaseCheck'
} as const;

export type BookRouteName = typeof BookRoutes[keyof typeof BookRoutes];

如果这一层缺失，页面会被迫知道 store name、key、默认值和异常处理细节。写到后面，所有页面都会变成半个仓储层。

entry 的 pageMap 是唯一分发点

页面只消费结果、展示状态、触发动作。跨页面刷新用轻量信号，完整业务对象继续由 Service 重新读取。

@Builder
function pageMap(name: string, param: object) {
  if (name === BookRoutes.DeckEdit) {
    DeckEditPageBuilder(param);
  } else if (name === BookRoutes.Drawing) {
    DrawingPageBuilder(param);
  } else if (name === BookRoutes.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 -n "PreferencesStore|AppStorage.setOrCreate|Repository|Service" D:\\ProgramData\\huawei\\lesson\\The_Book_of_Answers\nrg -n "question|answerText|deckName|hilog" D:\\ProgramData\\huawei\\lesson\\The_Book_of_Answers

常见问题与处理

处理这些问题时不要先改 UI 文案。先确认写入 owner、读取 owner 和刷新信号是否一致，再看页面是否正确消费结果。若只在页面补一个 Toast，用户当次可能看到了提示，但重启、返回、跨入口和发布复查仍然会暴露同一个根因。

落地取舍

这套方案不是为了把轻量应用写重，而是为了把真正会跨页面、跨启动、跨发布阶段的事实收住。只影响当前展示节奏的变量可以留在页面；会改变用户内容、持久结构、隐私口径或发布证据的逻辑，必须进入 Service、Repository 或发布清单。

真正落地时，可以先从一条最容易复现的路径开始：找出唯一写入点，补上结果模型，再把页面里的直接读写替换成 Service 调用。这个顺序比一次性重构全部页面更稳，也更容易在评审时说明每一行代码解决了哪个故障链。评审记录里最好保留对应的命令、截图或复现步骤，避免方案只停留在口头约定。

小结

HSP 可以提供页面，但入口治理属于宿主。把 RouteName 放在公共层，把 Builder 导出放在 HSP，把入口登记放在 entry，路由链路就能被审计、灰度和下线，而不是靠跨模块搜索碰运气。
说明每一行代码解决了哪个故障链。评审记录里最好保留对应的命令、截图或复现步骤，避免方案只停留在口头约定。

小结

HSP 可以提供页面，但入口治理属于宿主。把 RouteName 放在公共层，把 Builder 导出放在 HSP，把入口登记放在 entry，路由链路就能被审计、灰度和下线，而不是靠跨模块搜索碰运气。