Flutter鸿蒙适配实战：aws_sns_api与Push Kit推送链路详解

做鸿蒙适配最磨人的不是把自己写的代码跑起来而是把团队依赖的三方库一个个排雷。前段时间我们有个 Flutter 项目要从 Android 迁移到 HarmonyOS NEXT功能模块里最让我头疼的就是 aws_sns_api 这个库——它负责云端推送的调用牵涉到用户通知资产和消息分发链路。这篇博文不打算讲虚的直接把我适配 aws_sns_api 的过程、踩过的坑、以及最终让推送在鸿蒙设备上真正落地的方案完整记录下来。如果你们团队正在做 Flutter 鸿蒙化或者正准备用 AWS SNS 做面向鸿蒙设备的定向推送这篇适配指南能帮你少走很多弯路。先说结论aws_sns_api 是纯 Dart 实现的 SNS API 客户端不依赖 Android/iOS 原生 SDK所以鸿蒙化适配的难点不在于插件桥接而在于网络权限、签名参数、依赖兼容和推送通道接力。把这四件事处理好这个库在鸿蒙端基本就能稳定工作。1. 先搞清楚 aws_sns_api 是什么再谈鸿蒙化1.1 它是纯 Dart 的 API 封装不是原生 SDK 插件很多人一听到 AWS 相关 Flutter 库第一反应是会不会有 Android 和 iOS 的原生代码要翻译成鸿蒙 ArkTS。aws_sns_api 不是这种结构。它是 AWS Dart 社区维护的一组 API 客户端中的一个底层全部用 Dart 实现网络层走http包请求签名走aws_signature_v4包调用 AWS SNS 的标准 REST API。这意味着什么意味着它在鸿蒙平台上没有 JNI、没有 MethodChannel、没有原生视图Dart 代码本身在鸿蒙的 Flutter 引擎里是能直接运行的。最核心的兼容性问题发生在两个层面依赖链上的 Dart 包是否都能在鸿蒙 Flutter 引擎里正常初始化dart:io 的网络栈在鸿蒙系统上是否允许正常发起 HTTPS 请求。这两个层面只要有一个出问题库就用不起来。我在实际适配中验证过aws_sns_api 的主干依赖aws_common、aws_signature_v4、http、crypto、intl、retry在鸿蒙 Flutter 分支上都能正常编译运行没有遇到需要 fork 改源码的情况。这对三方库适配来说已经算是很幸运的结构了。1.2 为什么能编译不等于能推送纯 Dart 库最大的坑在于编译通过只是第一步运行时的系统差异才是真正的拦路虎。鸿蒙 NEXT 对网络权限、后台运行、通知权限的管理逻辑和 Android 有明显差异。aws_sns_api 就算在鸿蒙上把所有 API 调用都跑通了也只是打通了云端控制面——你能够创建 Topic、注册设备 Endpoint、发布消息了。但消息最终能不能变成用户手机上的通知弹窗还得看鸿蒙的推送服务怎么接。这就是标题里说的通知资产和精密分发的两个维度通知资产设备注册关系、Topic 订阅关系、EndpointArn 这些资源的管理与维护精密分发按设备定向发、按 Topic 广播、按 FilterPolicy 精准路由。aws_sns_api 负责管理资产和触发分发鸿蒙 Push Kit 负责把消息送到用户眼前。二者缺一不可这也是整个适配工作里最容易理解错的地方。1.3 适配路线其实有两条别一上来就埋头改代码我在方案预研阶段列过两条路线这里直接分享给各位参考。路线 A保留 aws_sns_api 作为云端调度入口把消息下发到鸿蒙设备的工作交给 Push Kit 接力。SNS 仍然负责任何 Topic 管理、订阅管理、消息发布但在鸿蒙设备上不直接走 SNS 的 APNs/FCM 通道而是通过 HTTP/S 订阅或中间件把消息转到 Push Kit。这是我们最终采用的方式改动最小逻辑最清晰。路线 B完全不碰 aws_sns_api直接在鸿蒙端用华为 Push Kit 的 REST API 自己封装一套推送服务。这种方式适合推送场景非常单一、完全不需要 AWS 体系的团队。但如果你的业务已经围绕 SNS 建好了 Topic 体系、订阅关系、消息筛选规则推倒重来的成本远大于适配一个 Dart 库。多数团队应该走路线 A。你只需要把 aws_sns_api 在鸿蒙上跑通剩下的事情就是设计推送链路。2. 鸿蒙化适配前的工程体检清单2.1 鸿蒙 Flutter 工具链的搭建要求在动 aws_sns_api 之前先把 Flutter 鸿蒙化的环境搞定。当前的主流做法是使用 OpenHarmony 社区的 flutter_flutter 和 flutter_engine 的 ohos 适配分支配合 DevEco Studio 构建 HAP 产物。环境搭建这部分不展开细说只给三个关键建议Flutter SDK 使用 ohos 分支不要用官方原生分支直接编鸿蒙架构不匹配DevEco Studio 安装时把 SDK 和工具链路径记录好后续 Flutter 用到的是同一个 SDK第一次跑flutter build hap之前确认你的 Gradle、Node 环境变量没有和 Android 构建互相污染。我踩过最疼的坑就是环境变量原本机器上配了 Android 的 ANDROID_HOME鸿蒙构建时 Gradle 把 Android 的插件也加载进来了导致整个构建失败。最后把 ohos 分支的构建命令独立封装成一个脚本环境变量只在脚本内生效问题才解决。2.2 给 Flutter 工程补上鸿蒙权限声明aws_sns_api 的所有操作都走 HTTPS 网络请求所以鸿蒙侧的 INTERNET 权限是必须的。在鸿蒙工程的module.json5里配置requestPermissions{ module: { name: entry, requestPermissions: [ { name: ohos.permission.INTERNET } ] } }如果漏掉这个权限表现很隐蔽编译能过但运行时所有 SNS 请求都会超时或直接被网络策略拦截。由于 aws_sns_api 的请求本质上就是一个普通的 HTTPS POST你甚至很难第一时间想到是权限没开。我建议在适配的第一天就把权限清单加到工程的统一配置里别等到联调时才排查。2.3 aws_sns_api 依赖链逐项体检在正式集成前我建议把 aws_sns_api 的完整依赖树打印出来逐项确认鸿蒙兼容性flutter pub deps --styletree重点关注这几个包http底层走 dart:io在鸿蒙 Flutter 引擎上可用网络栈表现正常aws_signature_v4纯 Dart 实现对时钟依赖较强注意设备时间同步问题crypto纯 Dart 实现Hash/HMAC 计算正常intl用于时间格式化纯 Dart兼容性没有问题retrySNS 客户端默认的重试策略纯 Dart无副作用。整个依赖链里没有要求dart:ffi或者调用系统 API 的包所以在鸿蒙上编译没有任何障碍。但这里我要提一个容易忽略的点如果你的项目里同时还引入了其他不会在鸿蒙上工作的插件那 aws_sns_api 就算没问题整体编译依然会挂。我做适配时的策略是先在最小工程里单独集成 aws_sns_api跑通之后再逐步加回其他业务插件。这样可以精确定位问题归属。3. 核心实施把 SNS 调用跑到鸿蒙真机上3.1 凭证方案别把 SecretAccessKey 写死在 Flutter 里任何 AWS SDK 客户端遇到的第一件事都是凭证。aws_sns_api 的构造函数需要AwsCredentials对象包含 accessKeyId、secretAccessKey以及可选的 sessionToken。直接使用长期密钥在客户端应用里是大忌尤其鸿蒙应用是直接分发到用户设备的逆向拿到密钥的成本非常低。我们的做法是自建一个临时的 Token 签发服务应用启动后请求后端接口后端用 STS AssumeRole 换取临时凭证返回给 Flutter 层临时凭证有效期控制在 15 分钟到 1 小时过期后需要重新获取。当然你也可以用 AWS Cognito Identity Pool 的凭证如果你原本就在 Cognito 体系内那会更顺。拿到临时凭证后初始化 SNS 客户端的代码大致如下final credentials AwsCredentials( accessKey, secretKey, sessionToken: sessionToken, ); final sns SNS( region: cn-north-1, credentials: credentials, retryConfiguration: RetryConfiguration(maxAttempts: 3), );注意 region 一定要与你后端的资源区域保持一致。常见错误是 Flutter 里配了us-east-1后端实际在cn-north-1结果操作资源的权限全被拒绝。3.2 SigV4 签名在鸿蒙上的隐形杀手设备时间aws_sns_api 的每个请求都会做 AWS Signature V4 签名签名过程包含x-amz-date请求时间和用于签名计算的 timestamp。AWS 服务端校验签名时会对比请求时间与服务器时间的偏差超过 15 分钟直接返回SignatureDoesNotMatch或者RequestExpired。鸿蒙设备如果用户关闭了自动同步时间或者设备长时间离线时间偏差很容易超过限制。我们的排查经历很典型模拟器上跑得好好的上了真机就开始报签名错误。查了半天才发现那台测试机因为长期用飞行模式系统时间停留在三天前。解决方案分两层在 Flutter 侧启动 SNS 实例前做一次时间校准检查偏差过大时提示用户开启网络时间同步调用接口后若收到 403 且 message 里包含时间相关字样第一时间排除设备时间因素。签名库本身没有问题aws_signature_v4 在鸿蒙上的计算结果和其他平台完全一致问题几乎都出在运行环境。3.3 走通核心链路设备注册、Topic 订阅、消息发布跑通 SNS 的核心链路我们按顺序验证了三个能力。首先是设备注册。鸿蒙设备拿到自身的推送 token 后token 从 Push Kit 获取调用createPlatformEndpoint把这个设备注册成 SNS 的 Endpoint 资产final endpoint await sns.createPlatformEndpoint( platformApplicationArn: platformArn, token: pushToken, customUserData: deviceIdxxxuserIdyyy, );这个customUserData特别有用。它可以存储业务侧的设备标识、用户标识后续做精准分发时你可以直接读 Endpoint 属性把用户和设备对上号。我们就把用户 ID 和 App 版本号都放了进去排查推送问题时非常省事。然后是订阅 Topic。设备 Endpoint 创建好之后要把它关联到对应的业务 Topic 上这样后续只需要向 Topic 发消息SNS 就会自动分发给所有已订阅的设备await sns.subscribe( topicArn: topicArn, protocol: application, endpoint: endpointArn, );最后是发布消息。发布时要注意 SNS 的消息结构。如果只是给移动端点下发通知可以直接传一条字符串消息final response await sns.publish( topicArn: topicArn, message: {default:default message,APNS:{\\aps\\:{\\alert\\:\\hello\\}},GCM:{\\notification\\:{\\title\\:\\hello\\}} }, );但你如果走的是后续我要讲的 SNS 接力 Push Kit 方案这一步的 message 结构就要按实际链路设计不能想当然地填一个 Alert 就完事。3.4 一个容易被忽略的细节Endpoint 更新与失效清理SNS 的 Endpoint 资源不是永久的。当 App 重新安装、Push token 轮换、或者 Push Kit 侧的 token 失效时旧的 EndpointArn 就会变成死资产。我们线上曾经出现过大量无效 Endpoint导致 SNS 发布消息时大量失败回执堆积。应对办法是建立 Endpoint 的健康巡检机制每次 App 启动时用当前 token 调一次getEndpointAttributes对比Token属性是否和本地一致不一致就用setEndpointAttributes更新 token如果返回的 Endpoint 状态是 disabled就删掉重建。这个运维层面的细节直接影响通知资产的健康度。就算 aws_sns_api 跑通了如果资产管理做得烂推送到达率照样难看。4. 从 API 通到推送落地鸿蒙设备怎么真正收到通知4.1 HarmonyOS NEXT 的推送通道现实如果这是 Android 或 iOSSNS 直接配置 FCM/APNs 凭证消息从 SNS 走到系统推送通道就结束了。但 HarmonyOS NEXT 不兼容 Android APK设备上也拿不到 GMSFCM 这条路在纯血鸿蒙上走不通。APNs 更不用想那是苹果生态的专属通道。所以必须面对现实SNS 本身无法直接把通知弹到鸿蒙手机上它只能把消息投递给订阅端点。要让鸿蒙用户收到通知必须借助华为 Push Kit 能力把消息送达鸿蒙系统级通知中心。4.2 接力方案一SNS 订阅 HTTP/S 端点鸿蒙侧回调触发 Push Kit这是我们在生产环境采用的方案。思路是在鸿蒙 App 里放置一个轻量的本地服务向 SNS 的 Topic 发起 HTTP/S 订阅SNS 发布消息时会向这个订阅端点发送一个 HTTP POST 请求鸿蒙侧收到请求后调用 Push Kit 的本地通知接口把消息内容转成系统通知弹给用户。这个方案的优点是不引入额外的中间件不需要部署 Lambda / SQS整条链路完全由 SNS 鸿蒙 App 自己闭环。缺点是依赖 App 进程存活如果 App 被杀本地服务收不到 SNS 的回调消息就会丢。适合对到达率实时性要求不那么极端的业务。要注意的是SNS 向 HTTP/S 端点投递消息时会验证订阅请求SubscriptionConfirmation你需要先回复订阅确认才能开始接收消息。aws_sns_api 本身也提供confirmSubscription接口鸿蒙端在收到初次订阅的确认 URL 后调用这个接口完成握手。这个细节非常容易漏漏了之后你会在 SNS 控制台看到订阅状态一直是 Pending Confirmation。4.3 接力方案二SNS - 轻量后端 - Push Kit REST API对到达率要求高的业务我们把链路设计成SNS Topic 订阅到一个后端服务公共云服务、短信服务、中间层 API 等后端收到 SNS 的 HTTP/S 消息推送后解析业务字段再调用华为 Push Kit 的 REST API把消息通过系统级推送通道下发给鸿蒙设备。App 发布消息 - SNS - 后端订阅端点 - 华为 Push Kit REST API - 鸿蒙设备通知栏这套方案的好处是App 被杀掉也能收到推送因为消息链路不经过 Flutter 进程。代价是后端要接入 Push Kit 的服务端 API并且维护设备 token 与用户关系映射。如果你的 App 同时还有 Android 端可以在后端统一做通道分发Android 走 FCM鸿蒙 NEXT 走 Push Kit普通 Android ROM 走厂商通道各自为政。后面接 Push Kit 时后端需要把 SNS 消息里的业务 ID、标题、内容字段解析出来重新组装成 Push Kit 的 Message 结构。这个解析规则最好和 Flutter 端约定一个统一的 JSON 消息规范避免两边各写一套。4.4 精密分发FilterPolicy 和消息定向的实战玩法SNS 的 FilterPolicy 是精密分发的一个重要工具。同一个 Topic 可以订阅多个不同类型的端点然后给每个订阅设置 FilterPolicy让 SNS 按消息属性自动判断是否投递。举个例子。一个订单状态Topic里面有用户设备端点和管理员监控端点。发布消息时带上orderStatus属性管理员端点通过 FilterPolicy 只接收statuscancelled或statusrefunded的消息用户端点则接收所有与自己订单相关的消息await sns.publish( topicArn: topicArn, message: jsonEncode({orderId: 12345, status: cancelled}), messageAttributes: { orderStatus: MessageAttribute( dataType: String, stringValue: cancelled, ), }, );这种属性级路由的好处是你不需要为每个业务场景单独创建 Topic控制面清爽很多。鸿蒙适配过程中这部分属于业务逻辑层和系统能力关系不大但它是真正体现精密分发价值的地方。建议在做适配时就把 FilterPolicy 的测试用例设计好别等上线后才发现某个订阅该收的没收、不该收的收到了。5. 高频问题与排查技巧实录5.1 编译期Gradle、工具链和依赖冲突鸿蒙 Flutter 工程最常见的编译问题集中在两个地方构建工具链版本不匹配ohos 分支的 Flutter 对 OpenHarmony SDK 版本有隐性要求DevEco Studio 自动安装的 SDK 如果版本过新可能在构建中报 please check your toolchain 之类含糊错误。建议直接用社区分支文档里锁定的版本组合依赖包解析冲突部分 Flutter 插件的原生实现会通过 Gradle 拉取 Android SDK 相关依赖这些依赖在鸿蒙构建时经常冲突出错。解决思路是把纯 Dart 依赖和原生插件依赖拆开管理必要时在鸿蒙构建配置里排除 Android 相关的传递依赖。我自己还遇到过一个问题项目里某插件在 pubspec 中依赖了path_provider而path_provider的 Android 原生代码在鸿蒙环境下加载失败导致整个构建中断。排查了半天最后只把 /ohos 目录下不需要的插件依赖声明移除才解决。如果你的构建日志里出现和 Android 路径相关的报错先怀疑有没有混入非鸿蒙兼容插件。5.2 运行期网络请求、签名错误和超时运行期问题我列一个速查表对应排查思路都在表里现象可能原因排查方法所有请求超时未配置 INTERNET 权限检查 module.json5确认 ohos.permission.INTERNET403 SignatureDoesNotMatch设备系统时间偏差超过 15 分钟手动同步设备时间后重试403 UnrecognizedClientExceptionRegion 配置错误核对 SNS 资源所在地域403 AccessDenied角色策略不足检查 STS 临时凭证关联的 IAM 策略频繁触发重试网络链路不稳定或代理设置异常抓包看请求是否走了意外代理其中时间偏差问题我强烈建议在适配阶段就做好预案。SNS 控制台页面给 AWS 服务端使用的 CET 时间但设备本地时间可能是亚洲时区两边如果都开着自动同步还没事一旦有一台设备时间错掉排查起来非常耗费时间。运行时如果遇到 HTTP 证书校验失败通常是 Flutter 引擎在鸿蒙环境下的 CA 证书加载问题。鸿蒙系统的信任根证书存储和 Android 不完全一致如果你们内部做了私有 CA 或者抓包工具代理了 HTTPS 流量就会出现这类问题。生产环境用正规 CA 签名的证书基本不会踩这个坑。5.3 推送链路的联调技巧从 SNS 到鸿蒙通知栏的验收清单推送链路联调比普通接口联调复杂因为中间隔了多个系统。分享一份我自用的验收清单在 Flutter 端发布一条 SNS 消息能否在 AWS 控制台对应 Topic 的消息计数里看到投递数增加查看 SNS 控制台的订阅端点状态确认订阅未被删除或标记为 disabled如果是 HTTP/S 接力方案在后端日志中确认收到了 SNS 的 POST 请求并且响应码为 200确认鸿蒙 Push Kit 服务端 API 调用成功后返回的 messageId 是否合法在鸿蒙设备的设置-通知中心查看 App 的通知权限是否开启如果权限关闭Push Kit 收得到消息但用户看不到弹窗杀进程后再发一条测试消息验证系统级推送通道是否正常通过getEndpointAttributes检查设备 token 是否与 Push Kit 最新 token 一致。这七步全过推送链路基本稳了。我还想特别提一下通知权限的坑。HarmonyOS NEXT 对通知权限管控很严格App 第一次弹出通知时会向用户申请权限。如果用户拒绝了之后即使 Push Kit 消息到达设备系统通知栏也不会展示。工程侧在适配时要把权限申请的逻辑放到合适的触发时机别在冷启动阶段强制弹窗不然用户很容易反感地关掉。5.4 一个值得提前设计的扩展点本地通知兜底在鸿蒙上做推送适配我个人体会最深的一点是一定要有本地通知兜底机制。如果 SNS 推送达不到网络问题、后端故障、Push Kit 通道限流App 至少需要能在用户打开应用时通过本地逻辑拉取未读消息并补通知。这个能力不用走 Push Kit只是把存储在端侧的数据处理成系统通知。aws_sns_api 的鸿蒙化适配在 API 层面很容易难的是把API 通了变成推送稳定到达。我们团队在做完 API 适配后又花了大半个月完善通道监测、死 Endpoint 清理、降级策略才敢上生产流量。如果你正在做类似的事情建议把时间预算留足别低估推送链路里看不见的损耗。拿我自己这几年的经验来说做跨平台适配最忌讳的就是只盯着编译器和 API 文档而忽略了运行环境的真实差异。aws_sns_api 这个库已经是纯 Dart 里结构很利落的那类了鸿蒙化过程仍然有这么多细节那些重度依赖原生 SDK 的三方库适配成本只会更高。希望这篇指南能帮你把 aws_sns_api 这关顺利过掉也让你对鸿蒙推送的整个链路有更清晰的判断。后续如果你们打算把更多 Flutter 三方库迁移到鸿蒙记住一个原则先体检、后集成、再联调每一步都拿真机数据说话。