Flutter异步结果处理插件async_result的使用

async_result 是一个强大且类型安全的方式来处理Dart和Flutter应用程序中异步操作的不同状态。它帮助你管理异步操作的常见状态：初始、加载、数据（成功）和错误状态。

特性

• 🎯 类型安全的状态处理
• 🔄 全面的状态管理
• 🛠️ 丰富的函数式编程工具
• 🧩 无缝集成Bloc/Cubit
• ⚡ 高效的模式匹配
• 🔍 内置错误处理

安装

在你的 pubspec.yaml 文件中添加以下依赖：

dependencies:
  async_result: ^1.0.6

概述

当处理异步操作时，通常会遇到不同的状态，如加载、成功或错误。AsyncResult 将这些状态封装到一个类型安全的类中，使得在整个应用程序中更容易处理和传播异步结果。

状态

AsyncResult 有四种可能的状态：

1. AsyncInitial：表示在任何操作开始之前的初始状态。
2. AsyncLoading：表示异步操作正在进行中。
3. AsyncData：表示带有相关数据的成功状态。
4. AsyncError：表示带有相关错误信息的错误状态。

基本用法

AsyncResult 提供了四个不同的状态：

// 初始状态
final initial = AsyncResult<String, Exception>.initial();

// 加载状态
final loading = AsyncResult<String, Exception>.loading();

// 成功状态带数据
final success = AsyncResult<String, Exception>.data("Hello, World!");

// 错误状态
final error = AsyncResult<String, Exception>.error(Exception("Something went wrong"));

模式匹配

使用 when 方法来处理所有可能的状态：

result.when(
  whenInitial: () => print("Initial state"),
  whenLoading: () => print("Loading..."),
  whenData: (data) => print("Success: $data"),
  whenError: (error) => print("Error: $error"),
);

与Cubit集成

下面是一个完整的示例，展示如何使用 AsyncResult 和 Cubit 来管理用户数据：

// 用户模型
class User {
  final String id;
  final String name;

  User({required this.id, required this.name});
}

// 仓库
class UserRepository {
  Future<User> fetchUser(String id) async {
    // 模拟API调用
    await Future.delayed(const Duration(seconds: 1));
    return User(id: id, name: "John Doe");
  }
}

// 状态
typedef UserState = AsyncResult<User, Exception>;

// Cubit
class UserCubit extends Cubit<UserState> {
  final UserRepository _repository;

  UserCubit(this._repository) : super(const AsyncResult.initial());

  Future<void> loadUser(String id) async {
    emit(const AsyncResult.loading());

    try {
      final user = await _repository.fetchUser(id);
      emit(AsyncResult.data(user));
    } catch (e) {
      emit(AsyncResult.error(Exception(e.toString())));
    }
  }
}

在UI中使用

以下是如何在Flutter小部件中使用 UserCubit：

class UserProfile extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return BlocBuilder<UserCubit, UserState>(
      builder: (context, state) {
        return state.when(
          whenInitial: () => const Text('Press button to load user'),
          whenLoading: () => const CircularProgressIndicator(),
          whenData: (user) => Column(
            children: [
              Text('ID: ${user.id}'),
              Text('Name: ${user.name}'),
            ],
          ),
          whenError: (error) => Text('Error: ${error.toString()}'),
        );
      },
    );
  }
}

高级用法

数据转换

使用 map 转换成功值：

final result = AsyncResult<int, String>.data(42);
final mapped = result.map((i) => i.toString()); // AsyncResult<String, String>

错误处理

使用 mapError 转换错误值：

final result = AsyncResult<int, String>.error("not_found");
final mapped = result.mapError((e) => Exception(e)); // AsyncResult<int, Exception>

操作链式调用

使用 flatMap 链接 AsyncResult 操作：

class UserCubit extends Cubit<AsyncResult<UserProfile, Exception>> {
  Future<void> loadUserWithPosts(String userId) async {
    emit(const AsyncResult.loading());

    try {
      final userResult = await _repository.fetchUser(userId);
      final result = AsyncResult<User, Exception>.data(userResult)
          .flatMap((user) async {
            final posts = await _repository.fetchUserPosts(user.id);
            return AsyncResult.data(
              UserProfile(user: user, posts: posts),
            );
          });

      emit(result);
    } catch (e) {
      emit(AsyncResult.error(Exception(e.toString())));
    }
  }
}

从错误中恢复

使用 recover 优雅地处理错误：

class UserCubit extends Cubit<AsyncResult<User, Exception>> {
  Future<void> loadUserWithFallback(String id) async {
    emit(const AsyncResult.loading());

    try {
      final user = await _repository.fetchUser(id);
      emit(AsyncResult.data(user));
    } catch (e) {
      emit(
        AsyncResult<User, Exception>
          .error(Exception(e.toString()))
          .recover((_) => User(id: "0", name: "Guest User"))
      );
    }
  }
}

最佳实践

1. 类型安全：始终指定成功和错误类型：

   typedef UserState = AsyncResult<User, Exception>;
   

2. 初始状态：创建Cubit时以初始状态开始：

   class MyCubit extends Cubit<AsyncResult<Data, Error>> {
     MyCubit() : super(const AsyncResult.initial());
   }
   

3. 错误处理：使用特定的错误类型而不是动态类型：

   AsyncResult<Data, NetworkError> instead of AsyncResult<Data, dynamic>
   

4. 状态转换：在进行异步操作之前始终发出加载状态：

   emit(const AsyncResult.loading());
   // ... 执行异步工作
   

示例代码

以下是一个完整的示例，展示如何使用 async_result 处理异步操作：

import 'dart:async';
import 'dart:math';

import 'package:async_result/async_result.dart';

void main() async {
  // 使用示例 1
  print('Fetching todos...');
  final todosResult = await fetchTodos();
  todosResult.when(
    whenInitial: () => print('Initial state (unexpected)'),
    whenLoading: () => print('Loading todos...'),
    whenData: (todos) => print('Fetched ${todos.length} todos: $todos'),
    whenError: (error) => print('Error fetching todos: $error'),
  );

  // 使用示例 2
  print('\nPerforming computation...');
  final computationResult = await simulateComputation();
  computationResult.when(
    whenInitial: () => print('Initial state (unexpected)'),
    whenLoading: () => print('Computing...'),
    whenData: (result) => print('Computation result: $result'),
    whenError: (error) => print('Computation error: $error'),
  );

  // 使用示例 3
  print('\nProcessing data...');
  final initialResult = AsyncResult<int, String>.data(10);
  final processedResult = await processData(initialResult);
  processedResult.when(
    whenInitial: () => print('Initial state (unexpected)'),
    whenLoading: () => print('Processing...'),
    whenData: (result) => print('Processed result: $result'),
    whenError: (error) => print('Processing error: $error'),
  );

  // 使用示例 5
  print('\nCombining results...');
  final result1 = AsyncResult<int, String>.data(42);
  final result2 = AsyncResult<String, String>.data('Hello');
  final combinedResult = await combineResults(result1, result2);
  combinedResult.when(
    whenInitial: () => print('Initial state (unexpected)'),
    whenLoading: () => print('Combining...'),
    whenData: (result) => print(result),
    whenError: (error) => print('Combining error: $error'),
  );
}

Future<AsyncResult<List<String>, Exception>> fetchTodos() async {
  await Future.delayed(Duration(seconds: 1));

  final random = Random();
  if (random.nextBool()) {
    final todos = List.generate(5, (index) => 'Todo ${index + 1}');
    return AsyncResult.data(todos);
  } else {
    return AsyncResult.error(Exception('Failed to load todos'));
  }
}

Future<AsyncResult<int, String>> simulateComputation() async {
  try {
    await Future.delayed(Duration(seconds: 2));
    final result = List.generate(1000000, (index) => index).reduce((a, b) => a + b);
    return AsyncResult.data(result);
  } catch (e) {
    return AsyncResult.error('Computation failed: $e');
  }
}

Future<AsyncResult<double, String>> processData(AsyncResult<int, String> input) async {
  return input.when(
    whenInitial: () => AsyncResult.error('Unexpected initial state'),
    whenLoading: () => AsyncResult.error('Unexpected loading state'),
    whenData: (data) async {
      await Future.delayed(Duration(milliseconds: 500));
      return AsyncResult.data(data / 2.0);
    },
    whenError: (error) => AsyncResult.error('Processing failed: $error'),
  );
}

Future<AsyncResult<String, String>> combineResults(AsyncResult<int, String> result1, AsyncResult<String, String> result2) async {
  if (result1.hasError) return AsyncResult.error(result1.whenError((e) => e)!);
  if (result2.hasError) return AsyncResult.error(result2.whenError((e) => e)!);

  final value1 = result1.dataOrNull;
  final value2 = result2.dataOrNull;

  if (value1 != null && value2 != null) {
    return AsyncResult.data('Combined: $value1 and $value2');
  } else {
    return AsyncResult.error('One or both results are null');
  }
}

通过上述示例，你可以看到如何在Flutter应用中使用 async_result 插件来简化异步操作的状态管理和错误处理。希望这些示例能帮助你在项目中更好地使用这个插件！