ReaderMX.
搜狐技术产品

再聊 Flutter Riverpod ，注解模式下的 Riverpod 有什么特别之处，还有发展方向

搜恋猫de小郭约 12 分钟

三年前我们通过《Flutter Riverpod 全面深入解析》深入理解了 riverpod 的内部实现，而时隔三年之后，如今Riverpod 的主流模式已经是注解，那今天就让我们来聊聊 riverpod 的注解有什么特殊之处。

前言

在此之前，我们需要先回忆一下，riverpod 最明显的特点是将BuildContext转换成WidgetRef抽象，从而让状态管理不直接依赖BuildContext，所以对应的 Provider 可以按需写成全局对象，而在 riverpod 里，主要的核心对象有：

  • ProviderScope：InheritedWidget实现，共享实例的顶层存在，提供一个ProviderContainer全局共享
  • ProviderContainer：用于管理和保存各种 “Provider” 的 State ，并且支持 override 一些特殊 “Provider” 的行为，还有常见的 read\watch\refesh
  • Ref：提供 riverpod 内的 “Provider” 交互接口，是 riverpod 内 ProviderElementBase 的抽象
  • ProviderElementBase： Ref 的实现，每个 “Provider” 都会有自己的 “Element” ，而构建 “Provider” 时是传入的Create函数会在 “Element” 内通过 "setState" 调用执行，比如StateProvider((ref)=> 0)这里的 ref ，就是内部在 ”Element“ 里通过setState(_provider.create(this));" 的时候传入的 this
  • WidgetRef：替代 FlutterBuildContext的抽象，内部通过继承StatefulWidget实现，作为 BuildContext 的对外替代
Image
❝

所以 "Provider" 里的 Ref和 “Consumer” 的  WidgetRef严格来说是两个不同的东西，只是它们内部都可以获取到  ProviderContainer，从而支持对应 read\watch\refesh 等功能，这也是为什么你在外部直接通过  ProviderContainer也可以全局直接访问到 read\watch\refesh 的原因。

另外，riverpod 内部定义了自己的 「Element」 和 「setState」实现，它们并不是 Flutter 里的 Element 和 setState，所以上面都加了 “”，甚至 riverpod 里的 “Provider” 和 Provider 状态管理库也没有关系， 这么设计是为了贴合 Flutter 本身的 「Element」 和 「setState」概念，所以这也是为什么说 riverpod 是专为 Flutter 而存在的设计。

注解模式

现在 riverpod 更多提倡使用注解模式，注解模式可以让 riverpod 使用起来更方便且规范，从一定程度也降低了使用难度，但是也对初学者屏蔽了不少过去的手写实现，导致在出现问题时新手也可能会相对更懵。

简单函数注解

首先我们看这个简单的代码，我们在main.dart里添加了了一个@riverpod给helloWorld，然后运行flutter pub run build_runner build --delete-conflicting-outputs，可以看到此时生成了对应的main.g.dart文件：

import'package:flutter/material.dart';
import'package:flutter_riverpod/flutter_riverpod.dart';
import'package:riverpod_annotation/riverpod_annotation.dart';
part'main.g.dart';
@riverpod
String helloWorld(Ref ref) {
return'Hello world';
}
classMyAppextendsConsumerWidget{
@override
  Widget build(BuildContext context, WidgetRef ref) {
finalString value = ref.watch(helloWorldProvider);
return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('Example')),
        body: Center(
          child: Text(value),
        ),
      ),
    );
  }
}

我们看main.g.dart文件，可以看到，根据@riverpod的规则，helloWorld会生成一个helloWorldProvider实例让我们在使用时 read/watch/refresh ：

// GENERATED CODE - DO NOT MODIFY BY HAND
part of 'main.dart';
// **************************************************************************
// RiverpodGenerator
// **************************************************************************
String _$helloWorldHash() => r'9abaa5ab530c55186861f2debdaa218aceacb7eb';
/// See also [helloWorld].
@ProviderFor(helloWorld)
final helloWorldProvider = AutoDisposeProvider<String>.internal(
  helloWorld,
  name: r'helloWorldProvider',
  debugGetCreateSourceHash:
constbool.fromEnvironment('dart.vm.product') ? null : _$helloWorldHash,
  dependencies: null,
  allTransitiveDependencies: null,
);
@Deprecated('Will be removed in 3.0. Use Ref instead')
// ignore: unused_element
typedef HelloWorldRef = AutoDisposeProviderRef<String>;
// ignore_for_file: type=lint
// ignore_for_file: subtype_of_sealed_class, invalid_use_of_internal_member, invalid_use_of_visible_for_testing_member, deprecated_member_use_from_same_package

通过生成的代码，我们可以看到：

  • _$helloWorldHash()：它主要是用于提供一个唯一标识，用于追踪 Provider 的来源和状态，它是被debugGetCreateSourceHash所使用，例如在 Debug 模式下 hotload 时，riverpod 会用这个值来判断当前 provider 是否需要重建，比如当你重新生成的时候 hash 值就会出现变化。
  • helloWorldProvider：AutoDisposeProvider的实例，也就是默认情况下@riverpod生成的都是自动销毁的 Provider ，
❝

这里默认使用  AutoDisposeProvider，也是为了更好的释放内存和避免不必需要的内存泄漏等场景，  AutoDisposeProvider内部，在每次  read、invalidate、页面退出、ProviderContainer销毁等场景会自动调用 dispose 。

异步函数注解

接着，如果给helloWorld增加 async ，那么我们得到一个AutoDisposeFutureProvider，同理，如果是async*就会生成一个AutoDisposeStreamProvider：

@riverpod
Future<String> helloWorld(Ref ref) async{
return'Hello world';
}
------------------------------GENERATED CODE---------------------------------
@ProviderFor(helloWorld)
final helloWorldProvider = AutoDisposeFutureProvider<Object?>.internal(
  helloWorld,
  name: r'helloWorldProvider',
  debugGetCreateSourceHash:
constbool.fromEnvironment('dart.vm.product') ? null : _$helloWorldHash,
  dependencies: null,
  allTransitiveDependencies: null,
);

当然，在返回结果使用上会有些差别， 异步的 Provider 会返回一个AsyncValue，或者需要.value获取一个非空安全的对象：

@override
Widget build(BuildContext context, WidgetRef ref) {
final AsyncValue<String> asyncValue = ref.watch(helloWorldProvider);
finalString? value = ref.watch(helloWorldProvider).value;
return MaterialApp(
    home: Scaffold(
      appBar: AppBar(title: const Text('Example')),
      body: Center(
        child: Text(asyncValue.when(
            data: (v) => v,
            error: (_, __) => "error",
            loading: () => "loading")),
      ),
    ),
  );
}

函数注解带参数

当你需要给helloWorld增加参数的时候，此时的helloWorldProvider就不再是一个AutoDisposeFutureProvider实例，它将变成HelloWorldFamily，它是一个Family的实现：

@riverpod
Future<String> helloWorld(Ref ref, String value, String type) async {
return'Hello world $value$type';
}
@override
Widget build(BuildContext context, WidgetRef ref) {
final AsyncValue<String> asyncValue = ref.watch(helloWorldProvider("1", "2"));
finalString? value = ref.watch(helloWorldProvider("1", "2")).value;
}
------------------------------GENERATED CODE---------------------------------
/// See also [helloWorld].
classHelloWorldFamilyextendsFamily<AsyncValue<String>> {
/// See also [helloWorld].
const HelloWorldFamily();
/// See also [helloWorld].
  HelloWorldProvider call(
String value,
String type,
  ) {
return HelloWorldProvider(
      value,
      type,
    );
  }
@override
  HelloWorldProvider getProviderOverride(
covariant HelloWorldProvider provider,
  ) {
return call(
      provider.value,
      provider.type,
    );
  }
staticconstIterable<ProviderOrFamily>? _dependencies = null;
@override
Iterable<ProviderOrFamily>? get dependencies => _dependencies;
staticconstIterable<ProviderOrFamily>? _allTransitiveDependencies = null;
@override
Iterable<ProviderOrFamily>? get allTransitiveDependencies =>
      _allTransitiveDependencies;
@override
String? get name => r'helloWorldProvider';
}
❝

在 Dart 中，call 方法是一个特殊的方法，它可以让一个类的实例像函数一样调用。

说到Family， 它的作用是主要就是支持使用额外的参数构建 Provider，因为前面helloWorld需要传递参数，所以HelloWorldFamily的主要作用，就是提供创建和覆盖需要参数的 Provider，例如前面的：

final AsyncValue<String> asyncValue = ref.watch(helloWorldProvider("1", "2"));
finalString? value = ref.watch(helloWorldProvider("1", "2")).value;

当然，这里你需要注意，不同与前面的helloWorldProvider实例，需要参数的 Provider 需要你每次使用时通过参数构建，而此时你每次调用如helloWorldProvider("1", "2")都是创建了一个全新实例，如果你需要同一个数据源下 read/watch ，那么你应该在调用时共用一个全局helloWorldProvider("1", "2")实例。

如果是不同 Provider 实例，那么你获取到的参数其实是不一样的，因为内部 map 登记的映射关系就是基于 Provider 实例为 key ：

Image

不过对比之下，过去你使用FutureProvider.family只能覆带一个Arg参数，虽然可以通过语法糖传递多个参数，但是终究还是比注解生成的麻烦：

final helloWorldFamily =
    FutureProvider.family<String, (String, String)>((value, type) async {
return'Hello world $value$type';
});

另外，注解生成时，还会动态生成一个对应的 "Element" ，让 Element 支持获取 Provider 的参数，并实现对应build方法，也就是通过 ref 可以获取到相关参数：

mixin HelloWorldRef on AutoDisposeFutureProviderRef<String> {
/// The parameter `value` of this provider.
Stringget value;
/// The parameter `type` of this provider.
Stringget type;
}
class_HelloWorldProviderElement
extendsAutoDisposeFutureProviderElement<String> withHelloWorldRef{
  _HelloWorldProviderElement(super.provider);
@override
Stringget value => (origin as HelloWorldProvider).value;
@override
Stringget type => (origin as HelloWorldProvider).type;
}

最后，带参数之后，生成的_SystemHash也会根据参数动态变化，从而支持 hotload 等场景：

class_SystemHash{
  _SystemHash._();
staticint combine(int hash, int value) {
// ignore: parameter_assignments
    hash = 0x1fffffff & (hash + value);
// ignore: parameter_assignments
    hash = 0x1fffffff & (hash + ((0x0007ffff & hash) << 10));
return hash ^ (hash >> 6);
  }
staticint finish(int hash) {
// ignore: parameter_assignments
    hash = 0x1fffffff & (hash + ((0x03ffffff & hash) << 3));
// ignore: parameter_assignments
    hash = hash ^ (hash >> 11);
return0x1fffffff & (hash + ((0x00003fff & hash) << 15));
  }
}

类注解

接着，我们看@riverpod除了可以注解函数之后，还可以直接注解 class ，只是 class 需要继承_$***一个子类：

@riverpod
classHelloWorldextends_$HelloWorld{
@override
String build() {
return'Hello world';
  }
  changeValue(String value) {
    state = value;
  }
}
@override
Widget build(BuildContext context, WidgetRef ref) {
finalString asyncValue = ref.watch(helloWorldProvider);
  ref.read(helloWorldProvider.notifier).changeValue("next");
}

通过生成代码可以看到，此时生成的是AutoDisposeNotifierProvider，也就是在读取时，可以通过read(****Provider.notifier)去改变状态：

String _$helloWorldHash() => r'52966cfeefb6334e736061e19443e4c8b94160d8';
/// See also [HelloWorld].
@ProviderFor(HelloWorld)
final helloWorldProvider =
    AutoDisposeNotifierProvider<HelloWorld, String>.internal(
  HelloWorld.new,
  name: r'helloWorldProvider',
  debugGetCreateSourceHash:
constbool.fromEnvironment('dart.vm.product') ? null : _$helloWorldHash,
  dependencies: null,
  allTransitiveDependencies: null,
);
typedef _$HelloWorld = AutoDisposeNotifier<String>;

也就是，通过@riverpod注解的 class ，是带有 state 状态的 NotifierProvider ，这是对比注解函数最明显的差异。

而如果注解 class 需要携带参数，那么可以在build上添加需要的参数，最终同样和函数一样会生成一个对应的HelloWorldFamily：

@riverpod
classHelloWorldextends_$HelloWorld{
@override
String build(String value, String type) {
return'Hello world';
  }
  changeValue(String value) {
    state = value;
  }
}

同理，如果你给 build 增加了 async，那么就会生成一个AutoDisposeAsyncNotifierProviderImpl的相关实现：

@riverpod
classHelloWorldextends_$HelloWorld{
@override
  Future<String> build(String value, String type) async {
return'Hello world';
  }
  changeValue(String value) {
final currentValue = state.valueOrNull ?? "";
    state = AsyncData(currentValue + value);
  }
  removeString(String value) {
final currentValue = state.valueOrNull ?? "";
    state = state.copyWithPrevious(AsyncData(currentValue.replaceAll(value, "")));
  }
}

可以看到，在注解 class 下可操作空间是在 build ，并且需要注意的是，当你调用refresh的时候，State 是会被清空，并且重新调用 build。

KeepAlive

那么我们前面说的都是 AutoDispose ，如果我不想他被释放呢？那就是需要用到大写字母开头的@Riverpod，给参数配置上keepAlive: true：

@Riverpod(keepAlive: true)
classHelloWorldextends_$HelloWorld

然后再看输出文件，你就会看到此时HelloWorldProvider继承的是AsyncNotifierProviderImpl而不是AutoDispose了：

classHelloWorldProviderextendsAsyncNotifierProviderImpl<HelloWorld, String> {
/// See also [HelloWorld].
  HelloWorldProvider(
String value,
String type,
  ) : this._internal(

dependencies

另外@Riverpod还有另外一个可配置参数dependencies，从名字上理解起来是依赖的意思，但是其实它更多用于「作用域」相关的处理。

在 riverpod 里，框架的设计是支持多个 ProviderContainer 的场景，并且每个容器可以覆盖（override）某些 Provider 的数据，例如我只是添加了一个dependencies: []，此时无论列表是否为空，它都可以被认为是一个具有作用域支持的 Provider，从而实现根据上下文进行数据隔离，另外不为空时还可以看作声明 Provider 在作用域内的依赖关系。

@Riverpod(dependencies: [])

但是，不是你加了 dependencies 它就自动产生作用域隔离了，不为空时也不会自动追加依赖，它只是一个声明作用，后续还是需要代码配合。

如下代码所示，这里简单的声明了一个带有dependencies的Counter，然后：

  • 在页面通过ref.watch(counterProvider)监听了 Counter
  • 在新的 dialog 也通过ref2.watch(counterProvider)监听了 Counter
@Riverpod(dependencies: [])
classCounterextends_$Counter{
@override
int build() => 0;
void update(int count) {
    state = count;
  }
}
classMyAppextendsStatelessWidget{
@override
  Widget build(BuildContext context) {
return ProviderScope(
      child: MaterialApp(
        home: Consumer(builder: (ctx, ref, __) {
final count = ref.watch(counterProvider);
return Scaffold(
            appBar: AppBar(),
            body: Column(
              mainAxisAlignment: MainAxisAlignment.start,
              children: [
                Text('Counter: $count'),
                ElevatedButton(
                  onPressed: () {
                    showDialog(
                      context: ctx,
                      builder: (context) => AlertDialog(
                          title: Text('Dialog'),
                          content: Consumer(builder: (_, ref2, __) {
final count2 = ref2.watch(counterProvider);
return InkWell(
                              onTap: () {
                                ref2
                                    .read(counterProvider.notifier)
                                    .update(count2 + 1);
                              },
                              child: Text('Dialog Counter: $count2'),
                            );
                          })),
                    );
                  },
                  child: Text('Open Dialog'),
                ),
              ],
            ),
            floatingActionButton: FloatingActionButton(onPressed: () {
              ref.read(counterProvider.notifier).update(count + 1);
            }),
          );
        }),
      ),
    );
  }
}

结果最后运行发现，Dialog 和主页的 Counter 其实还是共享的，dependencies并没有起到作用：

Image

之所以这样，原因在于没有增加新的ProviderScope，如下代码所示，只要将上面的showDialog部分修改为如下代码所示：

  • 新增一个 的ProviderScope
  • 通过overrides指定对应counterProvider
showDialog(
  context: ctx,
  builder: (context) => ProviderScope(
    overrides: [
      counterProvider，
///你还可以 overrideWith 覆盖修改
//counterProvider.overrideWith(()=>Counter())
    ],
    child: AlertDialog(
        title: Text('Dialog'),
        content: Consumer(builder: (_, ref2, __) {
final count2 = ref2.watch(counterProvider);
return InkWell(
            onTap: () {
              ref2
                  .read(counterProvider.notifier)
                  .update(count2 + 1);
            },
            child: Text('Dialog Counter: $count2'),
          );
        })),
  ),
);

以上条件缺一不可以，运行后如下图所示，可以看到此时counterProvider在主页和 Dialog 之间被有效分割开：

Image

其实原因从源码里也可以看出来，在ProviderContainer内部源码我们可以看到，要产生一个独立的作用域，你需要：

  • root 不为空，也就是有一个上级ProviderContainer
  • 其次存在dependencies且ProviderContainer的 override 不为空，也就是dependencies不为 null 就行，但是 override 必须有 Provider
  • 最后才是返回全新的_StateReader用于提供状态数据
Image

所以，从这里就可以看出，**dependencies只是一个先置条件，具体它是不是局部作用域，还得是你用的时候怎么用**。

同理依赖也是，比如你写了一个@Riverpod(dependencies: [maxCountProvider])，但是你还是需要对应写上ref.watch(maxCountProvider)，不然它也并不起作用：

@Riverpod(dependencies: [maxCountProvider])
int limitedCounter(LimitedCounterRef ref) {
final max = ref.watch(maxCountProvider); // 监听 
return0.clamp(0, max); 
}
❝

PS ，如果你只是正常监听，不需要作用域的场景，其实直接写 ref.watch而不需要 dependencies: [maxCountProvider]也是可以的。

如果我们从输出端看，可以看到有没有dependencies，主要就是_dependencies和_allTransitiveDependencies是否为空的区别：

Image

注意事项

最后也有一些注意事项，例如：

  • 通过注解生成的 Provider 好不要依赖非生成的 Provider，比如这里的example是注解，它监听了一个非注解生成的depProvider，这样并不规范：

    final depProvider = Provider((ref) => 0);
    @riverpod
    void example(Ref ref) {
    // Generated providers should not depend on non-generated providers
      ref.watch(depProvider);
    }

  • 有作用域时，如果监听了某个 Provider ，那么 dependencies 里必须写上依赖 Provider，以下写法就不合规：

    @Riverpod(dependencies: [])
    void example(Ref ref) {
    // scopedProvider is used but not present in the list of dependencies
      ref.watch(scopedProvider);
    }

  • Provider 里不应该接收BuildContext：

    // Providers should not receive a BuildContext as a parameter.
    @riverpod
    int fn(Ref ref, BuildContext context) => 0;
    @riverpod
    classMyNotifierextends_$MyNotifier{
    int build() => 0;
    // Notifiers should not have methods that receive a BuildContext as a parameter.
    void event(BuildContext context) {}
    }

其实类型的注意事项在riverpod_lint里都声明了，只是 Custom lint rules 不会直接展示在 dart analyze ，所以需要用户在添加完riverpod_lint后，执行对应的dart run custom_lint：

Image

最后

可以看到，通过注解模式，riverpod 可以让开发者少些很多代码，在整体设计理念没有变化的情况下，模版生成的代码会更规范，并且在上层屏蔽了许多复杂度和工作量。

另外通过dependencies我们可以可以看到 riverpod在存储管理上它是统一的，但是在组合上它是分散的的设计理念。

而 Flutter 状态管理一直以来也是「是非之地」，比如近期就出现说 riverpod 在基准性能测试表示不如 signals 的情况，但是作者也回应了该测试属于「春秋笔法」之流：

Image
Image

另外，由于Dart 宏功能推进暂停，而 build runner 与数据类的优化还没落地，作者也在探索没有 codegen 下如何也可以便捷使用 riverpod ，比如让 family 支持多个参数：

Image

当然，从作者的维护体验上看，貌似作者又有停滞 codegen 的倾向，看起来左右摇摆的状态还会持续一段时间：

Image
Image

那么， 2025 年 riverpod 还是你状态管理的首选吗？

KEEP THE THREAD GOING

更多来源文章