跨平台开发 / 系统课时

用 AsyncValue 表达三种结果

用 AsyncValue 表达三种结果

异步请求并不只有“成功或失败”两种结果:请求尚未结束时,页面同样需要明确状态。Riverpod 用 AsyncValue<T> 把等待、成功和失败统一成一个值,让业务状态不再依赖多组容易冲突的布尔变量。

学习目标

  • 理解 AsyncLoading、AsyncData 和 AsyncError 分别表达什么
  • 使用 AsyncValue<T> 保存异步操作的完整结果
  • 根据当前结果安全读取数据或错误信息

AsyncValue 解决的核心问题

如果分别维护 isLoading、data 和 error,就可能出现“正在加载但同时有错误”“加载结束却没有数据”等矛盾组合。AsyncValue<T> 把这些结果放进同一个类型中,调用方只需要处理合法状态。

状态 含义 页面通常显示
AsyncLoading<T> 异步操作正在等待结果 进度指示器、骨架屏
AsyncData<T> 操作成功并得到 T 类型数据 正常业务内容
AsyncError<T> 操作失败并记录异常与堆栈 错误提示、重试入口

这里的泛型 T 表示成功时真正需要的数据。例如 AsyncValue<String> 的成功结果是字符串,AsyncValue<List<User>> 的成功结果则是一组用户。

创建并观察三种结果

下面的完整 Flutter 示例直接创建三种 AsyncValue<String>。点击按钮后,页面会切换当前结果,并通过 when 把状态转换为可读文本。

dart
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';

void main() {
  runApp(const MaterialApp(home: AsyncValueDemo()));
}

class AsyncValueDemo extends StatefulWidget {
  const AsyncValueDemo({super.key});

  @override
  State<AsyncValueDemo> createState() => _AsyncValueDemoState();
}

class _AsyncValueDemoState extends State<AsyncValueDemo> {
  AsyncValue<String> value = const AsyncLoading();

  String describe(AsyncValue<String> current) {
    return current.when(
      loading: () => 'loading:正在等待结果',
      data: (data) => 'data:$data',
      error: (error, stackTrace) => 'error:$error',
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('AsyncValue 三种结果')),
      body: Padding(
        padding: const EdgeInsets.all(24),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text(describe(value)),
            const SizedBox(height: 24),
            Wrap(
              spacing: 8,
              children: [
                ElevatedButton(
                  onPressed: () {
                    setState(() => value = const AsyncLoading());
                  },
                  child: const Text('Loading'),
                ),
                ElevatedButton(
                  onPressed: () {
                    setState(
                      () => value = const AsyncData('用户资料已加载'),
                    );
                  },
                  child: const Text('Data'),
                ),
                ElevatedButton(
                  onPressed: () {
                    setState(
                      () => value = AsyncError(
                        Exception('请求失败'),
                        StackTrace.current,
                      ),
                    );
                  },
                  child: const Text('Error'),
                ),
              ],
            ),
          ],
        ),
      ),
    );
  }
}

预期结果

text
应用启动:loading:正在等待结果
点击 Data:data:用户资料已加载
点击 Error:error:Exception: 请求失败
再次点击 Loading:loading:正在等待结果

异常文本的具体展示形式可能随异常对象而变化,但状态分支应分别进入 loading、data 和 error。

不要绕过状态直接取值

AsyncData<T> 才保证包含成功数据,AsyncError<T> 保存的是失败信息,而 AsyncLoading<T> 可能还没有可用结果。因此业务代码不应假设每个 AsyncValue<T> 都已经有值,再通过强制读取来决定页面行为。

更稳妥的思路是让消费端显式处理三种结果。这样以后把本地假数据替换成网络请求、数据库读取或 AsyncNotifier 时,状态模型不需要重写,只需要改变产生 AsyncValue 的过程。

什么时候使用 AsyncValue

只要一次操作存在明确的等待、成功和失败过程,AsyncValue<T> 都适合作为它的结果模型,例如用户资料加载、搜索、分页首屏请求或提交表单。对于完全同步、不会失败的普通计数器等状态,则没有必要为了统一形式强行套上异步状态。

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

目录与阅读设置

阅读设置

17

记录一个想法

用 AsyncValue 表达三种结果

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

登录哪都通