riverpod-3-0-migration

Riverpod — 从 2.0 迁移到 3.0

如需查看完整的变更和亮点列表，请参阅 Riverpod 官方文档（Riverpod 3.0 有哪些新内容）。本技能总结了主要迁移步骤。

自动重试

在 3.0 中，失败的提供程序默认会重试。要全局禁用：

ProviderScope(retry: (retryCount, error) => null, child: MyApp())
// or ProviderContainer(retry: (retryCount, error) => null)

要按提供程序禁用，请在定义提供程序时传入 retry: (retryCount, error) => null（或在代码生成中使用 @Riverpod(retry: ...)）。请参阅 riverpod-retry。

不在视图中的提供程序会暂停

不可见（例如位于屏幕外）的组件中的监听器默认会暂停。没有全局开关。若要避免某个子树暂停，请将其包装在 TickerMode(enabled: true, child: ...) 中，这样其中的 Consumer 就不会遵循暂停行为。

旧版提供程序（StateProvider、StateNotifierProvider、ChangeNotifierProvider）

这些提供程序已移至旧版导入路径。它们并未移除，但不再推荐使用。若要继续使用：

import 'package:flutter_riverpod/legacy.dart';
// or hooks_riverpod/legacy.dart, riverpod/legacy.dart

更新使用 ==

现在所有提供程序都使用 == 筛选更新（不再使用 identical）。StreamProvider / StreamNotifier 的值也会使用 == 进行比较。若要自定义，可在 Notifier 上重写 updateShouldNotify(previous, next)（例如，返回 true 以始终触发通知）。

ProviderObserver API 变更

Observer 方法现在接收单个 ProviderObserverContext（包含 container、provider 和可选的 mutation），而不是分别接收 (provider, value, container) 参数。请更新方法签名，例如：

• didAddProvider(ProviderObserverContext context, Object? value)（其他回调也类似）。

Ref 简化；移除 Ref 子类

• Ref 不再有类型参数。请统一使用 Ref（例如，在代码生成中将 MyProviderRef 替换为 Ref）。
• ProviderRef.state、Ref.listenSelf、FutureProviderRef.future 已移至 Notifier/AsyncNotifier：请改用 Notifier.state、Notifier.listenSelf、AsyncNotifier.future，不要在 ref 上调用。如果需要这些功能，请使用基于类的 Notifier/AsyncNotifier，并在 notifier 上调用它们。

移除 AutoDispose 类型名称

仍支持 AutoDispose，但单独的类型名称（例如 AutoDisposeProvider、AutoDisposeNotifier）已统一。请使用具有相同行为的 Provider、Notifier 等。迁移时，请在类型名称中区分大小写地将 AutoDispose 替换为空字符串。

移除 Family Notifier 类型

FamilyNotifier、FamilyAsyncNotifier、FamilyStreamNotifier 已移除。请改用 Notifier / AsyncNotifier / StreamNotifier，并通过构造函数传入参数（并将其存储在字段中）。从 build 中移除参数；build() 不再接收 family 参数。示例：

• 之前：FamilyNotifier<int, String>，其中 int build(String arg)。
• 之后：Notifier<int>，带有构造函数 MyNotifier(this.arg) 和 final String arg;，并使用 arg 的 int build()。

ProviderException

当提供程序抛出异常时，该异常会被包装在 ProviderException 中。如果你捕获的是原始类型（例如 on NotFoundException），请改为 on ProviderException catch (e)，并检查 e.exception is NotFoundException。如果你只使用 AsyncValue 和 value.hasError / value.error，则无需更改。

总结

• 重试：通过作用域/容器或提供程序上的 retry 禁用。
• 暂停：在不希望暂停的位置使用 TickerMode(enabled: true)。
• 旧版：对 StateProvider / StateNotifierProvider / ChangeNotifierProvider 使用 flutter_riverpod/legacy.dart（或等效导入路径）。
• Ref：使用普通的 Ref；将 state / listenSelf / future 移至 Notifier/AsyncNotifier。
• AutoDispose：从类型名称中移除“AutoDispose”。
• Family Notifier：使用带构造函数参数的 Notifier/AsyncNotifier；build() 不带参数。
• 错误：需要获取原始类型时，捕获 ProviderException 并检查 exception。

如需了解版本亮点和更多详情，请参阅 Riverpod 官方文档。