如何使用 DartExceptor：在 Dart 3 中处理错误的一种更简便的方法

DartExceptor的工作原理

DartExceptor是一个轻量级的、不依赖任何外部库的Dart 3包。它实现了我在前一篇文章中提到的那种模式：`Trace`、`Ok`、`Err`，以及一些专门为这种模式设计出来的单子操作函数，从而使得这些功能可以被反复使用。

这个包不需要依赖`dartz`库，也不需要`Freezed`或`build_runner`。它只需要`Trace`、两种实现方式以及四个方法而已。

dependencies:
  dart_exceptor: ^1.1.2

import 'package:dart_exector/dart_exceptor.dart';

这就是全部设置内容了。

核心类型

DartExceptor中的每一个操作都会返回一个`Trace`对象：

• T代表成功的结果类型

• E代表错误的结果类型

`Trace`对象只有两种实现方式：

return Ok(user);                                    // 表示操作成功
return Err(AppException(code: 404, e: 'Not found')); // 表示操作失败

你永远不能直接创建`Trace`对象。你应该返回`Ok`或`Err`，然后在其他地方通过这些类型来处理相应的结果。函数签名本身就已经清楚地说明了可能发生的情况：

Future> getUser(String id);

任何看到这个函数签名的人都能立刻明白：这个操作要么会成功并返回一个`User`对象，要么会失败并抛出一个`AppException`异常。六个月后，这种设计依然非常合理、易于理解。

API接口：四个方法，每个方法负责处理一项具体的任务

如果前一篇文章中提到的`Result`类型包含了`map`、`flatMap`以及用于模式匹配的`when()`函数，那么DartExceptor也是沿用了同样的结构，但将其优化成了四个专门针对特定任务的函数。

`split`函数：退出点的关键

通过`split`函数，你可以离开`Trace`对象所代表的处理流程。由于必须同时使用成功处理和错误处理的逻辑，因此你绝对不能不小心忽略任何可能的失败路径。

result.split(
  data: (user) => print(user.name),
  e: (e) => print(e.message),
);

map：提取数据并执行转换操作

map方法能够从Ok结果中提取数据，并允许你直接对这些数据进行处理或转换：

final activeUsers = result.map(
  data: (users) => users.where((u) => u.isActive).ToList(),
);

mapError：提取数据但转换失败

mapError与map的作用相反，它用于处理转换过程中出现的错误。当数据的异常类型与业务逻辑层的期望不同时，这个方法非常有用：

final domainError = result.mapError(
  e: (e) => AppException(code: e.statusCode, e: e.toString()),
);

bind<B>：返回Trace值的链式操作

bind<B>才是真正执行核心处理操作的组件。它允许你将那些本身会返回Trace值的操作串联起来，从而在每一步都对数据类型进行转换。如果其中任何一步失败，后续的所有操作都会被自动跳过。

result
    .bind<User>>(
      n: (users) {
        try {
          return Ok(users.firstWhere((u) => u.id == id));
        } catch (e) {
          return Err(AppException(code: 404, e: '用户未找到'));
        }
      },
    )
    .bind<String>>(n: (user) => Ok(user.firstName))
    .split(
      data: (name) => print('用户：$name'),
      e: (e) => print('错误：${e.e}'),
    );

List<User>类型被转换为User类型，然后再被转换为String类型。每个bind<B>操作都会改变数据的类型，编译器会检查每一步的处理过程；如果链式操作中的任何一步失败，整个处理流程就会直接跳转到split方法中的错误处理部分。这其实就是上一篇文章中讨论的flatMap机制的逻辑延伸。

这种模式在清洁架构中的应用

原始文章中介绍的这个模式，其意义并不仅仅在于语法结构本身。它的真正目的是让各种层次中的错误都能被清晰地显示出来。DartExceptor正好能够完美契合这种架构设计，且无需进行任何修改：

// 数据层
abstract class DataSource {
  Future<Trace<>List<>User>>, AppException>> getAllUsers();
}

// 存储层
abstract class IUserRepository {
  Future<Trace<>List<>User>>, AppException>> getAllUsers();
}

// 业务逻辑层
class UserUseCase {
  Future<>Trace<>List<>User>>, AppException>> getAllUsers() => repository.getAllUsers();
}

// 表现层
void loadUsers() async {
  final result = await useCase.getAllUsers();

  result.split(
    data: (users) => print('加载了${users.length}个用户'),
    e: (e) => print('失败原因：${e.e}'),
  );
}

相同的层次结构、相同的分离方式，以及相同类型的错误处理路径——只不过无需每次都重新编写基础代码。

为什么不直接使用 dartz 呢？

前一篇文章已经详细介绍了 dartz 中的 Either 模型，如果你的团队对它的 API 接口感到熟悉，并且也不担心依赖关系带来的问题，那么它确实是一个非常不错的选择。

DartExceptor 的适用场景更为有限——当你只需要结果类型的模式，却不想引入基于 Haskell 风格函数式编程约定的库时，DartExceptor 就非常适合。它没有 Left/Right 这样的类型，也没有 fold 等函数，更不存在传递性依赖关系。它只需要 Trace、Ok、Err 以及四个方法，这些方法可以直接对应前一篇文章中介绍的实际使用方式。

dependencies:
  dart_exceptor: ^1.1.2