Flutter通用用例插件 generic_usecase 的使用

简介

在使用Clean Architecture的过程中，我们经常发现自己重复编写用例的通用代码。generic_usecase 插件提供了一个小组件，用于封装应用程序的场景逻辑。通过这些类，你可以将你的逻辑封装在一个原子元素中，并在整个应用程序中注入和使用。

特性

• ✅ 简单易用的API
• ✅ 完全测试（100%覆盖率）
• ✅ 完全文档化

可用的用例类型：

• Usecase<Input, Output>
• NoParamsUsecase<Output>
• StreamUsecase<Input, Output>
• NoParamsStreamUsecase<Output>

使用示例

简单用例

假设你想将两个数字相加，可以创建一个用例如下：

class AdditionUsecase extends Usecase<int, int> {
  const AdditionUsecase();

  [@override](/user/override)
  FutureOr<int> execute(int params) async => params + params;
}

void main() async {
  final addition = AdditionUsecase();
  await addition(2).then(print, onError: print); // 输出：4
}

execute 方法会在调用用例的 call 方法时执行。

使用流用例

你可以使用流用例返回一个 Stream 而不是原始值：

class GeneratorUsecase extends NoParamsStreamUsecase<int> {
  const GeneratorUsecase();

  [@override](/user/override)
  Stream<int> execute() async* {
    for (int i = 0; i < 10; i++) {
      await Future<void>.delayed(const Duration(seconds: 1));
      yield i;
    }
  }
}

void main() {
  final generator = GeneratorUsecase();
  final stream = generator();

  stream.listen(
    print,
    onError: print,
    onDone: () => print('Done'),
  );
}

检查前提条件和后置条件

你可以在用例中添加前提条件检查，它将在 execute 方法之前执行：

class DivisionUsecase extends Usecase<(int, int), double> {
  const DivisionUsecase();

  [@override](/user/override)
  FutureOr<ConditionsResult> checkPreconditions((int, int)? params) {
    if (params == null) {
      return ConditionsResult(isValid: false, message: 'Params is null');
    }

    if (params.$2 == 0) {
      return ConditionsResult(isValid: false, message: 'Cannot divide by 0');
    }

    return ConditionsResult(isValid: true);
  }

  [@override](/user/override)
  FutureOr<double> execute((int, int) params) async => params.$1 / params.$2;
}

你也可以添加后置条件检查，在 execute 方法之后执行：

class AdditionUsecase extends Usecase<int, int> {
  const AdditionUsecase();

  [@override](/user/override)
  FutureOr<int> execute(int params) async => params + params;

  [@override](/user/override)
  FutureOr<ConditionsResult> checkPostconditions(int? result) {
    if (result == null) {
      return ConditionsResult(isValid: false, message: 'Result is null');
    }

    if (result < 0) {
      return ConditionsResult(isValid: false, message: 'Result is negative');
    }

    return ConditionsResult(isValid: true);
  }
}

捕获异常

你可以通过覆盖 onException 方法来捕获由用例抛出的异常：

class AdditionUsecase extends Usecase<int, int> {
  const AdditionUsecase();

  [@override](/user/override)
  FutureOr<int> execute(int params) async => params + params;

  [@override](/user/override)
  FutureOr<int> onException(Object e) {
    print(e); // 打印异常信息
    return super.onException(e);
  }
}

这个方法会在 execute 方法抛出异常时被调用，也会在前提条件或后置条件检查失败时被调用。

使用 Result 对象

通过组合前面的例子，你可以创建一个返回 Result 对象的用例。通过捕获异常和检查前提条件与后置条件，你可以返回一个 Result 对象，该对象要么是 Success，要么是 Failure。

class DivisionResultUsecase extends Usecase<(int, int), Result<double, Failure>> {
  const DivisionResultUsecase();

  [@override](/user/override)
  FutureOr<ConditionsResult> checkPreconditions((int, int)? params) {
    if (params == null) {
      return ConditionsResult(isValid: false, message: 'Params is null');
    }

    if (params.$2 == 0) {
      return ConditionsResult(isValid: false, message: 'Cannot divide by 0');
    }

    return ConditionsResult(isValid: true);
  }

  [@override](/user/override)
  FutureOr<Result<double, Failure>> execute((int, int) params) async =>
      Result.success(params.$1 / params.$2);

  [@override](/user/override)
  FutureOr<Result<double, Failure>> onException(Object e) {
    if (e case UsecaseException _) {
      return Result.failure(Failure(e.message ?? ''));
    }
    if (e case Exception || Error) {
      return Result.failure(Failure(e.toString()));
    }
    return Result.failure(Failure(''));
  }
}

示例代码

下面是一个完整的示例代码，展示了如何使用 generic_usecase 插件：

import 'dart:async';
import 'package:generic_usecase/generic_usecase.dart';

Future<void> main() async {
  print('AdditionUsecase');

  const AdditionUsecase addition = AdditionUsecase();

  print('> addition(2)');
  await display(() => addition(2));

  print('> addition(null)');
  await display(() => addition(null));

  print('> addition(-2)');
  await display(() => addition(-2));

  print('DivisionUsecase');

  const DivisionUsecase division = DivisionUsecase();

  print('> division(null)');
  await display(() => division(null));

  print('> division((2, 0))');
  await display(() => division((2, 0)));

  print('> division((4, 2))');
  await display(() => division((4, 2)));

  print('GeneratorUsecase');

  const GeneratorUsecase generator = GeneratorUsecase();

  print('> generator()');
  generator().listen(
    print,
    onError: print,
    onDone: () => print('Done'),
  );
}

class AdditionUsecase extends Usecase<int, int> {
  const AdditionUsecase();

  [@override](/user/override)
  FutureOr<int> execute(int params) async => params + params;

  [@override](/user/override)
  FutureOr<ConditionsResult> checkPostconditions(int? result) {
    if (result == null) {
      return ConditionsResult(isValid: false, message: 'Result is null');
    }

    if (result < 0) {
      return ConditionsResult(isValid: false, message: 'Result is negative');
    }

    return ConditionsResult(isValid: true);
  }
}

class DivisionUsecase extends Usecase<(int, int), double> {
  const DivisionUsecase();

  [@override](/user/override)
  FutureOr<ConditionsResult> checkPreconditions((int, int)? params) {
    if (params == null) {
      return ConditionsResult(isValid: false, message: 'Params is null');
    }

    if (params.$2 == 0) {
      return ConditionsResult(isValid: false, message: 'Cannot divide by 0');
    }

    return ConditionsResult(isValid: true);
  }

  [@override](/user/override)
  FutureOr<double> execute((int, int) params) async => params.$1 / params.$2;
}

class GeneratorUsecase extends NoParamsStreamUsecase<int> {
  const GeneratorUsecase();

  [@override](/user/override)
  Stream<int> execute() async* {
    for (int i = 0; i < 5; i++) {
      await Future<void>.delayed(const Duration(seconds: 1));
      yield i;
    }
  }
}