最近在把一套 Flutter 项目从 Android 往 OpenHarmony 上迁移时第一个让我专门停下来重新设计的不是业务页面而是已经维护了两年的三方库 api_exception_manager。它在原来 Android 和 iOS 双端项目里的职责很明确全局网络异常拦截、统一错误归因、任务生命周期治理。说白了App 里所有请求的超时、断网、业务报错以及页面销毁后的异步任务清理都归它管。到了鸿蒙上这套逻辑不能直接从 Java 和 Kotlin 平移到 ArkTS而且它恰好是一个把 Dart 层和原生层串起来的插件所以适配难度比普通业务代码高出不少。这篇文章不是 SDK 文档的翻译而是我实际迁移过程中的完整记录。里面包括了哪些能力能直接复用、哪些必须重写、全局异常拦截在 OpenHarmony 上怎么做才不丢数据以及任务生命周期管理从 Flutter 引擎侧到 UIAbility 侧的桥接方案。如果你也在做 Flutter 库的鸿蒙适配或者准备把现有 App 迁到鸿蒙生态这篇应该能帮你少踩几个坑。1. 这个库在我的项目里到底管了哪些事1.1 没有统一治理时的网络错误长什么样做过 Flutter 网络层的同学应该都体会过这种场景Dio 的 onError 回调分散在各个模块里有人把超时错误提示成“网络异常”有人把业务错误码直接抛给 UI更常见的是页面已经销毁后异步任务还在跑最终回调访问了 dispose 之后的 State控制台里刷出一串 Unhandled Exception。这些问题单独看都不致命但累积到一定规模就会变成线上排查的灾难现场——同一个接口的错误在十个模块里有十种表现形式。我项目里实际出过一次比较典型的线上事故服务端高峰期超时客户端一个页面里有 6 个并发请求同时出错因为每处都自己处理错误结果弹了 6 个不同的错误提示框而且其中一个页面已经切走了错误回调还在往 ViewModel 里塞状态。当时排查了很久才发现是某个模块的 catch 分支没有判断 mounted。这个教训直接让我决定把网络异常统一收口。治理前后的差别可以用一张表简单对照维度治理前治理后超时提示各模块自行弹窗文案混乱统一文案、统一 UI 行为请求重试部分模块有本地重试大量重复代码重试策略集中配置全程可观测失败归因依赖开发翻日志信息零散统一 traceId 加阶段标记一键溯源页面销毁后回调偶发 Unhandled Exception任务被取消回调被安全拦截业务错误码各端映射逻辑不一致单一错误码归因器1.2 api_exception_manager 的核心抽象方式api_exception_manager 这个库做的事可以概括成三个层面。第一是异常模型统一。它把 DioException、SocketException、业务错误码甚至是本地缓存读写失败全部包装成统一的 ApiException 对象带上错误码、发生阶段、堆栈、请求上下文。业务层不需要关心底层是什么异常来源只需要处理一种类型。第二是拦截器链。在请求发出前和响应返回后各有一个拦截环节前者处理鉴权、链路追踪 ID 注入后者处理错误归一化、重试判断、降级策略。拦截器链不是简单的 List 遍历每层拦截器都消费异常并返回一个 ActionResult决定是放行、重试、降级还是终止。第三是任务生命周期管理。它内部维护一个 TaskManager每个网络请求都会被注册成一个 Task关联到当前的页面或业务 scope。页面销毁时统一取消未完成的任务并且对已经排队的回调做安全检查避免销毁后还收到网络响应。这套设计在 Android 上的实现依赖了 Activity 的 lifecycle 回调和网络状态监听而这两块恰恰是迁移到 OpenHarmony 时最先要动刀的地方。我适配时定下的原则是Dart 层只做协议和调度不改任何对外 API把“感知系统生命周期”“获取网络状态”“收集原生侧异常堆栈”这三类能力抽成 Platform 接口分别写 Android 实现和 OpenHarmony 实现。这样上层业务代码在换平台后一行都不用改。2. 鸿蒙适配的第一道坎Flutter 插件的平台层改造2.1 OpenHarmony 上 Flutter 插件的目录结构与脚手架Flutter 插件在 OpenHarmony 上的工程结构和标准 Flutter 插件相比多了一个 ohos 目录api_exception_manager/ ├─ lib/ # Dart 代码跨端复用 ├─ android/ # Android 原生实现 ├─ ios/ # iOS 原生实现 ├─ ohos/ # OpenHarmony 原生实现ArkTS │ ├─ index.ets # 插件入口需要实现 FlutterPlugin 接口 │ ├─ src/main/ets/ # 实际原生逻辑 │ └─ build-profile.json5 # 鸿蒙构建配置 └─ pubspec.yaml有一个细节值得注意OpenHarmony 社区对 Flutter 插件的规范还在演进不同版本的 SDK 对插件注册方式有细微差异。我在适配时锁定了社区维护的 flutter_flutter 分支版本没有追最新主分支因为稳定版的 API 文档和示例更全遇到问题也更容易在社区找到同路人。这一点对库适配特别重要——库是给所有人用的优先兼容稳定方案而不是追新。在 ohos/index.ets 中插件需要注册原生的 MethodChannel handler。以我用的版本为例核心结构大致是import { FlutterPlugin, MethodCall, MethodChannel } from flutter/engine; export class ApiExceptionManagerPlugin implements FlutterPlugin { private channel?: MethodChannel; onAttachedToEngine(binding: FlutterPluginBinding): void { this.channel new MethodChannel( binding.getBinaryMessenger(), api_exception_manager ); this.channel.setMethodCallHandler((call: MethodCall) { // 处理来自 Dart 侧的方法调用 }); } onDetachedFromEngine(): void { this.channel?.setMethodCallHandler(null); this.channel undefined; } }这里要特别强调 onDetachedFromEngine 里把 handler 置空。Android 插件开发时很多人会漏掉这一步在鸿蒙上一样会踩雷——插件被 detach 之后如果 handler 还活着很容易出现僵尸调用Dart 侧随机收到一条来自旧通道的响应。2.2 原生能力从 Kotlin 平移到 ArkTS原来的 Android 实现里有几件事依赖系统 API迁移到鸿蒙后对应关系如下能力Android 实现OpenHarmony 实现网络状态感知ConnectivityManager NetworkCallback网络管理 API 加系统广播监听生命周期感知Application.registerActivityLifecycleCallbacksEntryAbility.onForeground / onBackground / onDestroy原生线程堆栈Thread.getAllStackTraces目前获取受限采用降级方案崩溃捕获UncaughtExceptionHandler对接系统 crash 日志服务实际写下来发现前两类在鸿蒙上都有关键 API 可用只是回调时机和 Android 不完全一样。而“原生线程堆栈”这一项OpenHarmony 上目前能拿到的信息比 Android 少我的处理是降级只采集 Dart 层堆栈加上请求启动时的时间戳和 Task 状态足够定位绝大多数网络问题不纠结于完整的原生线程栈。另外还要注意 ArkTS 的语法风格和 Kotlin 差异很大最明显的是空安全处理更严格。Kotlin 里一个可空类型用?.就带过去了ArkTS 里对 nullable 的检查要求更细稍不注意就会出现编译告警。我迁移时出现过一次比较典型的编译不过一个成员变量可能在 onBackground 之前没被初始化ArkTS 编译器要求必须显式判空才能使用被迫把所有晚初始化字段都改成了undefined初始化加运行时校验。2.3 方法通道的类型映射差异Flutter 的 MethodChannel 在 Android 上和鸿蒙上的类型映射有细微差异。Android 标准映射里 Java 的 Map、List、Int 都有明确对应鸿蒙 ArkTS 侧通过兼容层做转换实际踩到的坑是Dart 侧传 Int64 类型的 ID 给鸿蒙原生时到达 ArkTS 侧后可能变成 number 或 string取决于通道序列化方式。这会导致原生侧用严格相等比较时判断失败进而引发回调匹配不到任务的 bug。我的解决方案很土但很有效在所有跨通道传递的 ID、时间戳、错误码上统一使用 String 类型禁止传数字。虽然多了一次字符串转换的开销但对通道消息来说完全可以忽略而且彻底规避了类型不一致造成的隐性 bug。这个规范也写进了团队的三方库开发文档里后续其它插件做鸿蒙适配时直接沿用。3. 全局网络异常拦截的适配实操3.1 异常模型统一与拦截链设计适配第一件事是保证 Dart 侧对外 API 不变。库原来的用法大致是ApiExceptionManager.instance.configure( onException: (ApiException e) { // 统一处理埋点、提示、上报 return ExceptionAction.retry; }, retryCount: 2, retryDelay: const Duration(milliseconds: 500), );底层拦截链我拆成了三段请求拦截器、响应拦截器、异常归因器。请求拦截器负责把 Task 注册到 TaskManager并注入 traceId响应拦截器把各种底层异常翻译成 ApiException异常归因器根据错误码决定重试、降级还是直接抛给业务层。在鸿蒙适配中没有改这个模型因为 Dart 层并不关心底层是哪个平台发的请求。核心代码结构大致是这样class ExceptionInterceptorChain { final ListExceptionInterceptor _interceptors []; void process(ApiException exception, TaskContext context) { var current exception; for (final interceptor in _interceptors) { final result interceptor.handle(current, context); if (result.action ExceptionAction.retry) { _scheduleRetry(result, context); return; } if (result.action ExceptionAction.cancel) { context.task.cancel(); return; } current result.exception ?? current; } } }这里有一个容易被忽略的设计点拦截器链必须持有 TaskContext而不是只持有异常本身。因为重试和降级都需要知道当前任务的剩余次数、所属 scope、是否已经被页面取消。如果没有 TaskContext拦截器就只能做纯静态判断无法感知动态的任务状态。3.2 重试、降级与熔断的开关配置对网络异常做重试不是无脑重试我在库里的默认配置是超时、断网、连接重置可重试最多 2 次指数退避500ms 到 1000ms4xx 业务错误不重试直接进入业务提示5xx 服务端错误可重试 1 次但如果连续 3 次 5xx触发熔断10 秒内不再发起新请求重试逻辑放在异常归因器里而不是放在 Dio 拦截器之外是为了保证重试也经过异常模型统一归因避免某次重试失败后错误信息风格突变。鸿蒙适配中有一个和 Android 不同的点OpenHarmony 的网络栈在部分设备上对弱网场景的表现不如 Android 稳定DNS 解析偶尔会卡到 3 秒以上。所以我把超时配置从原来的 connectTimeout 10 秒、receiveTimeout 15 秒调整为 connectTimeout 15 秒、receiveTimeout 20 秒并且把 DNS 解析失败归入可重试集合。这个调整在实测中把弱网场景的请求成功率从 96.1% 提到了 98.7%代价是错误提示晚出现几秒但用户感知反而是变好的——因为多数情况下重试一次就成功了。注意一个细节熔断状态是全局共享的不是单请求维度。我实现了一个简单的滑动窗口计数器在原生层保持同步。这样即使同时有多个请求并发失败熔断也能生效而不是每一个请求都单独重试把自己打成对服务端的二次攻击。3.3 把异常上报做扎实避免假阳性异常模型接好、拦截链跑通之后我发现线上上报的“断网异常”数量异常高后来一查不是真的断网而是 OpenHarmony 上部分设备在冷启动后网络权限尚未完成初始化时第一个请求就发出去直接被底层判定为 no route to host。这些请求发生在网络能力就绪之前属于典型的假阳性。处理方案是在请求拦截器里加一个网络就绪闸门调用一个由原生侧提供的 isNetworkReady 能力如果返回 false请求统一进入延时队列等网络状态广播确认就绪后再发出。这个闸门只在 App 冷启动后的前 5 秒内启用避免影响正常请求速度。我特意没有把闸门做成永久性的否则每次请求都多一次原生调用反而引入额外延迟。同时上报逻辑本身也要做缓冲。原来 Android 端异常上报是直接走 OkHttp 打点到统计服务鸿蒙上我改成了先写入本地缓冲队列每 10 秒批量 flush 一次。好处是避免异常风暴时打爆链路层坏处是如果应用被强杀最后几秒的缓冲数据会丢。但在实际场景里丢几秒的统计数据和打爆网络栈两者之间我选前者。4. 任务生命周期管理别等引擎告诉你要自己感知4.1 Flutter 自带生命周期的盲区Flutter 里开发者最熟悉的是 WidgetsBindingObserver.didChangeAppLifecycleState它能收到 resumed、inactive、paused、detached 这些状态。但这套机制感知的是 Flutter 引擎所在窗口的生命周期在鸿蒙上有两个明显盲区。第一应用的 UIAbility 已经 onBackground但 Flutter 引擎的 paused 可能延迟几百毫秒才到这段时间内的异步任务可能在错误时机执行。第二页面级的销毁比如用户从最近任务里划掉应用Flutter 侧可能直接走到 detached但中间不会给业务层一个明确的“立即取消所有任务”的信号。在 Android 上我可以用 LifecycleObserver 精确拿到 onStop、onDestroy鸿蒙上对应的则是 EntryAbility 的 onBackground、onDestroy。这些回调需要桥接到 Dart 层才能让 TaskManager 在正确的时间点做清理。无视这个盲区的后果是任务取消时机不稳定部分状态回调泄漏到销毁后的页面里用户体感就是偶发闪退或者页面复用异常。4.2 UIAbility 生命周期到 Dart 层的桥接我在 ohos 侧使用 EventChannel 把生命周期事件推送到 Dart 侧// EntryAbility.ets import { UIAbility } from kit.AbilityKit; export default class EntryAbility extends UIAbility { onBackground() { // 通过 EventChannel 广播给 Dart LifecycleBridge.instance?.sendEvent(onBackground, { timestamp: Date.now(), }); } onDestroy() { LifecycleBridge.instance?.sendEvent(onDestroy, { timestamp: Date.now(), }); } }Dart 侧在 TaskManager 里订阅_lifecycleChannel.receiveBroadcastStream().listen((event) { final name event[name] as String; if (name onBackground || name onDestroy) { _taskManager.cancelAllTasks(reason: name); } });这里有一个值得细说的点onBackground 时我并不是立即取消所有任务而是标记任务进入“迟到风险”状态给一个 5 秒的宽限期。因为后台立即取消任务会导致用户切回 App 时那些本来马上能返回结果的请求全部需要重发。5 秒之后仍未完成的任务才强制取消并触发错误归因器生成一个“任务被生命周期中断”的 ApiException。这个宽限期设计来自一次真实事故用户在看新闻详情页时切到微信回消息不到 10 秒切回来发现详情页空白重新加载了一遍。原因就是 onBackground 后所有请求被立即取消。加了宽限期后短后台切换的任务成功率明显提升。4.3 在生命周期节点做任务清理的真实收益库内置的 TaskManager 会记录每个任务的启动时间、绑定的业务 scope、当前状态。业务层在页面销毁时只需要调用ApiExceptionManager.instance.taskManager .cancelTasksByScope(pageScopeId);被取消的任务在回调层会收到一个 CancelledException而不是静默消失。这样做的核心收益是杜绝 Unhandled Exception以及避免回调在销毁后的 State 上执行。实测接入这套生命周期管理后崩溃日志里的 LateInitializationError 和 Unhandled Exception 数量减少了大概八成。另外要注意鸿蒙侧 UIAbility 的 onDestroy 触发时机在部分设备上可能晚于 Flutter 引擎 detach所以我在 TaskManager 里加了一道兜底当 Flutter 引擎侧收到 detached 时把该应用会话内所有 scope 的任务全部取消。两道清理逻辑是互补关系不能互相替代。只依赖其中任何一边都会有漏网之鱼。生命周期事件在适配过程中实际上组成了这样一套处理矩阵系统事件Dart 收到时机TaskManager 动作onForeground引擎 resumed 前约 200ms解除后台暂停标记允许新任务入队onBackground引擎 paused 前约 500ms启动 5 秒宽限期不立即取消宽限期超时精确计时触发强制取消未完成任务生成中断异常onDestroy引擎 detach 前或后设备差异立即取消当前 scope 全部任务engine detached引擎生命周期终点兜底取消全部任务5. 实测中踩过的一组坑及其排查链路5.1 任务取消事件滞后导致的回调泄漏第一次跑通完整链路后发现一个诡异问题页面已经销毁网络请求已经被 TaskManager 标记为 cancelled但过了一会控制台还是打印出了网络回调。排查链路是这样的。先怀疑取消逻辑没执行打印日志确认 TaskManager 确实在 onDestroy 触发了 cancelTasksByScope。再怀疑任务没有真正中断Dio 的 cancel 确实会让请求抛 CancelledException这点也验证过了。最后才发现问题不在请求侧而在响应侧请求已经发出原生层 hold 住的 HttpClient Future 并没有因为 cancel 而真正 abortDart 层 Future 提前完成后回调链路上那个陈旧的 Future 仍然执行了 onSuccess 分支。解决方法是在 Task 内部维护一个 cancelled 标志位所有回调在分发前先检查标志位if (_taskCancelled || !scope.isActive) return;这个标志位检查发生在 Future.then 之前而不是之后保证已经排队回调的 Future 也过不了闸门。这个改动看起来简单但确实需要回调分发和任务状态更新之间严格按照“先更新状态再触发取消通知”的顺序执行否则状态更新晚于通知就会出现竞态。5.2 网络状态监听的重复注册另一个坑出现在鸿蒙侧网络状态监听上。Android 实现里我在 Application 初始化时注册一个全局网络回调鸿蒙侧也照着做了但忽略了 UIAbility 的 onForeground 和 onBackground 多次切换导致的监听器重复注册。第一次测试时只是多打印两行日志没在意直到线上出现“网络状态回调风暴”的告警同一个广播在一秒内触发了 37 次把拦截器里的降级逻辑反复触发部分请求被重复重试。修复方式很直接在 onBackground 中注销网络监听在 onForeground 中重新注册并确保注册前注销旧实例。但这里又引出一个新问题重新注册之间如果有几毫秒间隙恰巧来了网络状态变化就会丢失一次状态通知。所以我改成在 unregister 前先把当前状态缓存register 后立刻用缓存补发一次状态。这套“先缓存后重注册再补发”的处理既避免了重复监听又不丢事件。排查这类问题的经验是不要只盯着实现代码看先确认平台回调的注册和注销是不是成对出现。鸿蒙侧的 UIAbility 生命周期方法和 Android 的 Activity 生命周期非常相似但应用模型下回调触发次数和嵌套关系不完全一致最容易出的问题就是“只注册不注销”。5.3 在 OpenHarmony 上验证稳定性的方法库适配完最怕的是“本机跑通了但不敢保证线上稳”。我这边验证稳定性用的是一套组合拳。第一用 OpenHarmony 官方的 XTS 认证套件跑基础兼容性测试重点看应用状态切换和网络异常注入这两类用例。XTS 认证测试对开发者来说不是可选项鸿蒙生态分发时这是硬门槛早跑早发现问题别等适配全部完成后才去碰。第二在弱网环境下做真实场景模拟。用路由器限速和丢包工具把上下行延迟调到 800ms 以上、丢包率 5%重跑首页 20 个接口的全链路用例。主要观察三件事超时后重试是否触发、任务取消后是否还有回调泄漏、降级方案是否在预期时间内生效。第三做小范围真机验证覆盖不同 SoC 方案和系统裁剪程度的设备。OpenHarmony 的碎片化比 Android 好一些但不同设备厂商对系统裁剪程度不同生命周期回调时序会有差异。有的设备 onDestroy 会先于 Flutter engine detach有的会反过来。我建议在库的初始化阶段输出一份“生命周期时序诊断日志”把 UIAbility 回调、Flutter 引擎状态、TaskManager 事件统一打点。上线后如果遇到生命周期相关异常直接拉日志对照不用再靠猜。这个诊断日志帮我定位了至少三次来自设备差异导致的任务取消顺序问题。6. 一点个人经验与后续计划这次适配最终没有改 Dart 层任何对外接口所有平台差异都被压在 ohos 原生层和少量 Dart 内部适配代码里。这个结果符合我一开始定的原则三方库做鸿蒙适配优先保证 API 稳定让上层业务迁移成本趋近于零。实际交付后项目里其他模块接鸿蒙的过程也确实没有遇到因为异常库引发的额外改动。如果接下来你还想在这个方向上继续深入我个人建议优先研究两件事一是 OpenHarmony 上 Flutter 引擎的渲染落地方式它会直接影响页面销毁时生命周期回调的精确时机二是库的自动化测试建设把生命周期时序和异常拦截链路的用例用 flutter_test 和鸿蒙侧集成测试一起固化下来。稳定性的价值往往在平台切换那一刻体现得最明显。最后分享一个小技巧做鸿蒙适配时别急着把原生能力一次性配齐先跑通一条最核心的链路比如“请求失败、异常模型转换、任务取消”这一段把基础打通后再往上叠加网络监听、堆栈采集、冷启动闸门这些能力。每加一块就回归一次之前的用例。整个适配过程会可控很多出问题时也容易定位。这个节奏比一次性重写全部逻辑再集中调试要高效得多。