代码模式

模式 1：用于 API 调用的 AsyncNotifier

dart
@riverpod
class UserController extends _$UserController {
@override
Future build(String userId) async {
final dio = ref.watch(dioProvider);
final response = await dio.get(/users/$userId);
return User.fromJson(response.data);
}

Future updateUser(User user) async {
// 乐观更新
final previous = await future;
state = AsyncData(user);

try {
await ref.read(dioProvider).put(/users/${user.id}, user.toJson());
} catch (e) {
state = AsyncError(e, StackTrace.current);
}
}
}

模式 2：组合 Provider

dart
@riverpod
List filteredTodos(Ref ref) {
final todos = ref.watch(todosProvider);
final filter = ref.watch(filterProvider);

return switch (filter) {
Filter.all => todos,
Filter.completed => todos.where((t) => t.completed).toList(),
Filter.uncompleted => todos.where((t) => !t.completed).toList(),
};
}

模式 3：依赖注入

dart
@riverpod
Dio dio(Ref ref) {
final baseUrl = ref.watch(baseUrlProvider);
return Dio(BaseOptions(baseUrl: baseUrl));
}

模式 4：AsyncValue 模式匹配

dart
class AsyncWidget extends ConsumerWidget {
@override
Widget build(BuildContext context, WidgetRef ref) {
final data = ref.watch(asyncProvider);

return switch (data) {
AsyncData(:final value) => Text($value),
AsyncError(:final error, :final stackTrace) => ErrorWidget(error),
AsyncLoading() => const CircularProgressIndicator(),
};
}
}

Provider 修饰符

Family - 参数化 Provider

dart
@riverpod
Future user(UserRef ref, String userId) async {
return await api.getUser(userId);
}

// 使用方式
ref.watch(userProvider(123));

AutoDispose - 自动清理

dart
@Riverpod(keepAlive: false)
Future temporaryUser(TemporaryUserRef ref, String id) async {
ref.onDispose(() {
// 清理逻辑
});
return await api.getUser(id);
}

Widget 模式

ConsumerWidget 模式

dart
class MyWidget extends ConsumerWidget {
const MyWidget({super.key});

@override
Widget build(BuildContext context, WidgetRef ref) {
final value = ref.watch(myProvider);
return Text($value);
}
}

ConsumerStatefulWidget 模式

dart
class MyPage extends ConsumerStatefulWidget {
const MyPage({super.key});

@override
ConsumerState createState() => _MyPageState();
}

class _MyPageState extends ConsumerState {
@override
void initState() {
super.initState();
ref.read(myProvider.notifier).load();
}

@override
Widget build(BuildContext context) {
final state = ref.watch(myProvider);
return Scaffold(body: Text($state));
}
}

HookConsumerWidget（配合 flutter_hooks）

dart
class HookWidget extends HookConsumerWidget {
const HookWidget({super.key});

@override
Widget build(BuildContext context, WidgetRef ref) {
final controller = useTextController();
final count = ref.watch(counterProvider);

return TextField(controller: controller);
}
}

代码生成工作流程

1. 1. 添加注解：@riverpod 或 @Riverpod()
2. 定义继承 $ClassName 的类或函数
3. 运行：flutter pub run buildrunner watch --delete-conflicting-outputs
4. 生成文件：.g.dart 扩展名

基本命令

bash

一次性生成

监听变化（开发时推荐）

测试

dart
testWidgets(计数器递增, (tester) async {
await tester.pumpWidget(
ProviderScope(
child: MaterialApp(home: CounterView()),
),
);

expect(find.text(0), findsOneWidget);
});

ref 方法

最佳实践

有关以下方面的详细指南，请参阅 BEST_PRACTICES.md：

• - Provider 架构
• 避免常见陷阱
• 性能优化
• 测试策略