一、前言

在前三篇专栏中，我们完成了心晴驿站的项目立项规划、环境搭建、技术选型，以及基于 Stage 模型的四层分层架构整体落地。目前项目已经具备了规范的目录结构、清晰的层级职责、隐私安全架构底座，完全满足业务开发的前置条件。

从本篇开始，我们正式进入核心技术实现模块。路由作为应用页面跳转、页面通信、业务流转的核心枢纽，是所有业务功能的基础。混乱的路由写法会导致页面跳转失控、参数传递异常、页面栈堆积、返回逻辑错乱，严重影响应用体验与稳定性。

本文将基于鸿蒙 Stage 模型，结合心晴驿站「首页、心理测评、治愈游戏、个人中心」四大业务页面，从零搭建一套统一、可维护、可扩展、低耦合的全局路由架构。摒弃原生零散的路由API调用方式，实现路由统一管理、优雅传参、页面栈控制、异常拦截，适配长期迭代开发，为后续测评、游戏、树洞等核心功能开发铺路。

二、鸿蒙Stage模型路由核心机制

2.1 Stage模型路由核心原理

鸿蒙 Stage 模型中，页面路由能力由官方 @ohos.router 模块提供，基于**页面栈（Page Stack）**机制管理页面生命周期。所有页面均以栈结构进行压入、弹出、替换操作，区别于老旧 FA 模型，Stage 模型路由具备更严谨的栈管理、更规范的生命周期回调、更稳定的页面跳转逻辑。

原生路由四大基础能力：

• pushUrl：压入新页面，保留当前页面，可返回上一级（适用于详情页、结果页跳转）

• replaceUrl：替换当前页面，销毁当前页面栈（适用于登录跳转、首页重定向）

• back：页面出栈，返回上一级页面，支持自定义返回层数

• clearAll：清空所有页面栈，仅保留目标页面（适用于底部导航切换、首页复位）

2.2 原生路由开发的痛点（项目初期踩坑）

在项目初始开发阶段，若直接在业务页面硬编码路由地址、零散调用原生路由API，会出现大量问题，也是鸿蒙新手高频踩坑点：

• 路由路径硬编码，页面地址修改需要全局替换，维护成本极高；

• 页面跳转逻辑分散在各个页面，代码耦合严重，难以统一管控；

• 参数传递无统一规范，参数丢失、类型不匹配、空参数报错频发；

• 底部导航多页面切换导致页面栈堆积，内存占用持续升高；

• 无统一异常拦截，页面跳转失败无兜底提示，用户体验差。

针对以上痛点，心晴驿站采用路由配置中心化 + 方法封装统一化 + 参数校验规范化的架构方案，彻底解决原生路由的开发弊端。

三、心晴驿站路由整体架构设计

3.1 整体设计思路

结合项目四大核心业务模块，我们将路由架构分为三层，实现配置、封装、调用完全解耦：

1. 路由配置层（constant）：统一管理所有页面路径，常量定义，杜绝硬编码；

2. 路由封装层（utils）：封装跳转、传参、返回、清空栈通用方法，统一拦截异常；

3. 业务调用层（pages）：业务页面直接调用封装方法，无需感知底层路由逻辑。

3.2 项目路由页面梳理

根据心晴驿站业务结构，梳理所有核心路由页面，分为底部主页面与二级业务页面：

1. 底部核心主页面（常驻页面）

• 首页：首页主页、树洞功能页入口

• 测评页：测评列表、极速心情自测入口

• 游戏页：四大治愈游戏总入口

• 我的页：个人记录、设置、免责说明

2. 二级业务跳转页面

• PHQ-9抑郁测评答题页、测评结果页

• GAD-7焦虑测评答题页、测评结果页

• 吹泡泡、彩虹收集、雨声冥想、涂色填图游戏详情页

• 历史测评记录详情页

四、路由架构代码落地（可直接复用）

4.1 第一步：路由常量统一配置

在 constant/route_const.ets 中统一维护所有页面路径，全局复用，后续页面更名、路径调整仅需修改此处。

/**
 * 路由路径常量配置
 * 心晴驿站全局页面路由统一管理
 */
export default class RoutePath {
  // 底部主页面
  static readonly INDEX_PAGE: string = 'pages/index/index'
  static readonly EVAL_PAGE: string = 'pages/evaluate/evaluate'
  static readonly GAME_PAGE: string = 'pages/game/game'
  static readonly MINE_PAGE: string = 'pages/mine/mine'

  // 测评二级页面
  static readonly PHQ9_TEST_PAGE: string = 'pages/evaluate/phq9'
  static readonly GAD7_TEST_PAGE: string = 'pages/evaluate/gad7'
  static readonly TEST_RESULT_PAGE: string = 'pages/evaluate/result'

  // 游戏二级页面
  static readonly BUBBLE_GAME_PAGE: string = 'pages/game/bubble'
  static readonly RAINBOW_GAME_PAGE: string = 'pages/game/rainbow'
  static readonly RAIN_MEDITATION_PAGE: string = 'pages/game/rain'
  static readonly COLOR_GAME_PAGE: string = 'pages/game/color'
}
    

4.2 第二步：全局路由工具类封装

在 utils/route_utils.ets 封装通用路由方法，支持带参跳转、无参跳转、页面替换、返回上页、清空栈跳转，同时加入全局异常捕获，避免跳转报错导致应用闪退。

import router from '@ohos.router'

/**
 * 全局路由工具类
 * 统一封装页面跳转逻辑，规范传参、统一异常处理
 */
export class RouteUtils {
  /**
   * 普通页面跳转（保留页面栈，可返回）
   * @param url 页面路由地址
   * @param params 跳转参数
   */
  static push(url: string, params?: Object) {
    try {
      router.pushUrl({
        url: url,
        params: params
      })
    } catch (e) {
      console.error('页面跳转失败：', JSON.stringify(e))
    }
  }

  /**
   * 替换当前页面（销毁当前页面，不可返回）
   * @param url 页面路由地址
   * @param params 跳转参数
   */
  static replace(url: string, params?: Object) {
    try {
      router.replaceUrl({
        url: url,
        params: params
      })
    } catch (e) {
      console.error('页面替换失败：', JSON.stringify(e))
    }
  }

  /**
   * 返回上一级页面
   * @param delta 返回页面层数
   */
  static back(delta: number = 1) {
    try {
      router.back(delta)
    } catch (e) {
      console.error('页面返回失败：', JSON.stringify(e))
    }
  }

  /**
   * 清空页面栈并跳转（用于底部导航切换）
   * @param url 目标页面地址
   */
  static clearAllPush(url: string) {
    try {
      router.clearAllUrl({
        url: url
      })
    } catch (e) {
      console.error('清空栈跳转失败：', JSON.stringify(e))
    }
  }
}
    

4.3 第三步：页面参数接收规范

针对测评结果页、游戏详情页等需要接收参数的页面，统一参数获取方式，配合 TypeScript 类型约束，杜绝参数类型报错。

import router from '@ohos.router'

// 获取路由参数
export function getRouteParams<T>(): T {
  return router.getParams() as T
}

// 测评结果页参数类型约束
export interface TestResultParams {
  score: number
  level: string
  desc: string
}
    

五、核心业务场景路由落地实战

5.1 底部导航路由切换（核心场景）

心晴驿站四大底部Tab切换，采用 clearAllPush 清空页面栈跳转，彻底解决多次切换导致的页面栈堆积、内存占用过高问题，保证底部页面常驻、唯一存在。

// 底部导航点击切换逻辑
onTabClick(index: number) {
  switch (index) {
    case 0:
      RouteUtils.clearAllPush(RoutePath.INDEX_PAGE)
      break
    case 1:
      RouteUtils.clearAllPush(RoutePath.EVAL_PAGE)
      break
    case 2:
      RouteUtils.clearAllPush(RoutePath.GAME_PAGE)
      break
    case 3:
      RouteUtils.clearAllPush(RoutePath.MINE_PAGE)
      break
  }
}
    

5.2 测评页面带参跳转（高频业务场景）

完成测评答题后，携带分数、评级、描述参数跳转至结果页，参数全程类型校验，保证数据传递稳定。

// 测评完成跳转结果页
goResultPage(score: number, level: string, desc: string) {
  RouteUtils.push(RoutePath.TEST_RESULT_PAGE, {
    score,
    level,
    desc
  })
}
    

5.3 二级页面返回逻辑

游戏页面、测评详情页点击返回，统一调用 back 方法，极简可控，适配所有二级页面。

backClick() {
  RouteUtils.back()
}

六、路由架构优化亮点与优势

6.1 解决耦合问题

所有路由路径统一常量管理，业务页面无需硬编码路径，路由逻辑与UI页面完全解耦，符合高内聚、低耦合的架构设计原则。

6.2 规范参数传递

通过 TypeScript 接口约束参数类型，从语法层面避免参数缺失、类型错误问题，大幅降低页面跳转异常概率。

6.3 优化内存性能

底部导航采用清空栈跳转策略，杜绝页面重复入栈堆积，有效控制应用内存占用，保证轻量化、低功耗的产品特性。

6.4 统一异常兜底

所有路由方法内置 try-catch 异常捕获，跳转失败打印日志，避免页面跳转报错导致应用闪退，提升应用稳定性。

6.5 支持快速迭代扩展

后续新增页面、新增业务跳转，仅需在路由常量中新增路径，无需重构整体路由逻辑，可扩展性极强。

七、路由开发踩坑复盘

7.1 页面栈堆积问题

问题现象：初期底部Tab使用普通push跳转，多次切换页面后，页面栈层层叠加，返回会逐层回退，体验极差，且内存持续升高。

解决方案：底部常驻页面统一使用 clearAllPush 清空栈跳转，保证四大主页面唯一存在，彻底解决栈堆积问题。

7.2 路由参数丢失问题

问题现象：直接通过临时对象传参，页面刷新后偶尔出现参数丢失、undefined 报错。

解决方案：统一封装参数获取方法，强制类型校验，规范传参格式，彻底解决参数不稳定问题。

7.3 路由路径书写不规范

问题现象：多人/长期开发下，路径大小写、书写格式不统一，导致部分机型跳转失效。

解决方案：全局路由常量统一管理，所有页面强制调用常量路径，杜绝手写路径。

八、本篇总结与下篇预告

本篇我们完成了心晴驿站全局路由架构的完整设计与实战落地，基于鸿蒙 Stage 模型原生路由能力，通过「常量配置+工具封装+规范传参」的三层架构，解决了原生路由散乱、耦合、易报错、内存溢出等核心问题，搭建了一套适配心理健康应用、可长期迭代的标准化路由体系。

路由作为所有业务功能的流转基础，为本系列后续的首页UI开发、测评功能、游戏交互、树洞功能开发提供了稳定的底层支撑。

下篇预告（第五篇）：ArkUI组件化架构实战，详解心晴驿站全局公共组件封装规范、组件复用与解耦设计，带你搭建项目通用卡片、导航栏、空白占位、弹窗组件，实现UI组件高度复用。