跨平台开发 / 系统课时

统一 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 只负责读取状态、渲染界面和触发动作,不直接拼装数据源。

Riverpod 功能域中的职责与依赖方向

这种分层不要求每层都必须单独一个文件。只有当职责已经独立、会被多个对象引用或文件明显变长时再拆分;小功能把 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 与代码生成流程;重点是观察命名与职责,而不是演示网络访问。

dart
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 项目即使继续扩张也不容易失控。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

统一 Provider 命名和文件边界

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通