Flutter鸿蒙适配：用Result包装与错误码分级实现异常自愈

如果你维护过一个跑了两年多的 Flutter 业务项目，第一次听到要把组件适配到鸿蒙时，心里最先跳出来的大概率不是 UI 怎么排，而是那些在 Android/iOS 上行之有效的异常处理，到鸿蒙上还能不能靠得住。我这边陆续适配过首页信息流、扫码、地图、文件上传等几个模块，最直观的感受是：跨端边界是异常最容易失真的地方，而且失真之后，Dart 侧拿到的往往根本不是一个异常，而是一个奇怪的空值、一个把原始错误吞掉的通用错误码，甚至是一段断成两截的堆栈字符串。

这篇文章想分享的，就是我们在这个适配过程中沉淀下来的一套组合方案：用类型化结果包装（Result）把鸿蒙桥接层的异常变成数据流，再基于错误码分级做重试、熔断、缓存兜底和状态重建，最终让组件具备一定程度的逻辑自愈能力。内容偏工程实战，适合正在做多端适配、或者已经遇到“调用原生方法后什么都没发生”这类诡异问题的 Flutter 团队参考。

1. 鸿蒙适配里最常见的三种“假成功”：异常并没有被安全传递

1.1 跨语言调用栈被截断，Debug 信息直接失去意义

Flutter 跑在鸿蒙上，业务代码在 Dart 虚拟机里，原生能力在鸿蒙的原生侧实现。中间隔着 MethodChannel 的序列化、反序列化、消息路由和结果回调。这一层一旦出错，最典型的现象就是：Dart 侧捕获到的异常并不是“原生方法抛出来的那个异常”，而是“通道在传递异常时包装出来的另一个异常”。

比如在 Android 上，你抛出一个带错误码的自定义异常，Flutter 侧收到的是PlatformException，code 还能对上，message 也能看到。换到鸿蒙适配层之后，原生侧抛出的异常往往在边界被转成了一段字符串，或者直接变成了一个泛化的失败回调，原始堆栈已经断掉。你在 Debug 面板里看到的那几行堆栈，并不是真正出错的堆栈，而是消息回调被拒绝时的堆栈。

这种情况下，沿用“哪里不对就 try/catch 一把”的习惯，会发现 catch 到的信息没有足够线索去定位问题。我一度遇到过这样的场景：Harmony 上一个系统服务偶发不可用，原生侧捕获到异常后返回给 Dart 侧的是一个 null 值，而 null 恰好又是业务层允许出现的合法状态，于是页面就走了一个异常分支，看起来是“成功完成了”，实际上数据根本没回来。

1.2 空返回值与类型坍缩，是比异常更隐蔽的坑

鸿蒙适配初期，很多 Flutter 组件直接调用原生方法时，完全没有想过原生侧会“不抛异常但返回一个空”。空值本身不可怕，可怕的是它在序列化层会被压缩成null，然后 Dart 侧再想当然地把null转换成一个强类型对象。

我之前遇到的一个真实情况是：调用原生扫码能力，正常情况下返回一个Map，包含二维码内容、类型、时间戳。在鸿蒙适配层没有注册对应实现时，通道返回的并不是MissingPluginException，而是一个空结果。Dart 侧代码拿到空结果后走了解析分支，Map为 null，解析器抛NullCheckError，这个错误又出现在 UI 线程的某个异步回调里，直接导致页面崩掉。

这类问题比显式的PlatformException难查得多，因为表面上没有任何一个环节告诉你“这个能力没接上”。你只会在线上看到一堆莫名其妙的空指针崩溃，却看不到真正的根因。

1.3 通道静默失败：回调没有结果，也没有异常

还有一种更恼人的情况：通道调用发出去之后，既不返回成功，也不返回失败，而是彻底没有回调。原生侧可能因为在异步初始化过程中某个资源没准备好，先把调用忽略了；也可能是后台线程异常退出，没有走完 result 回调。Dart 侧await一直挂着，页面永远停在加载中。

这类问题靠 try/catch 根本挡不住，因为连异常都没有。你要么给所有通道调用加超时保护，要么在架构上把“无回调”定义成一种可观测的结果类型。后续的方案里我们把超时和空回调统一并入了 Result 的失败分支，才真正把这类问题管住。

2. 从 try/catch 到数据流：我为什么在鸿蒙适配中先做结果包装

2.1 先写最基础的 Ok/Err，再决定要不要换 sealed class

结果包装不是什么新概念，Kotlin 里有 Result，Swift 里有 Result，Dart 生态里也有各种封装。核心思想很简单：让函数返回一个“要么成功、要么失败”的容器对象，而不是靠异常来传递失败。

在鸿蒙适配项目里，我最开始并没有直接引入第三方库，而是自己写了一个非常小的 Result。因为适配阶段桥接面很杂，先用最小实现跑通，后面再根据业务反馈迭代才更稳妥。

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

如果你们项目对应的 Flutter 分支还不支持 Dart 3 的 sealed class，退一步用抽象类加两个子类完全够用，关键是“成功值和失败信息必须同时出现在返回类型里”这个原则。

2.2 Failure 里面到底装什么才有诊断价值

很多团队写 Result 的时候只放一个 message 字符串，这在跨端适配里远远不够。因为 message 很可能是原生侧翻译过的文案，原始错误码、原始堆栈、序列化后的 details 都得保留下来，才能在后端日志里还原问题。

class Failure { final int code; final String message; final Object? raw; final StackTrace? stack; const Failure( this.code, this.message, { this.raw, this.stack, }); }

code 必须是稳定定义的错误码，不能直接用PlatformException.code返回的字符串。因为同一个字符串在 Android、iOS、鸿蒙上可能完全不同，统一映射之后业务层才能写重试逻辑。raw 字段用来装原生侧传过来的原始 details，可能是一个 Map、一段 JSON 字符串，也可能是一个整数，保留它的意义在于：如果错误码映射得不准，至少还能从原始材料里找线索。

2.3 “不抛异常”的收益在鸿蒙多模块适配中被放大

在单平台上，try/catch 的问题还不算大，最多是堆栈浅一点。但在鸿蒙适配中，一次业务操作可能横跨 Flutter 组件、通道层、原生侧 SDK、系统服务四个层面，任意一层抛异常，异常都必须穿透三层边界。穿透一次，信息就丢一层。

改成 Result 之后，异常不再需要“穿透”，而是在每一层边界被捕获、转换成错误码，然后继续作为正常返回值向后传递。每一层都有机会补充上下文信息，也可以根据错误码决定是否直接终止链路。这个收益在调用链越深、参与层越多的时候越明显。

3. 桥接层固化：MethodChannel 的错误码表、空值守卫与载荷还原

3.1 原生侧只做一件事：把异常变成结构化 Map

鸿蒙适配过程中，我最先改造的不是业务代码，而是所有自建平台的通道封装。原生侧统一在函数入口处捕获所有异常，输出结构化的 Map 结果，而不是抛PlatformException。

原生侧简化后的返回结构只有两种：

// 成功 { "ok": true, "data": ... } // 失败 { "ok": false, "errorCode": 10005, "message": "service unavailable", "raw": ... }

这个约定可以避免很多不必要的争议：原生侧不用关心 Flutter 侧怎么解析，只管保证任何异常路径都必须返回一个合法的 Map，绝不抛出。原生侧什么时候可以抛异常？我的建议是永远不要对 Flutter 的调用抛异常，因为 Dart 侧解析跨语言异常的成本远高于解析一个 Map。

3.2 Dart 侧统一封装 invokeWrapped

Dart 侧我写了一个统一封装，替换了原先所有直接调用invokeMethod的地方。

extension MethodChannelResultExt on MethodChannel { Future<Result<T>> invokeWrapped<T>( String method, { Object? arguments, T Function(Object? json)? decoder, }) async { try { final raw = await invokeMethod<Object?>(method, arguments); if (raw == null) { return const Err(Failure( ErrorCodes.nullReturn, 'native returned null', )); } if (decoder == null) { return Ok(raw as T); } return Ok(decoder(raw)); } on PlatformException catch (e) { return Err(Failure( ErrorCodes.fromPlatform(e.code), e.message ?? 'platform exception', raw: e.details, )); } on MissingPluginException catch (e) { return Err(Failure( ErrorCodes.missingPlugin, e.message ?? 'missing plugin', )); } catch (e, st) { return Err(Failure( ErrorCodes.unknown, e.toString(), raw: e, stack: st, )); } } }

这里最关键的是两点：一是先把 null 挡在门外，避免解析层再报空指针；二是 decoder 参数，原生返回的原始数据先经过它转换成强类型对象，转换失败也归一到 Err 分支，而不是让类型转换异常逃逸出去。

3.3 错误码分级：哪些可以重试，哪些直接放弃

有了统一封装，下一步就是定义错误码表。我们在项目里用了五位数分码，有一个关键动作：把错误码按照“是否可以重试”做了分级。这直接影响后续自愈策略的走向。

“是否可重试”这个信息非常重要，因为如果对“权限被拒”这类错误做自动重试，用户会看到多次弹窗；如果对“参数非法”做重试，永远都是无效消耗。错误码分级之后，后续的重试器只需要查一张表，不需要业务方传一个复杂的规则对象。

4. 函数式异常处理的组合子集合：map、flatMap、waitAllResult

4.1 让业务代码用 fold 收敛分支

Result 封装完之后，最大的风险是业务代码在每个地方都写 if/else 判断，结果比原来更啰嗦。要解决这个问题，就必须给 Result 配上几个基础组合子。

extension ResultOps<T> on Result<T> { Result<R> map<R>(R Function(T value) transform) { return fold( ok: (v) => Ok(transform(v)), err: (f) => Err<R>(f), ); } Result<R> flatMap<R>(Result<R> Function(T value) transform) { return fold( ok: transform, err: (f) => Err<R>(f), ); } T getOrElse(T fallback) { return fold(ok: (v) => v, err: (_) => fallback); } }

有了这些组合子，业务代码就能从层层嵌套的 if/else 里走出来。原来你可能要写“先判断第一个调用是否失败，再决定要不要发起第二个调用”，现在 flatMap 直接把失败链路短路掉，链条之后的代码天然不需要处理失败，因为失败已经在链条上被携带了。

4.2 并行加载多个原生能力的聚合

鸿蒙适配里，一个页面同时拉取多个原生能力的场景非常多，比如首页卡片既要读本机设备信息，又要拉账号状态，还要读缓存配置。如果复用 Future.wait，只要其中一个原生能力失败，整个 Future.wait 就会短路，这不符合“部分失败也可以展示”的业务诉求。

我写了一个简单的waitAllResult：

Future<Result<List<T>>> waitAllResult<T>( Iterable<Future<Result<T>>> tasks, ) async { final settled = await Future.wait(tasks); final failures = settled.whereType<Err<T>>().toList(); if (failures.isNotEmpty) { return Err(Failure( ErrorCodes.batchFailed, '${failures.length} sub tasks failed', raw: failures, )); } final values = settled .whereType<Ok<T>>() .map((result) => result.value) .toList(); return Ok(values); }

它的语义是：只要有一个子任务失败，整体返回失败；但失败信息里会带上所有子任务的失败明细，不会像 Future.wait 那样直接丢失其余结果。如果业务需要“部分成功也能展示”，我建议再扩展一个方法，返回一个包含每个子项结果的列表，由 UI 层分别展示成功和失败区块。

4.3 老组件过渡期如何处理

很多存量 Flutter 组件不可能一夜之间全部改成 Result。过渡期的做法是双轨并行：新桥接方法全部走 Result，老组件继续用 try/catch 把 Result 再转回异常，给业务方留一个迁移缓冲期。

Future<T> unwrapOrThrow<T>(Future<Result<T>> resultFuture) async { final result = await resultFuture; return result.fold( ok: (value) => value, err: (failure) => throw failure, ); }

这个兼容函数的意义在于：渠道侧可以先推广 Result，不需要一次性推动所有业务代码改造。等新组件上线验证稳定后，再从核心链路逐层替换。我测过一段时间的双轨运行，只要桥接层统一，两边结果是一致的，不会出现行为分裂。

5. 逻辑自愈：重试、熔断、兜底缓存和状态重建

5.1 出错重试不能盲目，要按错误码分级

有了 Result 和错误码分级，重试逻辑终于可以做得有依据了。最简单有效的是指数退避重试：第一次失败等 1 秒，第二次等 2 秒，第三次等 4 秒，最多三次；中间只要返回 Ok 或返回错误码不可重试，立即停止。

Future<Result<T>> retryWithBackoff<T>( Future<Result<T>> Function() task, { int maxAttempts = 3, Duration baseDelay = const Duration(seconds: 1), }) async { var attempt = 0; while (attempt < maxAttempts) { final result = await task(); if (result is Ok) { return result; } final failure = (result as Err).failure; if (!failure.isRetryable) { return result; } attempt++; if (attempt >= maxAttempts) { return result; } await Future.delayed(baseDelay * attempt); } return task(); }

这里注意一点：不要在重试期间无脑打印日志。每重试一次就输出一条 WARN 日志，用户只要遇到一次网络波动，日志量会翻好几倍。更合理的做法是最后一次失败才输出完整日志，前几次失败只更新一个计数器。

5.2 端侧轻量熔断器，避免雪崩

重试能解决瞬时故障，但害怕的是“系统服务已经彻底不可用”。这个时候如果所有页面都按自己的重试策略疯狂重试，原生侧会被打成一团，这就是典型的雪崩。

端侧不需要把熔断做得太复杂，我实现了一个非常轻量的版本：连续失败达到阈值后，接下来的 N 秒内直接短路，所有的调用立刻返回一个不可重试的失败，不再真正访问原生侧。

class CircuitBreaker { final int failureThreshold; final Duration openTimeout; int _failureCount = 0; bool _opened = false; DateTime _openedAt = DateTime.now(); CircuitBreaker({ this.failureThreshold = 3, this.openTimeout = const Duration(seconds: 10), }); bool get canAttempt => !_opened || _openedAt.add(openTimeout).isBefore(DateTime.now()); void onSuccess() { _failureCount = 0; _opened = false; } void onFailure() { _failureCount++; if (_failureCount >= failureThreshold) { _opened = true; _openedAt = DateTime.now(); } } }

熔断器必须和错误码分级协同。10002（原生超时）、10005（系统服务不可用）这类错误才计入失败计数；“权限被拒”这种用户行为导致的失败不应该触发熔断，否则会误伤正常的业务功能。我在接入时是把熔断器挂在单个通道的封装层，而不是全局共享，避免一个模块的故障冻掉所有模块。

5.3 本地缓存兜底与状态重建

重试和熔断解决的是“调用失败后怎么办”，还有一种场景是“调用失败后，组件还应该保持可用”。这时候本地缓存兜底就非常有效。我的做法是维护一个内存缓存，键是方法名加参数签名，值是上次成功返回的强类型结果。

class FallbackCache<T> { final Map<String, T> _cache = {}; Future<Result<T>> withFallback( Future<Result<T>> Function() task, String cacheKey, ) async { final result = await task(); if (result is Ok<T>) { _cache[cacheKey] = result.value; return result; } final cached = _cache[cacheKey]; if (cached != null) { return Ok(cached); } return result; } }

注意缓存兜底和正常的返回成功要区分开。如果直接返回 Ok，业务层会以为这是最新数据，可能导致用户在界面上看到过时信息。所以缓存兜底返回的概念应该是“降级成功”，我在实战里给 Result 再包了一层isFromCache标记，让 UI 层知道可以展示但必须提示“离线数据”。

状态重建也是自愈的重要部分。有些组件内部维护了一个状态机，异步任务失败后，旧状态没有被清理，下一个动作又基于错误状态继续执行，越走越歪。自愈的关键在于：任何异步调用返回 Err 时，组件都必须明确告诉自己“我现在处于哪个状态”，是初始态、加载态、错误态还是降级态。我倾向于把所有状态都声明为 sealed class，强制编译器帮我堵住遗漏的分支。

sealed class FeedState { const FeedState(); } class FeedInitial extends FeedState { const FeedInitial(); } class FeedLoading extends FeedState { const FeedLoading(); } class FeedData extends FeedState { final List<Object> items; const FeedData(this.items); } class FeedError extends FeedState { final Failure failure; const FeedError(this.failure); }

5.4 自愈表现如何看见：把 Result 接入埋点

逻辑自愈不是写完就完了，你还需要知道它是真的在自我修复，还是只是把问题掩盖了。我们的做法是给 Result 增加一个统一的观测入口：每次返回 Err 时，把错误码、是否重试、是否熔断、是否命中缓存兜底这些信息上报。

持续观测下来有几个很有价值的指标：自愈成功率（重试后成功次数 / 总失败次数）、熔断触发率、缓存兜底命中率。如果某个接口的缓存兜底命中率居高不下，说明真实网络成功率已经很低，这个接口应该优先排查根因，而不是继续依赖自愈兜底。自愈是用来缓冲问题的，不是用来消灭问题的。

6. 一次完整改造复盘：首页信息流组件从频繁异常到自动恢复

6.1 症状诊断：没人抛异常，但页面频繁卡死

这里分享一个具体的改造案例。某个首页信息流组件，在适配鸿蒙后线上反馈不断，症状非常一致：进入页面后偶尔会发生“卡死”，既不报错也不崩溃，界面停留在加载动画上，没有任何按钮响应。

初期排查很痛苦，因为日志里没有任何异常堆栈。后来我们把组件的外层包了一层runCatching加上链路追踪，才发现问题出在一个原生能力调用上：组件每次进页面要同时拉取推荐位配置、账号状态和用户画像，三个调用并行执行，其中一个能力在鸿蒙原生侧偶发回调丢失，导致对应的 Future 永远 pending，信息流首屏就一直等在这个调用上。

异常没有抛出来，try/catch 当然接不住。这就是前面提到的“通道静默失败”的典型形态。

6.2 分阶段改造顺序

这个组件没有被我们推倒重写，而是按顺序做了四步改造。

第一步，把所有并行调用从Future.wait换成waitAllResult，同时给每个调用加 5 秒超时。超时返回错误码 10002，立刻解决了“永远 pending”的问题。这一步效果立竿见影，页面不再无休止卡住。

第二步，将三个调用统一接入 Result。这一步看起来只是换返回类型，实际价值在于日志里终于能看到“哪个子任务失败、错误码是什么、原始 details 是什么”了。定位速度提高了不少。

第三步，按错误码接入重试和熔断。10002 和 10005 进入重试流程，连续失败三次后熔断 10 秒，熔断期间直接使用本地缓存展示上次成功数据，UI 顶部显示“内容可能不是最新”的降级标识。

第四步，把组件状态改成 sealed class 的状态机，Err 不再被直接吞掉，而是统一收敛到 FeedError 状态。用户下拉刷新时，FeedError 状态允许再次发起异步调用；用户在错误态点击重试时，行为也是一致且可预期的。

6.3 上线后的测量与踩坑

上线两周后测下来的变化：信息流首屏卡死率降到接近零，原来偶发的一类“莫名白屏”也彻底消失。故障发生时的日志完整度从原来的不到 40% 提升到了 100%，每一条失败都能在埋点里看到错误码、重试次数和兜底情况。

踩坑也有两处。第一处是超时时间设置，最初设成了 3 秒，鸿蒙原生侧在启动阶段有时会超过 3 秒才能返回，导致超时误报。后来改成“首次 5 秒、重试时 8 秒”两档，误报大幅减少。第二处是缓存兜底的数据源，最初直接把内存缓存作为唯一兜底，App 重启后缓存全丢，降级就失效了。后来加了持久化缓存，兜底效果才稳定。

最后再分享一个小技巧

在实际操作中，我发现这套方案最忌讳的是“只改桥不还债”。如果桥接层全部换成 Result，业务层却还在到处 unwrap 后再转回异常，等于白做。理想的节奏是每换一个原生调用，就把调用它的核心链路一起改到 Result 风格，不要把技术债留到后面。

另外，建议给所有底层通道封装加一个测试开关：模拟返回null、模拟返回超时、模拟返回错误码 10005，分别验证组件在对应情况下的状态迁移是否合理。这个开关在后面对接真实鸿蒙设备的各种复杂情况时，能帮你省掉大量联调时间。