做移动开发的这几年我手机里装得最多的不是娱乐应用而是各种带“异常上报”和“埋点”的调试包。Flutter 项目做久了你会发现一个特别真实的问题应用在开发和验收阶段跑得再顺一上线弱网、断连、后端超时、请求堆积这些“不体面”的事全来了。一开始我也以为加个重试就能解决直到一次线上事故让我意识到容错不是“错误发生后重来一次”而是一整套需要架构设计的弹性调度机制。这次我基于 Flutter 生态里的 polly_dart 三方库在一个需要跑在鸿蒙设备上的项目里做了完整的鸿蒙化落地把重试、熔断、超时、舱壁、回退这些策略真正接进了生产链路。这篇内容我尽量把“为什么这么设计”也讲透而不只是贴一段能用就行的代码。无论你是刚接触鸿蒙 Flutter 开发还是已经在做多端工程化我希望这篇文章能帮你少走一点弯路。1. 项目定位工业级容错到底要解决什么1.1 什么是瞬态故障为什么普通重试不够分布式系统里一个请求从客户端发出到服务端处理完返回中间要经过网络链路、网关、负载均衡、应用服务器、数据库、缓存任何一环发生短时抖动都可能造成请求失败。这类故障有个共同特点它是“瞬态的”稍后重试可能就好了。常见的瞬态故障大概是这几类网络连接超时或直接拒绝连接DNS 解析偶尔失败服务端临时返回 500、503、429连接池里的连接被对端关闭以及设备网络切换后旧连接全部失效。很多人第一反应是“在 catch 里加一个 for 循环失败了就重试几次”。开发环境里这招看起来没问题一上生产就露馅。第一重试次数没有上限时流量高峰所有客户端一起疯狂重试等于给后端火上浇油第二失败后立即重试成功率极低还要白白消耗电量和流量第三不能区分“可重试错误”和“不可重试错误”比如参数校验错误重试一万次也是白搭。polly_dart 做工业级容错的核心理念就是把这些问题从“业务代码里的临时补丁”升级为“一套统一的策略配置”让你对每一种故障类型都有明确的、可预期的处理路径。1.2 鸿蒙 Flutter 场景下的容错需求鸿蒙的设计目标是全场景分布式操作系统所以一个 Flutter 应用跑在手机上、平板上、车机上、智能屏上的情况会越来越多。不同设备的网络环境跨度非常大手机是移动网络和 Wi-Fi 交替平板可能长时间待机后网络重新唤醒车机在隧道、地库信号极差。在这种环境下应用如果只做“失败就弹 toast”的处理体验肯定是灾难级的。而且鸿蒙底层的网络协议栈、线程调度、系统资源回收机制和 Android 并不完全一样网络切换时机、DNS 解析行为、连接超时默认表现都会有一些细节差异。这就让容错组件在鸿蒙 Flutter 应用里的身份从“锦上添花”变成了“刚需”。但鸿蒙化的过程中你也会发现单纯的 polly_dart 移植并不复杂真正复杂的是让它在鸿蒙的运行时、线程模型、生命周期机制下稳定工作并且在出问题时能被观测、能恢复、不会制造新的故障。这也是“弹性调度架构”和“重试几行代码”的本质区别。1.3 我做的这个项目的具体目标当时手头一个 Flutter 应用需要落地到鸿蒙设备上核心模块是数据上报和状态同步对可靠性要求极高。上报不出去后端就收不到设备状态同步断了用户看到的就是数据错乱。我把需求抽成了三条硬性指标。任何一次网络请求遇到瞬态故障要自动恢复但不能放大后端压力。后端整体异常时要能快速打开熔断避免本地无限等待和资源堆积。后端恢复后要能自动半开探测不让服务在恢复窗口期被误杀。这套需求正好是 polly_dart 的看家本领。我基于它做了一层鸿蒙化封装整个架构分成策略层、执行层、观测层三层。后面几节我会一层一层拆开讲。2. 核心策略拆解弹性调度的“五根柱子”2.1 重试策略不要只写“重试 N 次”polly_dart 的重试策略核心 API 是一组链式声明下面这段代码是我在项目里实际用的模板。import package:polly_dart/polly_dart.dart; final retryPolicy Policy .HandleSocketException() .OrTimeoutException() .WaitAndRetry( retryCount: 3, sleepDurationProvider: (retryAttempt) Duration(milliseconds: 300 * (1 retryAttempt)), onRetry: (exception, delay, attempt) { // 把每次重试的原因、退避时间记录下来方便追踪 logger.warning(请求失败准备第 $attempt 次重试, exception); }, );先说 Handle 这一步。它声明这个策略只处理哪些异常。我不建议用HandleException()一把抓因为业务异常和服务端返回的业务错误码与网络断连、超时、连接被重置这些基础设施异常性质完全不同。前者重试没有意义后者重试才有价值。把“可重试异常”显式写清楚是容错配置的第一原则。退避计算用了一个左移运算第 1 次失败等约 300ms第 2 次 600ms第 3 次 1200ms总等待大约 2.1 秒。这样可以让失败后的重试请求错开峰值不至于所有客户端在同一秒内猛攻后端。生产环境建议再叠加一个“抖动”也就是在退避时间上加入随机偏移进一步防止并发客户端在同一个时间点集体发起重试形成惊群效应。提示WaitAndRetry的 sleepDurationProvider 里retryAttempt 一般来说从 1 开始但不同版本的 polly_dart 实现可能略有差异。接入时先打日志看一眼不要想当然。2.2 熔断器给系统装一个总闸重试负责“小事化了”熔断负责“大事止损”。如果没有熔断后端已经不可用时每个请求还在做全量重试资源在本地大量堆积后端恢复后收到的却是海量积压请求很容易再次被打挂。熔断器的逻辑就是一个经典三段状态机。关闭Closed所有请求放行统计失败情况。失败次数达到阈值后状态切换为打开。打开Open不再执行真正的调用直接抛异常或走回退逻辑相当于把闸拉了。半开HalfOpen经过一段恢复时间后放少量探测请求进去成功就回到关闭状态失败则继续保持打开。polly_dart 里对应这样写。final circuitBreaker Policy .HandleSocketException() .OrTimeoutException() .CircuitBreaker( exceptionsAllowedBeforeBreaking: 5, durationOfBreak: Duration(seconds: 30), );两个参数要认真调。exceptionsAllowedBeforeBreaking是熔断触发的失败次数我建议不要设成 1否则任何一次抖动都会把整个服务熔断反而降低可用性也不要设得太大否则熔断器形同虚设。5 次对我们这个场景是比较合适的折中。durationOfBreak是打开状态的持续时间后端局部故障通常几十秒就能恢复30 秒是当时测试下来的值。如果是依赖数据库恢复的场景可以放宽到 60 秒甚至更长但要配合半开探测来验证。注意polly_dart 的 CircuitBreaker 和 .NET Polly 的行为并不完全一致半开状态的探测请求数量、在打开状态抛什么异常都要看具体版本。接入后先用单元测试把状态跳转验证一遍再上真实流量。2.3 超时策略没有期限的任务比失败更危险做后端的人常说失败要快挂起是恶魔。一个请求如果永远不返回调用者会一直占着线程、管道、内存。Flutter 和 Dart 是单线程事件循环模型虽然超时不会阻塞 UI但未完成的 Future 会持续持有资源HttpClient、WebSocket、图片加载都受影响。超时策略就是给所有调用加一条明确的期限。final timeoutPolicy Policy.Timeout( timeout: Duration(seconds: 10), onTimeout: (context, timeout, task) async { logger.warning(请求超过 $timeout已强制结束); throw TimeoutException(request timeout); }, );移动端一个 HTTP 请求的超时通常要分连接超时和读取超时两段来看整体超时应覆盖“发起请求到拿到完整响应”的全过程。我的经验是内部接口给 5 秒外部第三方接口给 10 秒文件上传这类大流量场景单独配更长的时间不要一刀切。超时策略在执行链里通常放在最外层先把“红线”卡住避免内层策略或任务自己拖太久。2.4 舱壁与回退隔离故障的两种手段舱壁设计借鉴的是船舶舱室思路一个舱进水不会让整条船沉掉。落到代码里就是限制并发请求数超出时排队或直接拒绝从而隔离不同服务之间的故障影响。final bulkhead Policy.Bulkhead( maxParallelization: 10, maxQueueingActions: 20, );比如应用同时要调用订单服务、用户服务、日志服务我不希望日志服务一慢就把订单请求的并发额度全部占掉。用 Bulkhead 单独保护低频但不可控的服务保证核心链路始终有稳定的资源配额。回退策略则是在整条策略链最末端兜底。final fallback Policy .HandleException() .Fallback((_) DefaultResponse());重试、熔断、超时都拦不住时最后走回退逻辑返回一个默认值而不是让异常直接冲到 UI 层。对用户来说可能只是短暂看到“加载中”之后出现一个空态页而不是崩溃或白屏。回退值要尽量设计成“对用户可解释”的数据比如缓存里的旧数据或默认空列表这样体验会好很多。2.5 策略组合Wrap 的顺序比你想的更重要单独看每个策略都不复杂真正的复杂度在于怎么组合。polly_dart 提供了Policy.Wrap来拼接策略链。final policy Policy.Wrap([ timeoutPolicy, // 最外层 circuitBreaker, // 中间层 retryPolicy, // 最内层 fallbackPolicy, // 兜底 ]);Wrap 的执行顺序是从外到内。如果你想“先重试重试都不行再熔断”那熔断就要放在重试外层让熔断来统计重试之后的整体结果如果你想“任何单次尝试都不能超过 5 秒”超时就要放最外层约束整个链路。顺序没有绝对标准取决于你的容错目标。我建议画一张简单的执行顺序图贴在看板上团队里每个人都能看明白别让策略链成为一个只有写代码的人能懂的黑盒。3. 鸿蒙化实施一条完整的集成路线3.1 开发环境与 Flutter SDK 对齐鸿蒙的 Flutter 适配目前和官方 Flutter 主线并不完全同步所以第一步不是直接flutter create而是先确定你用哪一套 SDK。我当时走的是 OpenHarmony 社区维护的 Flutter 版本把本地 Flutter SDK 指向对应分支再用它创建项目。git clone -b ohos https://gitee.com/openharmony-sig/flutter_flutter.git export PATH$PWD/flutter_flutter/bin:$PATH flutter config --enable-ohos-platform flutter doctor执行完flutter doctor后可以看到 ohos 相关的 toolchain 信息。接下来创建工程。flutter create --org com.example --project-name resilience_app . flutter create --platforms ohos .工程根目录下会多出一个ohos目录后续 DevEco Studio 打开的就是这个目录。版本对齐是最容易踩坑的地方Flutter 的 ohos 分支版本、DevEco Studio 的版本、HarmonyOS SDK 版本三者必须匹配否则编译期会出现各种莫名其妙的报错。我的建议是直接参考社区 release 页面给出的版本对应表不要自己混搭。混搭的结果往往是“折腾三天最后发现是版本问题”。3.2 在 pubspec.yaml 中引入并验证 polly_dart鸿蒙平台在 Flutter 里对应的平台标识是ohos。polly_dart 本身是纯 Dart 库不涉及原生代码理论上可以直接用但工程上还是要做条件化处理避免未来同时维护 Android、iOS、鸿蒙多端时出现依赖冲突。dependencies: flutter: sdk: flutter polly_dart: ^3.0.0纯 Dart 三方库通常不需要专门为 ohos 写条件依赖但要注意纯 Dart 库也可能间接依赖 dart:io 里的平台实现比如文件路径、网络接口枚举等。如果库内部直接使用了 dart:io 的特定 API在鸿蒙上执行时可能因为平台差异产生问题。接入后建议把库自带的单元测试跑一遍确认在 ohos 设备上没有失败项。鸿蒙化和“换一个 pubspec 配置”并不是一回事。Dart 层的大多数库能直接编译到鸿蒙但真正要关注的是它和原生能力的边界。polly_dart 本身不直接做网络 IO它只编排任务所以你还需要选择鸿蒙上可用的 HTTP 客户端。dart:io 的 HttpClient 在鸿蒙上的实现行为很可能和 Android 有差异比如连接超时默认值、TLS 握手方式这些都要单独验证。3.3 业务代码接入封装带完整容错链的网络客户端下面这段代码是我在项目里实际使用的封装结构去掉了业务细节保留核心骨架。class ResilientApiClient { ResilientApiClient({required this.baseUrl}); final String baseUrl; late final Policy _policyChain _buildPolicyChain(); final http.Client _httpClient http.Client(); Policy _buildPolicyChain() { final retry Policy .HandleSocketException() .OrTimeoutException() .WaitAndRetry( retryCount: 3, sleepDurationProvider: (attempt) Duration(milliseconds: 300 * (1 attempt)), ); final breaker Policy .HandleSocketException() .OrTimeoutException() .CircuitBreaker(5, Duration(seconds: 30)); final timeout Policy.Timeout(Duration(seconds: 8)); return Policy.Wrap([ timeout, breaker, retry, ]); } FutureMapString, dynamic get(String path) async { final response await _policyChain.execute(() async { final resp await _httpClient .get(Uri.parse($baseUrl$path)) .timeout(Duration(seconds: 5)); return resp; }); return jsonDecode(response.body) as MapString, dynamic; } }这里有三个工程级细节值得展开。第一Policy.Wrap 的包装顺序是从外到内执行。我把 timeout 放最外层确保任何一层策略的执行时间都被总超时约束住breaker 放中间层让失败计数只统计真正的网络异常retry 放最内层让单次尝试内部先完成有限重试。这样的结构读起来很清楚先把时间红线卡住再把整体健康状态看住最后处理单次尝试的瞬时抖动。第二http.Client 是长生命周期对象不要每个请求都 new 一个。复用连接池能显著降低弱网下的握手开销但要注意连接池大小和熔断参数的匹配。如果并发连接数大于熔断阈值熔断状态可能被频繁打开导致可用性反而下降。上线前最好用压测数据把这个关系验证清楚。第三不要把 response 里的 Map 直接交给 UI。API 层最好统一返回不可变的数据模型这样以后切回退策略、替换默认值时都会方便很多。容错的一部分目标是让底层变化对上层透明数据模型的统一是基础。3.4 异步任务与并发调度鸿蒙上的弹性执行鸿蒙的 Flutter 应用本质上还是跑在 Flutter Engine 之上Dart 的异步模型是单线程事件循环加 Isolate 多线程。polly_dart 的策略执行不会强制创建新 Isolate所以调度开销非常低。但在鸿蒙设备上一个典型的坑是部分系统回调、平台通道调用可能在原生线程里等待如果容错策略等待了一个永远不会完成的 Future即使外层有超时也可能因为超时后没有正确取消底层调用留下一个悬空任务。我的做法是给所有平台通道调用再包一层可取消执行器。超时策略会抛出 TimeoutException但底层的方法通道调用可能还在运行所以在 onTimeout 里应该主动销毁对应的订阅或会话。final cancellableTimeout Policy.Timeout( timeout: Duration(seconds: 3), onTimeout: (context, timeout, task) async { await taskHandle?.cancel(); // 主动取消底层任务 throw TimeoutException(method channel timeout); }, );超时之后的“善后”比单纯抛异常更能体现工业级容错的价值。容错的最终目标不是把错误掩盖而是把系统恢复到可控状态。这一点在鸿蒙多设备场景下尤其明显因为设备间的协同、网络切换、系统休眠恢复都会产生比普通 Android 环境更复杂的任务生命周期问题。4. 工程化要点与可观测性设计4.1 日志与指标让每一次容错都有据可查容错组件最大的风险是“默默把错误处理了”开发者和运维完全不知道系统正在经历什么。如果线上出了问题你只看到一堆成功响应排查会非常痛苦。所以我在封装时统一埋点。每次策略开始执行的时间点、任务名称每次重试的异常类型、第几次、退避时长熔断器状态变化关闭、打开、半开、关闭超时发生的环节和累计耗时回退触发的次数和原因。我维护了一个简单的事件总线策略回调统一发事件上层可以接日志系统也可以接上报服务。abstract class ResilienceEvent { String get eventType; DateTime get occurredAt; } class CircuitOpenedEvent implements ResilienceEvent { override final String eventType circuit_opened; override final DateTime occurredAt DateTime.now(); } // 在 circuitBreaker 的 onBreak 回调里 // eventBus.publish(CircuitOpenedEvent());这些指标不需要一开始做得很重先把事件打出来后续要画图表、做告警时再把数据接到 APM 平台即可。关键是别在容错逻辑里用 print 了事线上的控制台是看不见的数据必须进日志系统或上报通道。4.2 性能与开销策略链不是免费的每增加一层策略就会增加一次闭包包装、异常捕获、状态更新。对高频接口来说这个开销虽然不大但也不是完全为零。我在真机上做过简单压测一个纯 Dart 的 HTTP 请求不挂策略链时单次请求在 10ms 左右挂上完整链路也就是 timeout 加 breaker 加 retry大约增加 1 到 2ms 调度开销占比约 10% 到 20%。所以瓶颈不在策略本身而在于你挂了多少层。更好的做法是给不同接口配置不同的策略链。核心写接口、状态同步接口用完整链普通读接口只用超时加一次重试日志上报接口只做舱壁隔离。策略不追求全覆盖追求按需覆盖。把最贵的策略留给最不能失败的请求资源才能花在刀刃上。4.3 微观层面小心 Dart 的 Future 错误吞噬Dart 有一个著名的大坑未处理的 Future 异常不会被当前 try/catch 捕获只会进入 unhandled error 回调。在容错策略里很容易写出下面这种代码。// 错误示例 final future policy.execute(myTask); // 不 await // 之后忘记处理 future 的异常一旦 myTask 抛异常而你没有在 Future 链上处理异常就变成 unhandled error。在 Flutter 里可能表现为红屏或控制台刷出一大片错误。好的习惯是任何不 await 的 Future都链上.catchError或者交给专门的事件处理函数不要让它裸奔。这个教训在我做鸿蒙 Flutter 适配时出现过好几次很多“诡异”的运行时问题最终定位下来都是错误吞噬导致的。5. 实操问题与排查记录5.1 编译阶段鸿蒙构建失败先查这三项第一轮接入时我遇到的并不是 polly_dart 本身的报错而是整个工程的依赖树里有某个包在 ohos 构建时出现兼容问题。排查思路其实很固定。先确认 Flutter ohos 分支版本和 polly_dart 的 Dart SDK 约束是否冲突看 pub 的报错信息。再执行flutter pub deps看依赖树找到纯 Dart 包和平台相关包的边界。最后把出错包单独抽出来跑一遍flutter test确认究竟是包的问题还是工程配置的问题。有一个容易忽略的点鸿蒙构建使用的 hvigor 构建链路和 Android 的 Gradle 路径不完全一样。flutter build ohos输出日志里的could not find symbol往往不是 Dart 层的错而是原生 CMake 或 hvigor 配置的问题。看到这类报错优先检查 NDK、CMake 版本和 ohos 构建工具链是否匹配。5.2 运行阶段熔断不生效多半是异常没被 Handle 命中我调试过最诡异的一个问题熔断器配置得明明白白但故障时一直不触发熔断请求在日志里全都在报错熔断状态却一直是关闭。后来跟到源码才发现业务层在调用底层网络库时把 SocketException 包成了自定义的 ApiException而我的熔断策略只 Handle 了 SocketException 和 TimeoutException自定义异常根本不在匹配范围内。解决办法是两层。一是策略里再把 ApiException 纳入匹配二是在封装 API 层时保持异常类型语义清晰不要把底层 IO 异常全部吞掉再重新包装否则上层策略会失去判断依据。容错策略和业务异常的设计必须放到一起考虑不能各写各的。这个教训也是我这套封装里最值钱的一条。5.3 真机调试如何在鸿蒙设备上验证容错行为没有一台能随时制造故障的测试环境容错代码就算写对了你也不敢上线。我的做法是在调试环境里用一个本地 mock 服务通过代码开关动态注入故障。注入随机延迟模拟慢接口注入随机的 SocketException模拟弱网断连后端开关控制返回 500 或 429模拟服务端故障周期性断开连接模拟网络切换。然后在真机上用鸿蒙的日志工具抓取 Flutter 侧运行日志配合策略事件总线里的事件就能把一次完整的容错过程还原出来。下面是我常用的排查速查表。现象优先级检查点常见原因熔断不触发Handle 异常类型是否匹配异常被包装成了自定义类型超时后任务仍占用资源onTimeout 是否取消底层任务平台通道调用还在运行重试次数异常多退避时间是否正确没有指数退避或抖动鸿蒙构建报符号找不到hvigor、NDK、CMake 版本构建工具链不匹配日志里全是 unhandled errorFuture 是否被 catchError 处理未处理的 Future 异常这套故障注入方案是我认为整个项目里性价比最高的一步。与其靠线上故障积累经验不如在开发阶段把故障注入做实让容错代码在真机环境下反复接受考验。6. 个人体会与后续扩展方向做这个项目我最大的一个体会是polly_dart 鸿蒙化的难点九成不在代码而在你是否真的理解容错。只把重试、熔断、超时随便拼在一起系统大概率不会崩溃但也绝不会变稳。真正有价值的是把它当成一套架构来设计策略怎么组合、异常怎么分类、日志怎么埋、恢复怎么验证每一步都值得想清楚再动手。我也想提醒准备做鸿蒙 Flutter 工程化的朋友要多给自己留一点“验证时间”。鸿蒙生态的适配进度和 Android、iOS 不完全同步很多三方库的兼容性需要实打实地在真机上跑一遍。给容错组件做一套故障注入测试比任何代码评审都更能发现问题。最后分享一个后续可以扩展的方向把策略配置从硬编码改成远程下发。后端发现某个服务不稳定时可以直接下发临时的熔断阈值或超时时间不用发布新版本。等这套机制跑顺了你的 Flutter 鸿蒙应用就不仅仅是“能运行”而是真正能在弱网、高并发、后端故障的夹缝里稳定地把业务做下去。
