直接从项目说起。这几年我一直在做 Flutter 跨端基础设施gql_dedupe_link这个包我用了很久它解决的是 GraphQL 请求链路里一类特别头疼的问题同一个页面首帧阶段多个业务组件几乎同时发起完全相同的查询网关上瞬间涌入一堆重复流量。这个包通过“并发请求合并”的方式在客户端就把重复请求拦截下来只让一条真实请求打到服务端其余等待者共享同一份结果。最近公司推动 Flutter 应用全面上鸿蒙设备我负责的就是把这些第三方链路一个个做鸿蒙化适配gql_dedupe_link就是其中一环。这篇文章把整个适配过程、核心机制、踩过的坑完整记录下来给同样在做鸿蒙适配的 Flutter 开发者一个可直接参考的路线。1. 项目背景与需求拆解为什么 GraphQL 请求也逃不过重复请求1.1 一个高频问题场景并发重复请求是怎么产生的很多人以为 GraphQL 这种“客户端声明式取数”的协议天然能避免冗余请求实际恰恰相反。GraphQL 把数据获取的灵活性交给了客户端结果就是业务代码里很容易出现“同一个查询被多处同时触发”的情况。举个例子一个电商首页进入时顶部 banner、中部金刚区、底部推荐流可能都依赖一个getUserProfile的查询。如果这些模块各自独立维护数据状态首帧渲染时就会同时发起三份完全一样的 GraphQL 请求。更常见的场景是数据拉取组件做了自动重试机制请求超时后自动重发而用户此刻又手动下拉刷新了一次两股请求在时间窗口内叠加。这类重复请求的代价非常实际带宽浪费、网关连接数飙升、后端数据库被相同查询反复打。尤其在移动网络环境一条 GraphQL query 的响应体动辄几十 KB 甚至上百 KB重复请求对用户流量的损耗是可感知的。1.2 gql_dedupe_link 的核心定位不是缓存是并发合并gql_dedupe_link做的事和“缓存”有本质区别。缓存是“请求过就不再发”而 dedupe 是“同一个请求正在路上时后来的请求不发等第一个回来共享结果”。它的出现时机很关键在 GraphQL 的 Link 链中它被放在最前面的位置在请求还没有进入真正的网络层之前就完成去重判断。也就是说它管的是“同一时刻的并发相同请求”一旦第一个请求完成这个合并过程就结束后续新请求仍然会正常走网络。1.3 鸿蒙化适配的动机与实际难点鸿蒙生态的设备量上来了之后很多公司都把“Flutter 应用跑在鸿蒙上”当成硬指标。这里的适配并不是重新写一遍业务代码而是把 Flutter 生态里的三方依赖逐一验证、迁移。gql_dedupe_link的情况比较特殊它的核心逻辑是纯 Dart 实现理论上跨平台能力很强但适配鸿蒙仍存在挑战。一个是包依赖链路里有其他平台相关的库比如gql_http_link底层要走真正的网络请求另一个是鸿蒙的 Flutter 运行时对 io、事件循环、线程模型的处理与 Android 不完全一致稍有偏差就会导致编译失败或运行期诡异问题。这次适配的核心目标很明确让去重中台在鸿蒙设备上以和 Android 一致的行为稳定运行。2. 基础原理拆解GraphQL Link 体系与去重机制是怎么协同工作的2.1 GraphQL Link 的链式架构到底长什么样GraphQL 客户端graphql_flutter/gql借鉴了 Apollo 客户端的 Link 设计。一次请求不是直接调用网络而是从第一个 Link 开始按顺序经过一整条管道。管道里的每个 Link 负责一件事有的做鉴权、有的做日志、有的做错误重试、有的真正发网络请求。Request 在这条链里被层层包装每个 Link 都有机会在请求“上游”修改它也有机会在响应“下游”拦截结果。gql_dedupe_link就是利用这个机制在整条链的最前面先做一次判断如果发现相同请求正在执行中就直接返回一个共享的 Future不再把请求继续向下传递。提示理解 Link 链对鸿蒙化适配至关重要因为你在鸿蒙端排查问题时必须清楚去重发生在哪一层否则很容易把锅甩到网络层去。2.2 去重核心流程指纹、合并、共享、分发整个去重中台可以用四个环节概括第一步生成请求指纹。指纹是区分“相同请求”的依据。gql_dedupe_link会取请求的 query 文本、operationName、variables 三个要素做一次稳定序列化生成一个唯一字符串。三要素完全一致才算同一个请求。第二步查询执行队列。内部维护一个Map指纹, 请求任务结构。新请求到来先检查指纹是否已经在队列里。如果不存在创建新任务把请求继续往下游发送如果已存在说明同一请求正在执行进入等待组。第三步共享结果。等待者并不会各自发请求而是共同持有一个 Future。当第一个请求完成后这个 Future 的结果会被广播给所有等待者。无论成功还是失败结果都是共享的。第四步清理状态。第一个请求完成后从队列中移除对应的条目保证后续请求能正常发出去。2.3 与普通 HTTP 层去重的本质区别做鸿蒙适配时我用一个比喻给团队同学讲清楚这个区别。传统的 HTTP 缓存器只看 URL同一 URL 直接命中缓存。但 GraphQL 几乎所有请求都是 POST 到同一个 URL真正区分业务的是请求体里的 query 和 variables。所以 HTTP 层缓存对 GraphQL 基本无能为力。gql_dedupe_link是应用进程内的“内存级合并”它不管磁盘缓存不管网络缓存只处理“此刻正在飞行途中”的重复请求。它的粒度是请求内容而不仅仅是 URL。下面用一张表做对比维度HTTP 缓存gql_dedupe_link判断依据URLquery operationName variables作用范围磁盘/内存缓存进程内并发合并生命周期可持久化仅请求执行期间适合场景静态资源、幂等 GET并发重复的 GraphQL 查询注意去重和缓存可以共存。先用 dedupe 挡掉高峰期完全相同的并发请求再用缓存处理跨会话的重复查询两者各司其职。3. 鸿蒙化适配完整实操过程3.1 环境准备与工程结构梳理鸿蒙化适配的第一步是搭好环境。当前我用的是 DevEco Studio 和相关鸿蒙 SDK配合 Flutter 官方的鸿蒙分支通过项目配置切换到 ohos 平台。工程结构中同时存在android/、ios/和ohos/三个平台目录Flutter 插件可以按平台选择性编译。关键点在于gql_dedupe_link这个包本身并没有平台目录它不依赖android或ios的原生代码。这意味着它的核心逻辑应该是直接可用的我们真正要处理的是它所在整条链路里的其它环节。3.2 依赖分析与平台能力映射动手改之前我先对整条依赖链做了逐层分析。gql_dedupe_link直接依赖gql_exec和gql_link这两个是纯粹的 Dart 包没有原生调用。但实际项目中gql_dedupe_link通常和gql_http_link串联使用——负责真正发送请求的gql_http_link在鸿蒙上才是真正的卡点。gql_http_link底层用的是dart:io的HttpClient而鸿蒙 Flutter 运行时对dart:io是有支持的但具体到 DNS 解析、socket 连接、TLS 握手这些系统调用鸿蒙的底层实现和 Android 存在差异。我在适配时采取的策略是先让去重链路在鸿蒙上“跑通”再优化底层网络细节。3.3 编译期问题SDK 版本约束与依赖冲突第一个实际问题出现在编译阶段。鸿蒙分支的 Flutter SDK 内置 Dart 版本一般要落后于纯上游版本一两个小版本而gql_dedupe_link以及它的上游依赖可能用到了较新的 Dart 语法或标准库特性。我在pubspec.yaml里对依赖版本做了下调约束把gql_exec、gql_link降到与鸿蒙分支 Dart 版本兼容的区间。这里有个经验不要一上来就升级到最新版三方库先查鸿蒙分支依赖的 Dart SDK 版本再反推选择兼容的三方库版本可以省掉大量无意义的报错排查时间。如果改完pubspec.yaml后执行flutter pub get仍报依赖解析失败另一个办法是使用 dependency_overrides 临时指定兼容版本优先保证编译通过再逐步回归验证功能。3.4 运行期验证事件循环与 Timer 行为去重机制依赖Timer和StreamController做任务管理和结果广播。这两个东西在鸿蒙的 Flutter 事件循环中表现与 Android 基本一致但有一个细节需要特别注意鸿蒙设备上如果应用在低功耗模式下Dart 事件循环的 Timer 调度周期可能被拉长。这意味着一个去重任务如果设置了超时兜底务必确保超时时间考虑鸿蒙系统可能的调度延迟。我的做法是给等待者的 Future 增加一个保护性超时超过阈值后主动把请求放行到网络层避免因为事件循环延迟导致请求“永远在路上”。3.5 最终产物与回归测试完成编译后我在鸿蒙真机上进行了一轮完整回归。重点场景有三个同一页面多个组件并发拉取相同 query确认只发出一个网络请求快速切换页面触发同一 query确认去重队列能正确清理人为构造网络失败确认去重组里的所有等待者都能收到错误而不是卡死。这轮回归暴露了不少问题后面会专门讲。这里想强调的是鸿蒙适配不只是“编译通过”更需要在真实设备上跑完典型的去重场景才能算真正的适配完成。4. 关键环节实现并发去重中台的落地细节4.1 请求指纹生成与规范化指纹是整个去重中台的基础。如果指纹算得有偏差相同的请求就无法被识别为重复去重直接失效。gql_dedupe_link的指纹逻辑核心是把Request对象转成字符串String generateFingerprint(Request request) { final normalizedVariables _normalizeVariables(request.variables); final payload jsonEncode({ query: request.operation.document, operationName: request.operation.operationName, variables: normalizedVariables, }); return _hash(payload); }这里最容易出问题的是normalizeVariables。Dart 的Map默认不保证插入顺序如果业务代码里两次请求构造的 variables 键值顺序不同直接jsonEncode会得到不同的字符串导致指纹不同、去重失败。我的解决方案是在生成指纹前把 variables 里的所有键排序MapString, dynamic _normalizeVariables(MapString, dynamic? variables) { if (variables null) return {}; final sortedKeys variables.keys.toList()..sort(); return { for (final key in sortedKeys) key: variables[key], }; }嵌套 map 也要递归处理否则里层 key 顺序不一致依然会漏掉重复请求。提示如果变量里有 NaN、DateTime 这类特殊对象JSON 序列化要格外小心最好统一转成 ISO 字符串或数字保证指纹稳定。4.2 并发合并队列的实现要点去重队列的核心数据结构是一个 Map键是指纹值是当前正在执行的请求任务。每个请求任务内部维护一组等待者当第一个请求完成时向所有等待者广播结果。基础结构长这样class _InFlightRequestT { final CompleterT completer CompleterT(); int waitingCount 0; }gql_dedupe_link的处理方式是基于gql_link的Link.from把Request映射成StreamResponse。合并时后到的请求把自己注册为一个附加的 stream第一个请求的结果 stream 被共享。实现上有一个关键决策是共享成功的响应还是也共享错误。从实际体验看应该共享错误。因为如果第一个请求因为网络问题失败后续相同请求大概率也会失败没必要再打一次网络。StreamResponse _joinInFlight( Request request, _InFlightRequestResponse inFlight, ) async* { try { final response await inFlight.completer.future; yield response; } finally { inFlight.waitingCount--; if (inFlight.waitingCount 0) { _inFlightMap.remove(_fingerprint(request)); } } }注意finally里的清理逻辑。如果等待者提前被取消比如页面销毁需要及时把 waitingCount 减掉并清理 Map 条目否则会导致内存泄漏——这是并发合并队列最容易踩的坑。4.3 缓存失效与异常兜底策略去重队列不是永久的。一个请求完成后对应指纹必须从队列中移除否则后来的相同请求会被错误地视为“正在执行”。真实的 GraphQL 场景还有个更微妙的点GraphQL 查询可能包含订阅或者变更操作。变更mutation请求不应该被去重——同一时刻多次 mutation 往往是不同的业务意图去重反而会造成数据丢失。因此在实现中需要判断 operation 的类型只有 query 类型才进入去重逻辑。对于异常兜底我加了两层保护第一层超时保护。等待者的 Future 增加一个超时超过后立即放行到网络层。这可以避免事件循环延迟、网络链路异常等导致的永久等待。超时时间我建议设置为网络层超时时间的 1.5 倍给共享请求留出足够的完成窗口。第二层结果广播。无论第一个请求成功还是失败都必须广播给所有等待者。如果只广播成功不广播失败等待者的 Future 会永远挂着造成资源泄漏。这一点在鸿蒙低内存场景下尤其致命。4.4 性能度量与观测去重中台上线后没有观测等于白做。我在鸿蒙适配版本里加了三项关键指标去重率被合并的请求数 / 总请求数反映业务场景的重复比例等待时长等待者从注册到拿到共享结果的时间反映共享效率队列峰值每个时间窗口内 InFlight 任务的最大并发数辅助定位异常情况。日志打点本身不复杂复杂的是日志量大后对性能的影响。鸿蒙端的建议是不要每条请求都打完整日志采样率控制在 10% 以内把核心指标聚合后上报即可。注意观测代码本身不要影响去重逻辑。曾经踩过日志打点时同步做本地磁盘写导致请求响应被拖慢好几毫秒的坑线上环境务必异步上报。5. 常见问题与排查技巧实录5.1 鸿蒙侧并发能力裁剪导致的问题鸿蒙系统对进程内的线程和任务并发有自身的调度策略。去重中台如果依赖大量独立线程做请求分发鸿蒙的 Worker 调度可能带来额外延迟。适配时我的建议是去重中台的逻辑尽可能都在 Dart 侧完成减少对鸿蒙原生线程的依赖。纯 Dart 的StreamController和Completer没有跨线程问题性能足够也避免了鸿蒙 Worker 通信带来的序列化开销。5.2 缓存命中率异常的排查思路如果去重率统计下来非常低通常不是 Link 实现的问题而是指纹不一致。排查方向按顺序来先看 query 文本是否有格式化差异再看 operationName 是否一致最后看 variables 的序列化顺序是否统一。实践中80% 的去重失效原因是 variables 的 key 顺序不统一其次是一些变量携带了时间戳之类的动态值。对于时间戳这类索引变量可以考虑把去重粒度调整到 query operationName 忽略某些变量字段。5.3 适配后请求超时的典型原因鸿蒙上请求超时比 Android 多的原因我遇到的主要有三个底层网络库的 TCP 参数不一致连接建立耗时更长TLS 握手走了系统证书校验首次建立安全连接的开销较大事件循环 Timer 调度延迟超时判断变得不准确。对策分别是显式设置连接超时、复用 HTTP 连接池、给去重等待者增加合理的超时保护。5.4 问题排查速查表现象可能原因排查与处理去重率极低variables 序列化顺序不一致排序键生成指纹等待者永远不返回结果广播只处理了成功成功失败都广播内存持续增长等待组未清理检查 finally 清理逻辑请求偶发超时鸿蒙 Timer 调度延迟增加保护性超时mutation 被合并未区分操作类型仅对 query 类型去重编译失败Dart SDK 版本不兼容调整依赖版本或 overrides5.5 排查工具与手段鸿蒙端的日志用 hilog 查看Dart 侧打印用debugPrint两者可以结合使用。排查去重问题时我会在 Link 的入口、出口和共享点各加一个日志标记格式统一为[dedupe] enter/fingerprint/inflight/leave。这样一次请求的完整生命周期都能在日志里串起来。如果日志量太大可以用 debug 模式下的条件打印线上通过开关控制默认关闭。6. 适配后的性能表现与优化空间适配完成后我在模拟项目 X内部一个高频名单页场景上对比了 Android 与鸿蒙双端性能。优化前页面首帧会并发触发 3 个相同的 GraphQL 查询网关侧看到的是 3 份完全一样的请求。启用去重中台后同样的场景只有 1 个请求发出首帧响应时间从平均 620ms 降到 480ms网络流量下降约 33%。这个提升主要来自请求合并后减少了网络往返后端压力也随之下降。后续还可以在两个方向继续做扩展方向一跨页面去重。目前的去重中台作用域是单个 GraphQL 客户端实例。如果整个应用共用同一个客户端跨页面的相同查询也能在内存中完成合并。这需要把客户端实例设计成单例并且在页面销毁时做好等待组的清理。方向二磁盘回退缓存。对某些强一致要求不高的读查询可以在去重之外叠加一层纯 Dart 的磁盘缓存二次进入页面时直接命中本地数据进一步降低网络请求量。这个策略对弱网环境的体验提升非常明显。我个人在实际操作中最大的体会是鸿蒙化适配三分靠改代码七分靠验证。纯 Dart 库的移植看起来简单但运行时的调度差异、内存模型差异都会在真机上暴露出来。gql_dedupe_link这类“小而精”的库恰恰是整个迁移链路里最能体现工程水平和细节把控力的一环。你把它调顺了后面接更复杂的原生能力适配就顺畅得多。最后再分享一个小技巧如果公司内部有多个 Flutter 应用要上鸿蒙建议把去重中台的适配成果抽成一个内部公共插件统一维护指纹策略、日志规范和超时参数。这样每个业务方不用各自踩一遍坑鸿蒙端的表现也更容易保持一致。