跨平台开发 / 系统课时
组合 family 与异步请求
组合 family 与异步请求
当接口地址或查询条件由用户选择决定时,可以让 family 把参数传入异步 Provider,并让 Riverpod 按参数分别管理加载、成功、失败和缓存状态。本篇用 FutureProvider.autoDispose.family 构建一个可切换用户的最小示例。
学习目标
- 使用
FutureProvider.autoDispose.family根据动态参数发起异步加载 - 在界面中处理
AsyncValue的加载、成功与失败状态 - 理解不同 family 参数对应独立缓存,以及何时改用 AsyncNotifier
把动态参数变成异步缓存键
FutureProvider.family 可以理解为“带参数的异步 Provider 工厂”。例如 userProvider('u-100') 与 userProvider('u-200') 是两个不同状态槽,各自拥有自己的 Future、AsyncValue 与缓存。
如果参数集合可能不断增长,例如搜索关键字、分页编号或详情页 ID,通常应考虑 autoDispose。当对应 Provider 不再被监听时,Riverpod 可以释放状态,避免长期保留大量只访问过一次的参数实例。

实现可切换参数的异步 Provider
下面示例使用内存仓库模拟接口延迟,重点保留真实项目中的结构:页面只传 userId,Provider 负责调用仓库并把结果转换成 AsyncValue<User>。
import 'dart:async';
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
class User {
const User({required this.id, required this.name});
final String id;
final String name;
}
class UserRepository {
Future<User> fetchUser(String userId) async {
await Future<void>.delayed(const Duration(milliseconds: 300));
const users = {
'u-100': User(id: 'u-100', name: 'Ava'),
'u-200': User(id: 'u-200', name: 'Noah'),
};
final user = users[userId];
if (user == null) {
throw StateError('User not found: $userId');
}
return user;
}
}
final userRepositoryProvider = Provider<UserRepository>((ref) {
return UserRepository();
});
final userProvider =
FutureProvider.autoDispose.family<User, String>((ref, userId) {
final repository = ref.watch(userRepositoryProvider);
return repository.fetchUser(userId);
});
void main() {
runApp(const ProviderScope(child: DemoApp()));
}
class DemoApp extends ConsumerStatefulWidget {
const DemoApp({super.key});
@override
ConsumerState<DemoApp> createState() => _DemoAppState();
}
class _DemoAppState extends ConsumerState<DemoApp> {
String userId = 'u-100';
@override
Widget build(BuildContext context) {
final user = ref.watch(userProvider(userId));
return MaterialApp(
home: Scaffold(
body: Center(
child: Column(
mainAxisSize: MainAxisSize.min,
children: [
user.when(
loading: () => const CircularProgressIndicator(),
error: (error, stackTrace) => Text('加载失败: $error'),
data: (value) => Text('${value.id}: ${value.name}'),
),
const SizedBox(height: 16),
FilledButton(
onPressed: () {
setState(() {
userId = userId == 'u-100' ? 'u-200' : 'u-100';
});
},
child: const Text('切换用户'),
),
],
),
),
),
);
}
}预期结果
冷启动短暂显示加载指示器,随后显示:u-100: Ava
点击“切换用户”后,短暂显示加载指示器,随后显示:u-200: Noah示例中的延迟值属于演示行为,真实接口的响应时间会不同。界面不需要手动维护 isLoading、data 和 error 三组变量,因为它们已经包含在 AsyncValue 中。
缓存、刷新与参数边界
相同参数会复用对应 family 状态;参数改变则读取另一个状态槽。如果希望重新请求当前参数,可以调用 ref.invalidate(userProvider(userId)),让当前实例失效并在下次监听时重新创建。
family 参数仍然必须具备稳定相等性。上例使用 String,因此天然适合作为缓存键;如果换成自定义查询对象,应先保证其 == 与 hashCode 正确。
autoDispose 适合参数空间很大、页面离开后不必长期保留结果的场景。如果详情数据需要跨页面长期缓存,可以改用非 autoDispose 版本,或根据业务显式控制保留策略。
什么时候改用 AsyncNotifier
只需要“根据参数读取一次异步数据”时,FutureProvider.family 通常最简单。若同一个参数实例还需要暴露刷新、提交、分页、重试等命令,并在这些操作之间维护异步状态,AsyncNotifier 更适合承载这组行为。
无论选择哪一种,family 的职责都相同:把动态参数纳入 Provider 身份。先把参数设计成稳定缓存键,再决定异步逻辑由 FutureProvider 还是 AsyncNotifier 承担,状态边界会更清楚。