NavGraph 设计原则：图形化定义、嵌套图、全局动作与目标匹配策略

NavGraph 是 Navigation 组件的核心编排层，它不仅仅是一个目的地清单，更是一个有向图结构，定义了用户所有可能的路径。本章深入三个设计原则：图形化定义、嵌套图和全局动作，并剖析底层目标匹配策略的架构边界。理解这些原则，是构建可维护、模块化导航方案的前提。

3.1 模块边界与分层职责

在架构方案中，NavGraph 处于路由编排层，它不感知业务逻辑，仅负责定义从“源目的地”到“目标目的地”的转移条件。其模块边界如下图所示：

3.2 图形化定义：XML 的架构价值

Navigation 组件强制使用 XML 图形化定义（nav_graph.xml），这不仅仅是配置，更是架构约束：

• 模块边界显式化：所有目的地（Destination）和动作（Action）以声明式清单存在，避免代码中隐式跳转。
• 可视化预览：Android Studio 可直接渲染 NavGraph，便于架构评审与沟通。
• 编译期校验：无效的 ID 引用、缺失的起始目的地、循环依赖会在编译时暴露。

对比纯代码定义（Kotlin DSL），XML 图形化定义在团队协作和长期维护方面具有显著优势：

3.3 嵌套图：模块化职责的物理标识

嵌套图（Nested Graph）是 NavGraph 实现模块化的核心手段。它将一组逻辑相关的目的地包裹在独立的 <navigation> 标签内，形成自包含的子图。

典型结构示例：

<navigation xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/root_graph"
    app:startDestination="@id/onboarding_flow">

    <!-- 嵌套图：用户引导流程 -->
    <navigation
        android:id="@+id/onboarding_flow"
        app:startDestination="@id/welcome_screen">
        <fragment
            android:id="@+id/welcome_screen"
            android:name=".WelcomeFragment" />
        <fragment
            android:id="@+id/login_screen"
            android:name=".LoginFragment" />
        <action
            android:id="@+id/action_to_login"
            app:destination="@id/login_screen" />
    </navigation>

    <!-- 嵌套图：主功能流程 -->
    <navigation
        android:id="@+id/main_flow"
        app:startDestination="@id/home_screen">
        <fragment
            android:id="@+id/home_screen"
            android:name=".HomeFragment" />
        <fragment
            android:id="@+id/details_screen"
            android:name=".DetailsFragment" />
    </navigation>

    <!-- 全局动作：从引导流程跳转到主流程 -->
    <action
        android:id="@+id/global_to_home"
        app:destination="@id/main_flow" />

</navigation>

3.4 全局动作与局部动作的职责划分

动作（Action）分为两种作用范围：局部动作（定义在 <fragment> 内）和全局动作（定义在 <navigation> 根下）。

架构设计中，全局动作是跨模块桥梁，常用于非直接关联的目的地之间：

• 局部动作： 适用于同一个嵌套图内的流程跳转，紧耦合。
• 全局动作： 适用于跨嵌套图、跨模块跳转，解耦。

在多层嵌套中，局部动作的可见性受限于其所属的嵌套图。如果试图在嵌套图 B 中引用嵌套图 A 的局部动作，编译期会报错——这正是架构强制的模块边界约束。

3.5 目标匹配策略：从 ID 到 Deep Link 的解析链路

NavController 在收到导航请求后，会按照以下优先级进行目标匹配：

1. ID 精确匹配： 检查 NavGraph 中是否存在完全匹配的 android:id。
2. 嵌套图内部匹配： 如果当前位于某个嵌套图内，优先在该嵌套图内查找动作和目标。
3. 全局动作匹配： 逐级向上查找父级 NavGraph 中的全局动作。
4. Deep Link 匹配： 解析 URI 和 intent 数据，匹配 <deepLink> 定义。
5. 回退栈匹配： 如果以上都未命中，且存在 popUpTo 行为，则回退栈中寻找。

3.6 落地步骤与验收标准

为了将 NavGraph 设计原则落地到项目中，建议遵循以下实施步骤：

落地步骤

1. 划分模块边界： 根据业务模块（如“注册”、“主页”、“设置”）创建独立的 NavGraph XML 文件。
2. 定义嵌套图： 在每个 XML 文件中将模块内部流程打包为 <navigation> 并设置 app:startDestination。
3. 声明全局动作： 在根导航图（nav_graph.xml）中声明所有跨模块动作。
4. 关联 Deep Link： 为需要外部唤醒的目的地添加 <deepLink>，并在匹配策略中测试。
5. 编译期校验： 执行 ./gradlew :app:mergeDebugResources 以触发 NavGraph 资源合并校验。

验收标准