跨平台开发 / 系统课时
统一 Provider 命名和文件边界
统一 Provider 命名和文件边界
当 Provider 数量从几个增长到几十个后,真正难维护的通常不是 Riverpod API,而是“状态入口放哪、业务逻辑由谁负责、名字能否一眼定位”。本节用按功能域拆分的方式,把 provider、notifier 与 repository 的边界固定下来,让查找、测试和重构都更直接。
学习目标
- 建立一致的 Provider 与 Notifier 命名规则
- 区分 provider、notifier、repository 和 UI 的职责边界
- 按功能域组织文件,避免项目扩大后出现全局 provider 大杂烩
先用职责决定名字
Provider 的名字应描述“提供什么”,而不是重复技术类型。使用 Riverpod 代码生成时,标注函数或类的名字会参与生成 Provider 名称,例如 todoRepository 会得到 todoRepositoryProvider,TodoList 会得到 todoListProvider。因此不必把源名称写成 todoRepositoryProvider,否则会产生重复、冗长的命名。
建议把可观察状态命名为业务名,如 sessionProvider、cartProvider、todoListProvider;把基础依赖命名为对象名,如 apiClientProvider、todoRepositoryProvider。Notifier 类则表达它负责维护的状态,而不是笼统使用 AppNotifier、DataNotifier 这类难以搜索的名字。
把四类职责分开
Repository 负责访问远端 API、数据库或本地缓存,并把外部数据转换成领域对象。Provider 负责把依赖注册到 Riverpod 容器。Notifier 负责组合依赖、维护可变状态并暴露用户动作。Widget 只负责读取状态、渲染界面和触发动作,不直接拼装数据源。

这种分层不要求每层都必须单独一个文件。只有当职责已经独立、会被多个对象引用或文件明显变长时再拆分;小功能把 provider 与很短的 notifier 放在同一个 application 文件中也完全可以。
按功能域组织文件
相比把所有 Provider 都塞进 providers/,更推荐先按业务功能分组,再在功能内部按职责拆分。例如 todo 功能可以使用 data/todo_repository.dart、application/todo_list.dart、presentation/todo_page.dart。这样删除一个功能时,相关状态、数据访问和界面基本位于同一目录。
文件名也应跟随主要职责。一个文件若主要声明 TodoRepository,就叫 todo_repository.dart;若主要维护 todo 列表状态,就叫 todo_list.dart 或 todo_list_notifier.dart。不要用 providers.dart、common.dart、utils.dart 长期承载不断增长的业务状态。
下面是一个使用代码生成的片段示例,依赖项目已配置 riverpod_annotation 与代码生成流程;重点是观察命名与职责,而不是演示网络访问。
import 'package:riverpod_annotation/riverpod_annotation.dart';
part 'todo_list.g.dart';
abstract interface class TodoRepository {
Future<List<String>> fetchTodos();
}
class InMemoryTodoRepository implements TodoRepository {
@override
Future<List<String>> fetchTodos() async => ['write tests', 'ship app'];
}
@riverpod
TodoRepository todoRepository(Ref ref) {
return InMemoryTodoRepository();
}
@riverpod
class TodoList extends _$TodoList {
@override
Future<List<String>> build() {
// Notifier 只编排状态与依赖,不承担数据源实现。
return ref.watch(todoRepositoryProvider).fetchTodos();
}
}代码生成后,应得到可由调用方使用的 todoRepositoryProvider 与 todoListProvider。验证时打开分析器即可:若两个生成符号都能解析,并且 UI 无需直接创建 InMemoryTodoRepository,说明依赖边界已经生效。
控制跨文件依赖方向
整理文件后,还要检查依赖方向。Presentation 可以依赖 application;application 可以依赖 data 层暴露的抽象与 Provider;data 不应反向 import 页面或 Widget。跨 feature 共用的 HTTP 客户端、认证会话等基础设施可以放到更高层的 core 目录,但不要因为“以后可能复用”就提前把业务 Provider 全部上移。
判断一个对象放哪里时,可以问一句:如果明天把页面换掉,它还应该存在吗?Repository 通常应该存在;Notifier 往往仍然存在;仅用于当前页面展示的临时 UI 状态则应尽量留在页面附近。文件边界最终服务于变更边界,名字则服务于快速定位,两者统一后,Riverpod 项目即使继续扩张也不容易失控。