Flutter鸿蒙适配实战：类型化结果处理与错误自愈机制

做 Flutter 组件适配鸿蒙这件事，圈内普遍把注意力放在"能不能跑起来"——编译过了、页面能开、接口通了，就觉得适配完成。但真正上生产之后，最头疼的恰恰是"跑起来之后出错怎么办"。我这次把一个内部用的轻量级结果封装组件 okay 从标准 Flutter 环境迁移到鸿蒙端，表面看只是一个包的移植，实际花时间的全在另外三块：结果类型的语义建模是否贴合鸿蒙的异常模型、函数式错误处理链在跨平台边界上能不能保持行为一致、以及错误已经暴露之后业务逻辑能不能自己"缓过来"。这篇实战记录就是把这三块拆开讲透，适合正在做 Flutter 鸿蒙适配的团队，也适合想在 Dart 侧引入类型化结果处理和自愈机制的开发者。整篇会涉及具体的数据结构设计、扩展方法实现、重试/降级/熔断的落地代码，以及过程中踩过的一堆坑。

1. 项目背景：适配的不只是 API，而是异常语义

1.1 为什么拿 okay 这个组件当切入点

先说清楚背景。团队在某跨端项目里大量使用一个叫 okay 的内部组件，它做的事情很单纯：给 Dart 提供一套类型化的 Result 包装，把"成功值"和"失败原因"统一收进一个类型，再配上 map、flatMap、recover 之类的函数式操作，让异步错误处理从"抛出和捕获"变成"返回和匹配"。

这套写法在标准 Flutter 环境跑得很稳，直到鸿蒙适配提上日程。第一轮适配我们把 UI 层、路由、本地存储全都过了一遍，编译没问题，页面能开，但一跑长时间场景就开始出现"说不清"的崩溃。典型症状有三种：平台通道调用偶尔返回的异常对象，类型结构和 Dart 侧预期对不上；底层服务返回了错误码，但错误码的语义在鸿蒙和标准 Flutter 之间不一致，同是一个"超时"，一端叫 timeout，另一端叫 "ERR_TIMED_OUT"，还可能带个数字后缀；更恶心的是偶发的资源释放时序问题，上层拿到一个被"污染"的结果，内存里的字段还是对的，但状态已经不可用。

这些问题的共性在于：它们不是某一处代码写错了，而是两套系统的异常语义没有对齐。这时候 okay 组件反而成了最适合的改造载体——它的结果包装层天然是错误信息的"集散地"，只要在这里做一次规范化，上层业务代码就不需要关心跑在哪个平台。

1.2 这次适配给自己定的三个目标

目标不能含糊，我一开始就写清楚了三条：

• 第一条，okay 提供的 Result 类型在鸿蒙端与标准 Flutter 端行为完全一致，上层业务代码不需要分平台写两套判断逻辑；
• 第二条，所有平台通道的错误在进入 Dart 侧之前，统一被转换成标准的 Failure 结构，包含错误码、错误信息、原始对象和堆栈，谁也别想着偷懒直接抛个字符串上来；
• 第三条，在结果包装之上叠加逻辑自愈能力，某个操作返回 Err 时，系统能根据失败分类自动决定重试、降级还是熔断，而且这个过程对业务方透明。

说白了，适配的核心不是把"能用的代码搬过来"，而是把"错误的表达方式"变成一套两端都听得懂的语言，再让系统具备一定程度的自我恢复能力。下面按这三条逐一展开。

2. 类型化结果包装：把异常变成数据

2.1 Result 的数据模型为什么这么设计

okay 的核心不复杂，一个密封类加两个子类就构成了骨架：

dart复制sealed class Result<T> {
  const Result();
}

final class Ok<T> extends Result<T> {
  final T value;
  const Ok(this.value);
}

final class Err<T> extends Result<T> {
  final Failure failure;
  const Err(this.failure);
}

这里有两个设计决策值得展开说。第一是使用 sealed class，这是 Dart 3 开始支持的特性，配合 switch 表达式可以做穷尽检查，编译器会强制要求你处理所有分支。如果你在业务代码里漏掉了 Err 分支，编译期就会给出警告，这把"可能出错"这件事提前暴露在编码阶段，而不是等到运行期崩了才回头查。

第二是 Err 里不直接放 Exception 对象，而是放一个 Failure 结构体。这一点是适配鸿蒙时的关键决策，Failure 的定义如下：

dart复制class Failure {
  final String code;
  final String message;
  final Object? cause;
  final StackTrace? stackTrace;
  final FailureKind kind;

  const Failure({
    required this.code,
    required this.message,
    this.cause,
    this.stackTrace,
    this.kind = FailureKind.unknown,
  });
}

为什么要包一层 Failure 而不是直接放异常？我实测下来的体会是：异常对象在跨语言、跨边界传输时，类型信息会严重丢失。标准 Flutter 里 catch 到一个 PlatformException，还能拿到 code 和 details；但鸿蒙端的通道回调数据格式更杂，可能是一个纯字符串错误码，可能是一段序列化后的 Map，甚至可能是 null。如果不做一层归一化，上层代码就会被迫写一堆"if (e is PlatformException) ... else if (e.code == 'xxx') ..."式的判断，那整个错误流就失控了。

2.2 从 try-catch 到模式匹配的范式切换

引入 Result 之后，最直观的变化是错误处理的阅读方式变了。以前是典型的"保护性"写法：

dart复制try {
  final data = await repository.fetchUser(id);
  _render(data);
} on TimeoutException {
  _showRetry();
} on ApiException catch (e) {
  if (e.code == 401) {
    _redirectLogin();
  } else {
    _showError(e.message);
  }
}

现在变成：

dart复制final result = await repository.fetchUser(id);
result.match(
  onOk: _render,
  onErr: (failure) => switch (failure.kind) {
    FailureKind.timeout => _showRetry(),
    FailureKind.unauthorized => _redirectLogin(),
    _ => _showError(failure.message),
  },
);

两者看似只是写法差异，实际差别很大。try-catch 的问题在于异常沿着调用栈向上传播，中间任何一层函数忘了捕获，错误就会"穿透"到最外层，最后统一弹一个"网络异常"了事，真正的原因被层层吞掉。而 Result 把错误显式地放在返回值里，调用方必须处理，否则从代码结构上就不完整。另一个对团队很实在的好处是测试友好，构造一个 Err 只需要 new 一个 Failure，比"模拟某个方法在特定时机抛异常"简单太多。

3. 鸿蒙端函数式异常处理实践

3.1 适配层核心改造：平台通道错误归一化

真正的适配工作量集中在这里。Flutter 在鸿蒙上运行时，Dart 侧和原生侧的通信走的是通道机制，但鸿蒙端的实现和 Android 端有细节差异，最明显的一点是错误回传的格式不统一。我在适配层加了一个叫 NativeErrorInterpreter 的转换器，职责只有一个：把从平台通道回来的任何"异常形态"转成标准 Failure。

dart复制class NativeErrorInterpreter {
  static Failure interpret(Object? raw, String fallbackCode) {
    if (raw is Failure) return raw;
    if (raw is PlatformException) {
      return Failure(
        code: raw.code,
        message: raw.message ?? 'platform error',
        cause: raw,
        stackTrace: raw.stackTrace,
        kind: _inferKind(raw.code),
      );
    }
    if (raw is Map) {
      final code = raw['code'] ?? raw['errCode'] ?? fallbackCode;
      return Failure(
        code: code.toString(),
        message: raw['message']?.toString() ?? raw['msg']?.toString() ?? 'unknown',
        cause: raw,
        kind: _inferKind(code.toString()),
      );
    }
    return Failure(
      code: fallbackCode,
      message: raw?.toString() ?? 'unknown error',
      kind: FailureKind.unknown,
    );
  }
}

这段代码乍看简单，但里面有一个核心思路：永远不要假设平台会给你什么类型，而是把"解释错误"做成一个独立层。_inferKind 根据错误码前缀推断失败类型，比如超时类错误码映射为 FailureKind.timeout，权限类映射为 FailureKind.unauthorized。这一步不做，后面的自愈策略根本没有依据去分支。

3.2 扩展方法：map、flatMap、recover 的实现要点

okay 用起来顺不顺手，完全取决于扩展方法实现得是否到位。我保留了最核心的四个：

dart复制extension ResultOps<T> on Result<T> {
  Result<R> map<R>(R Function(T) fn) => switch (this) {
        Ok(:final value) => Ok(fn(value)),
        Err(:final failure) => Err(failure),
      };

  Result<R> flatMap<R>(Result<R> Function(T) fn) => switch (this) {
        Ok(:final value) => fn(value),
        Err(:final failure) => Err(failure),
      };

  T recover(T Function(Failure) fn) => switch (this) {
        Ok(:final value) => value,
        Err(:final failure) => fn(failure),
      };

  Result<T> retry(int times, Duration Function(int attempt) delay) =>
      _retryWithBackoff(() async => this, maxAttempts: times);
}

map 用于对成功值做纯转换，错误原样传递；flatMap 用于串联多个可能失败的操作，语义类似异步世界里的 Promise 链；recover 是从错误中恢复出默认值，适合缓存兜底场景。

适配过程中我特别盯了一个细节：flatMap 传入的回调本身抛了异常怎么办。按照标准实践，实现里要把回调包在 try-catch 里，捕获后转成 Err，否则链式调用会在运行期直接炸掉，这等于绕过了整套类型化结构。我在内部实现里是这么处理的：

dart复制Result<R> flatMap<R>(Result<R> Function(T) fn) {
  switch (this) {
    case Ok(:final value):
      try {
        return fn(value);
      } catch (e, st) {
        return Err(Failure(code: 'callback_error', message: e.toString(), cause: e, stackTrace: st));
      }
    case Err(:final failure):
      return Err(failure);
  }
}

这个细节容易被忽略，但恰好是适配鸿蒙时最容易踩的位置——很多异常是在跨桥之后的回调里才触发的，不兜住就会漏出去。

4. 逻辑自愈架构：当错误成为常态

4.1 自愈的四层设计

所谓"逻辑自愈"，我的理解是系统在遇到非致命错误时，能够不重启、不人工介入，通过预定义策略把状态恢复到可用水平。这次我在 okay 基础上封装了四层自愈机制，从里到外分别是重试层、降级层、熔断层、状态恢复层。

重试层针对 FailureKind.timeout、FailureKind.network 这类瞬时错误，自动做有限次重试。重试间隔用指数退避加抖动实现：

dart复制Future<Result<T>> _retryWithBackoff<T>(
  Future<Result<T>> Function() action, {
  int maxAttempts = 3,
  Duration initialDelay = const Duration(milliseconds: 200),
}) async {
  for (var attempt = 0; attempt < maxAttempts; attempt++) {
    final result = await action();
    if (result is Ok<T>) return result;
    final failure = (result as Err<T>).failure;
    if (!failure.kind.isRetryable || attempt == maxAttempts - 1) {
      return result;
    }
    final delay = initialDelay * (1 << attempt) +
        Duration(milliseconds: Random().nextInt(100));
    await Future.delayed(delay);
  }
  return Err(Failure(
    code: 'max_retry_exceeded',
    message: 'retry failed after $maxAttempts attempts',
    kind: FailureKind.retryExhausted,
  ));
}

这里我踩过一个很实际的坑：最初没加抖动，结果多个请求同时进入退避重试，退避时间一到就集体重发，形成"惊群效应"，瞬时把下游打崩了。加上随机抖动之后，重试请求的分布明显平滑，接口压力小了很多。

降级层负责在重试仍然失败时，根据失败类型挑选降级方案。常见的有三种：缓存兜底，从本地缓存返回旧数据并标记为过期数据；默认值兜底，返回一个预设的合理空值；功能裁剪，某个推荐模块挂了就隐藏掉，而不是让整个页面白屏。选择哪种降级，本质上是业务权衡，但"宁可展示旧数据也不要白屏"这条原则在移动端基本通用。

熔断层解决的是"下游已经不行了就别再打它"的问题。当某个依赖连续失败达到阈值，短期内直接快速失败，不发起真实请求，给下游喘息时间。我实现里用了一个轻量的滑动窗口计数器：

dart复制class CircuitBreaker {
  final int failureThreshold;
  final Duration openDuration;
  CircuitState _state = CircuitState.closed;
  int _consecutiveFailures = 0;
  DateTime? _openedAt;

  bool get canAttempt {
    if (_state == CircuitState.open) {
      if (DateTime.now().difference(_openedAt!) >= openDuration) {
        _state = CircuitState.halfOpen;
        return true;
      }
      return false;
    }
    return true;
  }

  void recordFailure() {
    _consecutiveFailures++;
    if (_consecutiveFailures >= failureThreshold) {
      _state = CircuitState.open;
      _openedAt = DateTime.now();
    }
  }

  void recordSuccess() {
    _consecutiveFailures = 0;
    _state = CircuitState.closed;
  }
}

熔断在单客户端场景下的主要价值不是保护下游，而是省电、省流量、避免用户等待一个注定失败的请求。半开状态很关键，它允许少量试探请求通过，试探成功就关闭熔断，失败则重新打开。

状态恢复层是前面三层的兜底。重试、降级、熔断都是把"当前这一次请求"救回来，状态恢复则是把"整个模块的状态"救回来。做法是在关键业务节点做轻量状态快照，检测到连续 Err 时触发快照回滚，确保 UI 不会停在"半加载"的尴尬状态。这个快照不用全量，只保存影响渲染的关键字段。

4.2 自愈策略必须绑定业务语义

落地过程中最需要注意的一点：自愈策略不能拍脑袋定，必须绑定业务语义。同样是 Err，超时和权限不足的策略完全相反，权限不足时重试一万次也没用，直接跳登录才对。我在 Failure 上预留的 kind 字段，就是给策略层做决策用的。

策略绑定可以整理成一张规则表：

规则表在实际项目里可以演化成配置文件，让产品同学调整阈值而不用改代码。但项目还不大的时候建议先用代码写死，别一上来就上配置中心，很容易过度设计。我见过不少团队把自愈策略做成了"万能配置系统"，结果配置本身比业务代码还难维护。

5. 常见问题与排查技巧实录

5.1 四个高频坑位

第一个坑：错误类型透传时丢失原始堆栈。鸿蒙侧抛出的异常，Dart 侧 catch 后 stackTrace 经常是空的，排查问题非常痛苦。解决方法是适配层把原始错误对象完整放进 Failure.cause，打日志时把 cause 的完整 toString 打出来，不要只打 message。这个习惯帮我省了大量定位时间。

第二个坑：Result 泛型在 Dart 运行时的类型信息有限。Dart 泛型在运行期不是完全可用的，尤其在列表、动态调用等场景里，is Ok 这种判断可能出现误判。规避方式是避免对 Result 做运行时泛型收窄，尽量在 match 回调里做类型处理，把类型信息留在编译期解决。

第三个坑：鸿蒙端的线程模型差异。Flutter 引擎在鸿蒙上的平台通道回调，个别场景不在主 isolate 上，直接在回调里操作 UI 会偶发崩溃。解决方法是所有经过 Result 的回调统一通过一个 dispatcher 切回主 isolate。这个 dispatcher 必须在 SDK 层封装好，不能指望业务方记得。

第四个坑：重试导致状态副作用。如果重试的操作不是纯函数，内部修改了计数或缓存，重试两次等于副作用执行了两次。处理办法是要求 retry 的操作满足幂等性，或者在重试前做一次状态快照与回滚。我项目里就出现过一次：某个上报接口重试后，埋点重复计数，数据直接翻倍。

排查问题多了，我整理了一张速查表：

5.2 几个值得保留的调试技巧

调试函数式错误处理链，最大的难点是"看不到过程"。普通 try-catch 至少能打断点，但 map、flatMap 这种链式调用，执行过程是分散的，一步错就整链断。我的做法是在扩展类里加一个只见于开发模式的 tapped 方法：

dart复制Result<T> tapped(void Function(Result<T>) visitor) {
  visitor(this);
  return this;
}

这样就能在链路任何位置插入观察点：

dart复制final result = await fetchUser(id)
    .tapped((r) => logger.d('fetchUser => $r'))
    .map((u) => UserViewModel.from(u))
    .retry(2, (i) => Duration(milliseconds: 300 * i));

另一个建议：调试阶段把自愈策略关掉，让错误完全透明。做法是加一个全局配置 selfHealingEnabled，默认 true，debug 模式下强制置为 false。这样重试次数归零、熔断阈值设成无限大，所有错误会直接暴露，一次性看清所有拦截点。这个开关帮我省了很多时间，否则错误被重试和降级悄悄吞掉，你会一直觉得"好像什么错误都没发生"。

最后分享一个小技巧：给 FailureKind 加一个 classify 方法，统一从原生错误码分类到 kind。鸿蒙端不同模块返回的错误码风格差异很大，有的用字符串，有的用数字，有的带前缀，classify 里维护一张映射表，新模块接入时只需要注册错误码区间，不用动上层逻辑。实测下来，"错误码注册制"比散落在各处的 if-else 要稳得多，也顺带让自愈策略的规则表有了统一的输入维度。