跨平台开发 / 系统课时

用 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。

dart
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'),
          ),
        ),
      ),
    );
  }
}

预期结果

text
首次加载:数据:42
点击“触发失败请求”后:先出现加载指示器,随后显示“失败:Exception: request failed”

guard 不会替你决定加载策略

guard 只负责把 Future 的完成结果包装成异步状态。是否先执行 state = const AsyncLoading(),取决于交互设计:提交表单时通常需要明确进入 loading;后台刷新时如果希望保留旧数据,就不应机械地清空当前状态。

另外,不要在 guard 内部吞掉异常后返回一个“看似成功”的默认值。这样虽然页面进入 data 状态,却失去了错误边界。需要把特定业务异常转换成可展示数据时,应明确设计返回类型,而不是借默认值掩盖失败。

什么时候仍然需要 try-catch

当异常发生后还要执行额外分支逻辑,例如针对鉴权错误清理令牌、对特定异常做补偿,或者记录不同级别的日志时,显式 try-catch 仍然更合适。若需求只是“成功就得到数据,失败就进入 error 状态”,AsyncValue.guard 能用更少代码表达同一件事。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 AsyncValue.guard 捕获异常

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通