Dart中高级错误处理技术：记录对象、结果类型、单子以及冻结异常

catch (e)这个语句会捕获所有类型的错误：变量名拼写错误、空指针异常、真正的网络请求失败——所有这些错误都会被统一处理到同一个catch块中。如果不查看具体的错误信息，就无法区分这些错误的类型，而这种做法本身就非常不可靠。

错误在传递过程中会丢失其类型信息： 当API层抛出的UnauthorizedException到达视图模型层时，它就已经变成了一个普通的Object对象，所有的结构化信息都消失了。

解决这个问题的方法就是：让错误成为函数签名、类型系统以及编译器检查中不可或缺的一部分。本文介绍的各种模式正是为了实现这一目标而设计的。

第1部分：将记录类型作为轻量级的结果容器

什么是Dart记录类型？

Dart 3.0引入了记录类型——这种匿名且不可变的值类型允许人们将多个字段组合在一起，而无需编写完整的类定义。

// 一个包含两个命名字段的记录类型
({String name, int age}) person = (name: 'Seyi', age: 28);

print(person.name); // 输出：Seyi
print(person.age); // 输出：28

记录具有结构化类型特性——只要两个记录的字段名称和类型相同，那么它们就属于同一类型，无论这些字段是在哪里定义的。此外，记录是不可变的，并且是通过值来进行比较的，而不是通过引用。

记录作为结果类型

在错误处理中，记录最简单的应用方式就是将成功与失败编码为一种包含可空字段的单一返回类型：

typedef Result = ({E? e, T? data});

这种定义创建了一种包含两个可空字段的记录类型：e用于表示错误信息，data用于表示成功结果。其规则很简单：这两个字段中必定只有一个是非空的。

// 成功时——数据存在，e为null
Result result = (e: null, data: user);

// 失败时——e存在，data为null
Result result = (e: '用户未找到', data: null);

与异常处理方式相比，这种设计已经有了显著的改进。返回类型明确告诉调用者：该函数可能会返回数据，也可能会返回错误信息。失败情况本身就是该函数接口的一部分。

你还可以为应用程序的不同层次定义更具体的类型别名：

typedef ApiResult = ({T? data, E? exception});
typedef SecurityResponse = {bool? isSecured, String? error};
typedef Repository = ApiResult;

每个类型别名都为这种记录结构赋予了一个有意义的名称，从而使得在每次调用该类型时都能清楚地理解其用途。

密封类作为命名空间构造函数

每次都需要手动创建结果记录，这种做法既重复又容易出错。最简洁的解决方案就是使用密封类来为静态工厂方法提供一个统一的命名空间：

sealed class Res {
  static Result success(T data) => (e: null, data: data);
  static Result failure(E e) => (e: e, data: null);
}

需要注意的是，这里的sealed关键字并不是用于实现多态性的。这种类不能被实例化，它的存在纯粹是为了将两个相关的静态方法放在一个有意义且不可扩展的命名空间中。

使用这种方式后，代码结构会变得更加清晰、有条理：

// 在仓库模块中
Future> getUser(String id) async {
  try {
    final user = await _api.fetchUser(id);
    return Res.success(user);
  } on NetworkException catch (e) {
    return Res.failure(iException.internet(message: e.message));
  }
}

对于Dio框架特有的响应类型，也可以采用同样的模式：

sealed class DioResult {
  static ApiResult success(T data) => (data: data, exception: null);
  static ApiResult failure(E exception) => (data: null, exception: exception);
}

对于那些需要使用简化类型别名的仓库级结果类型，可以这样实现：

// GET 实际上就是 ({E? e, T? res})
typedef New = GET;

sealed class R {
  static New success(T data) => (e: null, res: data);
  static New failed(iException error) => (e: error, res: null);
}

每个密封类的命名空间都只负责处理一种特定的功能，并且对应于应用程序中的某一层结构。

特定领域的记录类型

对于那些不符合通用成功/失败模式的特定领域结果类型，使用记录结构也能很好地满足需求：

typedef SecurityResponse = ({bool? isSecured, String? error});

sealed class Check {
  static SecurityResponse isSecured() => (isSecured: true, error: null);
  static SecurityResponse isInsecured(String error) => (isSecured: false, error: error);
}

使用方法如下：

final check = Check.isSecured();
if (check.isSecured == true) {
  // 继续执行后续操作
}

final check = Check.isInsecured('Certificate validation failed');
print(check.error); // 输出：Certificate validation failed

这种记录结构清晰、易于理解，而且能够自我说明功能用途。它能让你清楚地知道这个函数返回的是什么类型的数据。

基于记录的结果类型要求你必须手动检查哪些字段是非空的。编译器不会强制你处理这两种情况，也没有内置的方法可以在不手动解包数据的情况下转换结果。因此，在这种情况下，使用合适的密封型结果类型就显得十分必要了。

第2部分：构建合适的密封型结果类型

AppResult密封类

密封型结果类型的优势在于：它利用Dart的类型系统，使两种可能的结果状态在结构上变得截然不同，并提供了when()方法，强制调用者在编译时就考虑这两种情况。

import 'appfailure.dart';

sealed class AppResult {
  const AppResult();

  R when({
    required R Function(T value) success,
    required R Function(AppFailure failure) failure,
  });
}

class AppSuccess extends AppResult {
  const AppSuccess(this.value);

  final T value;

  @override
  R when({
    required R Function(T value) success,
    required R Function(AppFailure failure) failure,
  }) {
    return success(value);
  }
}

class AppFailureResult extends AppResult {
  const AppFailureResult(this.error);

  final AppFailure error;

  @override
  R when({
    required R Function(T value) success,
    required R Function(AppFailure failure) failure,
  }) {
    return failure(error);
  }
}

让我们仔细分析一下这些设计决策的合理性。

sealed class AppResult：`sealed` 这个关键字意味着所有的子类型都必须位于同一个文件中，编译器能够了解所有可能的子类型。正是这一特性使得穷举模式匹配成为可能。T表示在操作成功时返回的数据类型。

AppSuccess：用于存储实际的结果数据。当对AppSuccess对象调用when()方法时，系统会始终执行success回调函数，并将结果值传递给该函数。

AppFailureResult：用于存储错误信息。当对AppFailureResult对象调用when()方法时，系统会始终执行failure回调函数。需要注意的是，即使这个对象不包含任何实际数据，它仍然带有T类型标注——这种设计确保了两种子类型都能与AppResult类型兼容。

when()方法：这是整个机制的核心。这两个回调函数都是必须存在的；编译器会强制要求你必须同时处理成功和失败这两种情况。你不能忽略错误路径，也不能忽略成功路径。到底是哪条路径会被执行，是由对象本身来决定的——而不是由调用代码中的if/else语句来决定的。

// 这个仓库函数会返回AppResult类型的结果
Future> login(String email, String password) async {
  try {
    final user = await _api.login(email, password);
    return AppSuccess(user);
  } on UnauthorizedException {
    return AppFailureResult(AppFailure.unauthorized());
  } on NetworkException {
    return AppFailureResult(AppFailure.network());
  } catch (e) {
    return AppFailureResult(AppFailure.unknown(e.toString()));
  }
}

使用when()处理结果

final result = await _repository.login(email, password);

result.when(
  success: (user) => emit(AuthState.authenticated(user)),
  failure: (error) => emit(AuthState.error(error.message)),
);

你也可以使用when()来返回其他类型的数据：

// 返回Widget类型的结果
final widget = result.when(
  success: (user) => UserProfileCard(user: user),
  failure: (error) => ErrorView(message: error.message),
);

// 返回字符串类型的结果
final message = result_when(
  success: (data) => '欢迎回来，${data.name}',
  failure: (error) => '发生了错误：${error.message)',
);

when()会自动推断返回类型R；无论两个回调函数返回什么类型，when()都会返回相同类型的值。如果它们返回的是Widget，那么最终得到的也是Widget；如果它们返回的是String，那么最终得到的也是String。

为什么这种设计更好

第3部分：扩展到Monad模式

什么使某物成为Monad？

Monad是函数式编程中的一种模式。从实际角度来看，当某种类型满足以下三个条件时，它就被视为Monad：

包装功能——你可以将一个值放入相应的上下文中。

AppSuccess(user) // 将User封装到AppResult中

转换功能（map）——你可以在不手动解包的情况下，对被包装的值应用某个函数。如果转换结果表示失败，那么这个转换操作就会被跳过，失败状态也会直接传递下去。

链式操作功能（flatMap）——你可以按顺序执行多个操作，而这些操作都会返回相同类型的封装结果，而且无需使用嵌套结构。一旦出现第一个失败，整个操作链就会立即停止执行。

如上所定义的AppResult类型满足了第一条规则，同时也符合通过when()实现的第二条规则的“精神”。但是，如果没有map和flatMap》方法，它就不符合Monad的严格定义。让我们来补上这些缺失的部分。

sealed class AppResult {
  const AppResult();

  /// 转换成功的结果，失败的状态则保持不变
  AppResult map(R Function(T value) transform) {
    return when(
      success: (value) => AppSuccess(transform(value)),
      failure: (error) => AppFailureResult(error),
    );
  }

  /// 链式执行多个操作，每个操作都会返回一个AppResult类型的结果
  AppResult flatMap(AppResult Function(T value) transform) {
    return when(
      success: (value) => transform(value),
      failure: (error) => AppFailureResult(error),
    );
  }

  R when({
    required R Function(T value) success,
    required R Function(AppFailure failure) failure,
  });
}

final loginResult = await login(email, password);

loginResult.when(
  success: (user) async {
    final profileResult = await getProfile(user.id);
    profileResult WHEN(
      success: (profile) async {
        final settingsResult = await loadSettings(profile.settingsId);
        settingsResult WHEN(
          success: (settings) => emit(AppState.ready(settings)),
          failure: (error) => emit(AppState.error(error)),
        );
      },
      failure: (error) => emit(AppState.error(error)),
    );
  },
  failure: (error) => emit(AppState.error(error)),
);

final result = (await login(email, password))
    .flatMap((user) => getProfile(user.id))
    .flatMap((profile) => loadSettings(profile.settingsId))
    .map((settings) => settings.theme);

result.when(
  success: (theme) => emit(AppState.ready(theme)),
  failure: (error) => emit(AppState.error(error)),
);

dependencies:
  dartz: ^0.10.1

import 'package:dartz/dartz.dart';

typedef API<T> = Either<T, iException>;

// 成功时 —— Left用于存储数据
Either<User, iException>> result = Left(user);

// 失败时 —— Right用于存储异常信息
Either<User, iException>> result = Right(iException.internet(message: '无法建立连接'));

if (result.isLeft()) {
  final user = result.fold((user) => user, (_) => null);
}

class ApiRes {
  static Future<API<T>>> deserialize<T>>(ApiResult<T, iException>> res) async {
    return (res.data != null)
        ? Left(res.data as T)
        : Right(res.exception!);
  }

  static Future<API>> deserializeDynamic(
    ApiResult<dynamic, iException>> res,
  ) async {
    return (res.data != null) ? Left(res.data) : Right(res.exception!);
  }
}

Future> getUser(String id) async {
  // 数据层会返回一条记录
  final res = await _dataSource.fetchUser(id);

  // 在层与层之间的转换点进行类型转换
  return ApiRes deserialize(res);
}

final result = await repository.getUser(id);

result.fold(
  (user) => emit(UserStateLoaded(user)),       // 成功情况
  (exception) => emit(UserState.error(exception.message)), // 失败情况
);

// map — 对左侧的值进行转换
final nameResult = result.map((user) => user.name);

// flatMap / bind — 将多个返回Either类型的操作串联起来
final profileResult = result.flatMap(
  (user) => getProfile(user.id),
);

throw Exception('出了问题');
// 在捕获异常的地方，根本不知道到底发生了什么问题、属于哪种类型的异常，也不知道是哪段代码导致了这个问题。

dependencies:
  freezed_annotation: ^2.4.1

dev_dependencies:
  freezed: ^2.4.5
  build_runner: ^2.4.6

import 'package:flutter/foundation.dart';
import 'package:freezed.annotation/freezed_annotation.dart';

part 'exception.freezed.dart';

@freezed
class iException with _$iException {
  const factory iException.internet({
    required String message,
    int? code,
  }) = InternetException;

  const factory iException.mapper({
    required String message,
    int? code,
  }) = MapperException;

  const factory iException.validation({
    required String message,
    int? code,
  }) = ValidationException;

  const factory iException.unauthorized({
    required String message,
    int? code,
  }) = UnauthorizedException;

  const factory iException.unknown({
    required String message,
    int? code,
  }) = UnknownException;

  const iException._();
}

flutter pub run build_runner build --delete-conflicting-outputs

iException (sealed base)
├── InternetException    — 网络连接失败
├── MapperException      — JSON解析失败
├── ValidationException  — 输入验证失败
├── UnauthorizedException — 认证失败或令牌过期
└── UnknownException     — 用于处理其他未知错误

iException.internet(message: '没有网络连接')
iException.unauthorized(message: '会话已过期', code: 401)
iExceptionvalidation(message: '电子邮件格式无效')
iException.mapper(message: '无法解析UserResponse', code: 500)
iException.unknown(message: e.toString())

因为when、maybeWhen、map和maybeMap等方法来处理各种异常情况：

exception.when(
  internet: (message, code) => '没有网络连接：$message',
  mapper: (message, code) => '解析错误：$message',
  validation: (message, code) => '输入无效：$message',
  unauthorized: (message, code) =>> '未授权——请重新登录',
  unknown: (message, code) => '发生未知错误：$message',
);

所有情况都必须被考虑到；编译器会拒绝那些处理不完整的异常匹配逻辑。你不能不小心只处理了某些类型的异常，而忽略了其他类型。

对于只需要关注特定类型的情况，可以使用以下代码：

exception.maybeWhen(
  unauthorized: (message, code) =>> _redirectToLogin(),
  orElse: () =>> _showGenericError(exception),
);

更简洁的基类getter模式

一旦你理解了这些设计模式所要解决的问题，就会发现它们其实并不复杂。而它们所要解决的问题——也就是那些看不见、无法被强制执行、存在类型安全风险的错误处理机制——正是Flutter应用程序中产生故障的最常见原因之一。

下一步就是将这些设计模式应用到实际项目中去。使用它们肯定能够彻底改善你整个代码库中的错误处理机制及相关流程。