跨平台开发 / 系统课时
用 AsyncValue.guard 捕获异常
用 AsyncValue.guard 捕获异常
在 AsyncNotifier 的公开方法里发起请求时,最容易重复出现的是 try-catch、AsyncError 和堆栈处理。AsyncValue.guard 可以把成功结果与异常统一转换成 AsyncValue,让方法只负责切换状态,页面继续按 loading、data、error 三种状态渲染。
学习目标
- 使用
AsyncValue.guard把可能抛异常的Future转成AsyncValue - 在
AsyncNotifier方法中减少重复的try-catch - 区分首次
build与后续用户操作中的异常处理位置
guard 解决的重复代码
AsyncValue.guard 接收一个返回 Future<T> 的函数。Future 正常完成时得到数据状态;函数抛出异常时得到错误状态,并保留对应堆栈。它适合放在刷新、保存、提交等 Notifier 方法里,因为这些方法通常需要显式把执行结果写回 state。
如果异常发生在 AsyncNotifier.build 中,Riverpod 本身就会把初始化结果暴露为异步状态;因此没有必要为了“保险”再给每个 build 套一层 guard。真正能减少样板代码的地方,是后续由按钮或业务动作触发的异步方法。
在 Notifier 方法中使用 guard
下面的最小 Flutter 示例先成功加载数字 42。点击按钮后,请求故意失败;reloadWithFailure 不写 try-catch,而是把 AsyncValue.guard 的结果直接赋给 state。
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
void main() {
runApp(const ProviderScope(child: MyApp()));
}
class DemoRepository {
Future<int> fetchNumber({required bool fail}) async {
await Future<void>.delayed(const Duration(milliseconds: 300));
if (fail) {
throw Exception('request failed');
}
return 42;
}
}
final repositoryProvider = Provider<DemoRepository>((ref) {
return DemoRepository();
});
class NumberController extends AsyncNotifier<int> {
@override
Future<int> build() {
return ref.read(repositoryProvider).fetchNumber(fail: false);
}
Future<void> reloadWithFailure() async {
state = const AsyncLoading<int>();
// guard 负责把成功值或异常统一转换成 AsyncValue<int>。
state = await AsyncValue.guard(
() => ref.read(repositoryProvider).fetchNumber(fail: true),
);
}
}
final numberProvider =
AsyncNotifierProvider<NumberController, int>(NumberController.new);
class MyApp extends ConsumerWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context, WidgetRef ref) {
final value = ref.watch(numberProvider);
return MaterialApp(
home: Scaffold(
body: Center(
child: value.when(
data: (number) => Column(
mainAxisSize: MainAxisSize.min,
children: [
Text('数据:$number'),
ElevatedButton(
onPressed: () {
ref
.read(numberProvider.notifier)
.reloadWithFailure();
},
child: const Text('触发失败请求'),
),
],
),
loading: () => const CircularProgressIndicator(),
error: (error, stackTrace) => Text('失败:$error'),
),
),
),
);
}
}预期结果
首次加载:数据:42
点击“触发失败请求”后:先出现加载指示器,随后显示“失败:Exception: request failed”guard 不会替你决定加载策略
guard 只负责把 Future 的完成结果包装成异步状态。是否先执行 state = const AsyncLoading(),取决于交互设计:提交表单时通常需要明确进入 loading;后台刷新时如果希望保留旧数据,就不应机械地清空当前状态。
另外,不要在 guard 内部吞掉异常后返回一个“看似成功”的默认值。这样虽然页面进入 data 状态,却失去了错误边界。需要把特定业务异常转换成可展示数据时,应明确设计返回类型,而不是借默认值掩盖失败。
什么时候仍然需要 try-catch
当异常发生后还要执行额外分支逻辑,例如针对鉴权错误清理令牌、对特定异常做补偿,或者记录不同级别的日志时,显式 try-catch 仍然更合适。若需求只是“成功就得到数据,失败就进入 error 状态”,AsyncValue.guard 能用更少代码表达同一件事。