flutter-riverpod-arch

Flutter Riverpod 架构

目标

使用 Feature-First 目录结构、Riverpod（配合代码生成）进行状态管理，并使用 flutter_hooks / HookConsumerWidget 组合 UI，构建可扩展的 Flutter 应用。该架构是一种受领域驱动设计和整洁架构启发的轻量级方案。其设计理念分为三层——表示层、领域层和基础设施层；本技能中的代码级命名分别为 UI、UseCase 和 Repository。数据源访问封装在 Repository 中。Repository 提供程序使用 @Riverpod(keepAlive: true)，屏幕作用域状态使用 @riverpod。

层级映射（权威依据）

设计理念	代码级命名
表示层	UI
领域层	UseCase
基础设施层	Repository

决策逻辑

判断任务属于 UI、UseCase 还是 Repository，确定它是特定功能专用还是共享的，并选择合适的 Riverpod 作用域。

结构和命名请参阅 architecture.md，Repository/UseCase 的放置位置请参阅 providers.md，提供程序作用域规则请参阅 riverpod.md。

指南

1. 规划功能结构

确定功能，确认实现是共享的还是仅适用于特定功能，并在编码前将文件放入正确的层级。

目录结构和命名请参阅 architecture.md。

2. 实现 Repository 层

在 Repository 层实现 Repository 代码，并遵循 Repository 提供程序的 Riverpod/提供程序规则。

Repository 实现细节请参阅 providers.md，提供程序作用域规则请参阅 riverpod.md。

3. 实现 UseCase 层

在 UseCase 层实现 UseCase 代码，用于验证、编排以及面向 UI 的状态变更。

UseCase 模式请参阅 providers.md，提供程序作用域规则请参阅 riverpod.md。

4. 使用 HookConsumerWidget 构建 UI

按照本技能要求的模式，在表示层构建 UI。

页面和组件结构请参阅 presentation.md，ref.watch / ref.read 的用法请参阅 riverpod.md，按钮和光标规则请参阅 button.md。

5. 实现响应式布局

应用本技能定义的响应式布局规则。

断点策略和响应式布局模式请参阅 responsive.md。

6. 编写测试

使用本技能采用的测试模式，测试 Repository、UseCase、控制器和组件的行为。

测试结构、覆盖和 fake/mock 模式请参阅 testing.md。

约束

• 优先使用 HookConsumerWidget： 此技能使用 HookConsumerWidget（配合 flutter_hooks）实现所有有状态页面和复杂组件。对于不涉及 Riverpod 交互、状态完全局限于本地的 UI，可以使用 StatefulWidget。
• 不要在 build 中使用 ref.read()： ref.read() 只能出现在事件处理程序或回调中，不能放在 build 方法的顶部以派生响应式 UI 状态。
• 不要在事件处理程序中使用 ref.watch()： ref.watch() 只能出现在 build() 或 provider 的 build() 方法中。
• View 中不得包含业务逻辑： Widget 类只能包含布局、条件渲染和导航。所有数据转换和验证都必须放在 Use Case 或 Repository 中。
• 列表模式： 遵循 list.md 中定义的列表和 sliver 规则。
• 避免仅用于设置样式的按钮包装组件： 不要创建唯一用途是应用固定按钮样式的自定义包装组件。如果需要封装加载状态或提交流程等行为，则可以使用包装组件。
• 使用有针对性的 MediaQuery 静态方法： 优先使用 MediaQuery.sizeOf、MediaQuery.paddingOf、MediaQuery.orientationOf 等方法，而不是 MediaQuery.of(context)，以避免不必要的重建。
• 不要使用 LayoutBuilder 设置页面级断点： 使用 ResponsiveLayout（它使用 MediaQuery.sizeOf），确保布局决策基于实际屏幕宽度，而不是父级约束。
• macOS/Web 上必须设置鼠标光标： 每种 Button 变体都必须包含 enabledMouseCursor: SystemMouseCursors.click。每个 InkWell 都必须包含 mouseCursor: SystemMouseCursors.click。
• 必须运行代码生成： 添加或修改 @riverpod 注解后，务必运行 dart run build_runner build。
• 命名约定： 文件和目录使用 snake_case；类使用 UpperCamelCase；页面类以 Page 结尾；repository 类以 Repository 结尾；use case 类使用动词-名词格式（例如，FetchPosts、CreatePost）。

参考文件

• architecture.md — 项目结构、目录布局、命名约定
• providers.md — Repository 和 use case 实现模式
• riverpod.md — Provider 类型、ref.watch 与 ref.read、缓存、代码生成
• presentation.md — 页面结构、导航、hooks 用法、错误处理
• testing.md — 测试模式、模拟策略、ProviderContainer 用法
• button.md — 按钮模式、styleFrom、macOS/Web 的悬停光标
• list.md — ListView.builder、下拉刷新、使用 Slivers 实现分页
• responsive.md — 断点、ResponsiveLayout、平台专属布局