跨平台开发 / 系统课时
识别 StateNotifier 迁移场景
识别 StateNotifier 迁移场景
旧项目里常见 StateNotifierProvider,它并不会因为 Riverpod 升级就立刻失效,但在 Riverpod 3 中已归入 legacy API,新代码更推荐 Notifier 或 AsyncNotifier。本节重点不是“全部重写”,而是识别值得迁移的时机,并选择同步或异步的目标模型。
学习目标
- 判断现有
StateNotifierProvider是否需要立即迁移 - 根据初始化方式选择
Notifier或AsyncNotifier - 用低风险顺序完成单个状态单元的迁移与验证
先判断是否值得迁移
Riverpod 3 仍保留 StateNotifierProvider,只是把它与 StateProvider、ChangeNotifierProvider 一起放入 legacy 导入中。因此,稳定运行且近期不会修改的模块没有必要为了“追新”一次性重写。
更适合迁移的信号包括:正在修改该功能;初始化逻辑散落在 Provider 工厂与 StateNotifier 构造函数;Notifier 需要直接通过 ref 观察其他 Provider;异步加载还在手工维护 isLoading、error 等字段;团队准备统一到代码生成 API。
用状态初始化方式选择目标
选择目标类型时,先看状态的初始值如何得到。同步即可得到初始状态,并且后续会响应用户动作时,使用 Notifier<T>。初始状态需要等待网络、数据库或其他 Future 时,优先使用 AsyncNotifier<T>,让加载、错误与数据统一通过 AsyncValue<T> 表达。

如果对象只计算一个值、没有对外的修改方法,还可以进一步考虑函数式 Provider,而不是机械地把每个 StateNotifier 都换成类式 Notifier。
看懂旧写法与新写法的差别
下面两个片段表达同一个同步计数器。旧写法依赖 StateNotifier 构造函数设置初值,Provider 工厂负责创建对象;新写法把初始状态与依赖读取集中到 build(),代码生成负责产生 Provider。片段示例依赖项目已经配置对应 Riverpod 包与代码生成。
旧写法在 Riverpod 3 项目中通常来自 legacy API:
class CounterNotifier extends StateNotifier<int> {
CounterNotifier() : super(0);
void increment() {
state++;
}
}
final counterProvider =
StateNotifierProvider<CounterNotifier, int>((ref) {
return CounterNotifier();
});迁移为代码生成的 Notifier 后:
import 'package:riverpod_annotation/riverpod_annotation.dart';
part 'counter.g.dart';
@riverpod
class Counter extends _$Counter {
@override
int build() => 0;
void increment() {
state++;
}
}代码生成后仍可围绕 counterProvider 读取状态,并通过 counterProvider.notifier 调用 increment()。验证重点不是比较类名,而是确认原有页面能看到相同初值、执行同一动作后得到相同状态变化。
异步状态不要照搬同步迁移
如果旧 StateNotifier 构造后还会调用 _load(),并自己维护 loading、data、error 三套字段,通常应直接迁移到 AsyncNotifier。它的 build() 可以返回 Future<T>,Riverpod 会把加载、成功和失败表示为 AsyncValue<T>,避免再造一套异步状态协议。
迁移时不要把旧构造函数中的副作用原样搬进新构造函数。Notifier 与 AsyncNotifier 的初始化逻辑应进入 build();依赖其他 Provider 时使用 ref.watch 或 ref.read,清理资源则使用 ref.onDispose。这样生命周期与依赖关系都集中在同一个对象内部。
用最小改动验证迁移
一次只迁移一个 Provider。先记录旧实现的可观察行为,例如初始状态、一次成功操作、一次失败操作和页面重建后的状态;再替换实现并运行现有测试。若原 Provider 名称保持一致,多数 ref.watch(counterProvider) 调用可以不动,真正需要检查的是 .notifier 暴露的方法、异步状态类型以及依赖生命周期。
对于缺少测试、业务规则复杂或近期必须上线的 legacy 模块,可以先保留 StateNotifierProvider,等功能进入正常迭代时再迁移。迁移的价值来自更集中的初始化与依赖模型,而不是单纯把类名换成新的 API。