vgv-navigation

用途

vgv-navigation 是 verygoodopensource/vgv-ai-flutter-plugin 中针对 Flutter 应用导航与路由的实践规范，基于 GoRouter——Flutter 团队推荐的、构建于 Navigator 2.0 API 之上的路由包。它用于统一 Flutter 项目中的路由定义、导航调用、参数传递、重定向与测试方式。

核心标准

以下标准适用于所有导航工作：

所有导航使用 package:go_router，绝不使用原始 Navigator 2.0 或 Navigator 1.0 的 push/pop。
使用 @TypedGoRoute 注解实现类型安全路由，绝不在路由定义中使用原始字符串路径。
优先使用 go() 而非 push()；仅当需要从目标页面返回数据时才使用 push()。
绝不使用 extra 参数——它会破坏深链接，且无法在 Web 上工作。
使用层级式子路由以实现正确的返回导航，将路由组织为父子树结构，而非扁平列表。
URL 单词分隔使用连字符，绝不在 URL 路径中使用下划线或驼峰命名。
按路由名称导航，而非原始路径字符串，以将导航与路径变更解耦。
使用 BuildContext 扩展进行导航，优先使用 context.goNamed() 而非 GoRouter.of(context).goNamed()。

路由组织

以逻辑父子关系层级化组织路由。子路由确保应用栏返回按钮正确显示，并保持 URL 整洁。

层级结构（推荐）：

/flutter
  /flutter/news
  /flutter/chat
  /flutter/articles
    /flutter/articles?category=all
    /flutter/article/:id
/android
  /android/news
  /android/chat

扁平结构（避免）：

/flutter-news
/flutter-chat
/android-news
/android-chat

层级式子路由会自动产生正确的返回导航——当用户位于 /flutter/news 时，返回按钮会导航到 /flutter。

类型安全路由

使用 @TypedGoRoute 注解配合 GoRouteData 类，消除拼写错误和手动参数转换。go_router_builder 包在构建时生成类型安全的路由辅助代码。

基本路由示例：

@TypedGoRoute<CategoriesPageRoute>(
  name: 'categories',
  path: '/categories',
)
@immutable
class CategoriesPageRoute extends GoRouteData {
  const CategoriesPageRoute({
    this.size,
    this.color,
  });

  final String? size;
  final String? color;

  @override
  Widget build(BuildContext context, GoRouterState state) {
    return CategoriesPage(size: size, color: color);
  }
}

带子路由的示例：

@TypedGoRoute<FlutterPageRoute>(
  name: 'flutter',
  path: '/flutter',
  routes: [
    TypedGoRoute<FlutterNewsPageRoute>(
      name: 'flutterNews',
      path: 'news',
    ),
    TypedGoRoute<FlutterArticlesPageRoute>(
      name: 'flutterArticles',
      path: 'articles',
      routes: [
        TypedGoRoute<FlutterArticlePageRoute>(
          name: 'flutterArticle',
          path: 'article/:id',
        ),
      ],
    ),
  ],
)
@immutable
class FlutterPageRoute extends GoRouteData {
  const FlutterPageRoute();

  @override
  Widget build(BuildContext context, GoRouterState state) {
    return const FlutterPage();
  }
}

导航方法

go() 与 push() 对比：

方法	URL 更新	返回按钮	使用场景
go()	是	应用栏	屏幕之间的标准导航
push()	否	系统	需要从被弹出路由返回数据时

使用 go()（默认）：

const CategoriesPageRoute(size: 'small', color: 'blue').go(context);

使用 go() 可确保当前路由有父级可返回时，应用 AppBar 中的返回按钮正常显示。

使用 push()（仅用于返回数据）：

final result = await DialogPageRoute().push<String>(context);

仅当路由必须返回数据时（例如收集用户输入的对话框）才使用 push()。在 Web 上，push() 不会更新地址栏。

BuildContext 扩展：

// 推荐
context.goNamed('flutterNews');

// 避免
GoRouter.of(context).goNamed('flutterNews');

参数策略

使用路径参数（:id）进行资源标识，使用查询参数（?category=all）进行可选过滤。绝不使用 extra——它会破坏深链接，且无法在 Web 上工作。完整示例（路径参数、查询参数以及为何禁止 extra）见 references/parameters.md。

重定向

重定向可应用于根路由器级别（例如身份验证守卫）和单个路由级别（例如授权守卫）。父级重定向先于子级重定向执行。根级与路由级重定向示例见 references/redirects.md。

测试

使用 package:mocktail 模拟 GoRouter，并在 widget 测试中将组件包裹在 InheritedGoRouter 中。通过构造带有目标重定向逻辑的 GoRouter 并断言结果页面来测试重定向。模拟 GoRouter 与测试重定向的示例见 references/testing.md。

常见模式

添加新路由：

创建页面组件（若使用 Bloc，则遵循 Page/View 模式）。
定义带 @TypedGoRoute 注解的 GoRouteData 类。
将其作为子路由添加到合适的父路由下。
运行 dart run build_runner build --delete-conflicting-outputs 重新生成路由辅助代码。
使用生成的类型安全路由类进行导航。

深链接设置：

以有意义的 URL 路径层级化组织路由。
使用路径参数进行资源标识。
使用查询参数进行过滤——绝不使用 extra。
按路由名称导航，这样路径重构不会破坏链接。
通过使用目标 URL 启动应用来测试深链接。

嵌套导航（Shell 路由）：

@TypedShellRoute<AppShellRoute>(
  routes: [
    TypedGoRoute<HomePageRoute>(
      name: 'home',
      path: '/home',
    ),
    TypedGoRoute<SettingsPageRoute>(
      name: 'settings',
      path: '/settings',
    ),
  ],
)
class AppShellRoute extends ShellRouteData {
  @override
  Widget builder(BuildContext context, GoRouterState state, Widget navigator) {
    return AppShell(child: navigator);
  }
}

快速参考

包：

包	用途
go_router	构建于 Navigator 2.0 之上的声明式路由
go_router_builder	类型安全路由类的代码生成

命令：

命令	用途
dart run build_runner build --delete-conflicting-outputs	生成类型安全路由辅助代码
dart run build_runner watch --delete-conflicting-outputs	监视变更并重新生成

适用场景与限制

该规范适用于使用 Flutter 与 GoRouter 构建的应用，尤其是需要深链接、Web 支持、类型安全路由与层级化返回导航的项目。限制方面：资料未提供具体的收费、价格、平台支持范围或性能效果数据；extra 参数被明确禁止，push() 在 Web 上不更新地址栏，这些是使用中需注意的约束。