056 — 模块化路由设计：RouterMap 枚举驱动的导航解耦

简介

在多模块工程中，页面导航是一个易于被忽视但却影响深远的架构决策。如果每个页面直接引用目标页面的路径字符串，一旦路径变更（如模块重构、包名修改），所有引用方都需要同步修改，维护成本极高。MoneyTrack 通过 RouterMap 枚举将 17 个路由目标集中管理，结合 DialogMap 管理对话框路由，并通过 RouterModule 封装类统一封装跳转逻辑，实现了页面间的完全解耦。

核心知识点

1. 路由跳转完整流程

使用 mermaid 图可以清晰地展示一次路由跳转的完整流程：

通过 RouterMap 枚举的中间层，源页面与目标页面的物理路径完全解耦——源页面只感知语义化的枚举名，不感知路径字符串。

2. 路由集中管理

将所有可跳转页面的路径定义为枚举值，每个枚举项对应一个页面 URL：

• 集中管理使得路径变更只需修改枚举定义，所有使用者自动生效。
• 枚举值具有语义化，一眼看出跳转目标。
• 配合 TypeScript，跳转参数也能做到类型安全。

3. RouterMap 枚举类型安全的具体实现

在基础版本之上，通过泛型约束实现参数的类型安全：

// 定义路由参数的类型映射
export interface RouteParams {
  [RouterMap.BILL_LIST]: { categoryId?: string; startDate?: string };
  [RouterMap.BILL_DETAIL]: { billId: string };
  [RouterMap.ADD_BILL]: { prefillCategory?: string };
  [RouterMap.ASSET_DETAIL]: { assetId: string };
  [RouterMap.STATISTICS]: { year?: number; month?: number };
  [RouterMap.SETTINGS]: Record<string, never>;
  [RouterMap.LOGIN]: { redirect?: string };
  // ... 其他路由参数类型
}

// 类型安全的路由封装
export class RouterModule {
  static navigateTo<T extends RouterMap>(
    target: T,
    params?: RouteParams[T]
  ) {
    router.pushUrl({ url: target, params });
  }
}

这种设计下，RouterModule.navigateTo(RouterMap.BILL_DETAIL, { billId: '123' }) 是类型安全的——参数对象的字段和类型由泛型约束自动推导。如果传递了错误的参数名或类型，编译阶段就会报错。

4. 模块间路由解耦

模块间解耦的核心是"依赖倒置"：

• feature 模块不直接引用其他 feature 模块的页面。
• 所有路由通过 RouterMap 枚举间接引用，枚举定义在 common 层。
• feature 模块只需依赖 common 层，不依赖其他 feature。

5. NavPathStack 与 router API 的对比

鸿蒙提供了两种主要的导航方式，它们的对比如下：

特性	router API (pushUrl)	NavPathStack
使用方式	全局函数调用	Navigation 组件的栈管理
页面栈控制	基础 push/replace/back	完整栈操作，支持 popToIndex/popToName
参数传递	params 对象	泛型参数，类型更安全
页面间动画	不支持自定义	支持自定义转场动画
适用场景	简单跳转、跨模块导航	复杂导航结构、Tab 页内导航

在 MoneyTrack 中，跨模块的页面跳转统一使用 router API 配合 RouterMap 枚举；而在同一 feature 内部的页面导航（如账单列表页 → 账单详情页），则使用 NavPathStack 获得更好的动画控制和栈管理能力。

6. 路由参数的类型安全

除了路由目标的类型安全，路由参数本身也需要关注：

• 必选参数：如账单详情需要 billId，在类型定义中标记为必填。
• 可选参数：如列表页的筛选条件可以传也可以不传。
• 参数校验：在目标页面的 onPageShow 或 aboutToAppear 中对参数进行校验，缺失必选参数时给出友好提示或跳转回退。

// 目标页面参数校验
aboutToAppear() {
  const params = router.getParams() as RouteParams[RouterMap.BILL_DETAIL];
  if (!params?.billId) {
    console.error('缺少必选参数 billId');
    router.back();
    return;
  }
  this.billId = params.billId;
}

7. 路由守卫和拦截器

在需要统一处理登录校验、权限检查等场景时，可以使用路由守卫：

export class RouterGuard {
  // 需要登录才能访问的路由列表
  private static authRequiredRoutes: RouterMap[] = [
    RouterMap.SETTINGS,
    RouterMap.MEMBERSHIP,
    RouterMap.FEEDBACK,
  ];

  static canNavigate(target: RouterMap): boolean {
    if (this.authRequiredRoutes.includes(target) && !AuthService.isLoggedIn()) {
      // 未登录，跳转到登录页
      RouterModule.navigateTo(RouterMap.LOGIN, { redirect: target });
      return false;
    }
    return true;
  }
}

// 在 RouterModule 中集成守卫
export class RouterModule {
  static navigateTo<T extends RouterMap>(target: T, params?: RouteParams[T]) {
    if (!RouterGuard.canNavigate(target)) return;
    router.pushUrl({ url: target, params });
  }
}

8. DialogMap 对话框路由

对话框也可以像页面一样管理：

• DialogMap 枚举管理所有对话框路由（确认框、选择框、输入框等）。
• 通过统一的 Dialog 管理器打开/关闭对话框。

项目代码案例

文件路径：lib_router/RouterMap.ets

export enum RouterMap {
  INDEX = 'pages/Index',
  BILL_LIST = 'pages/BillList',
  BILL_DETAIL = 'pages/BillDetail',
  ADD_BILL = 'pages/AddBill',
  ASSET_LIST = 'pages/AssetList',
  ASSET_DETAIL = 'pages/AssetDetail',
  ADD_ASSET = 'pages/AddAsset',
  STATISTICS = 'pages/Statistics',
  SETTINGS = 'pages/Settings',
  LOGIN = 'pages/Login',
  MEMBERSHIP = 'pages/Membership',
  FEEDBACK = 'pages/Feedback',
  // ... 共 17 个路由目标
}

export enum DialogMap {
  CONFIRM_DELETE = 'dialog/ConfirmDelete',
  DATE_PICKER = 'dialog/DatePicker',
  CATEGORY_PICKER = 'dialog/CategoryPicker',
}

RouterModule 封装：

export class RouterModule {
  static navigateTo(target: RouterMap, params?: Record<string, Object>) {
    router.pushUrl({ url: target, params });
  }
}

通过 RouterMap + RouterModule + RouterGuard 的组合，MoneyTrack 实现了路由的集中管理、类型安全、守卫拦截三大目标。任意页面都只需调用 RouterModule.navigateTo(RouterMap.BILL_LIST) 即可跳转，完全不感知目标页面的具体路径和所在模块。

推荐参考文档

• 路由解耦设计模式
• router.pushUrl API 参考
• Navigation + NavPathStack 导航文档