有段时间我在做 Flutter 项目的代码质量门禁时发现sonar_analysis这个三方库在 iOS 和 Android 上表现一直很稳定但一放到鸿蒙HarmonyOS/OpenHarmony环境里整个通道直接就哑火了。翻了一圈社区资料相关的适配文档基本都停留在“理论可行”的阶段真正能把代码审计、质量指标采集和门禁闭环跑起来的实战案例非常少。这篇文章就是一次完整的鸿蒙适配过程记录我会把sonar_analysis从插件工程改造、ArkTS 通道实现到对接 sonar-scanner 的完整链路讲清楚适合正在做 Flutter 鸿蒙化、或者准备把现有 Flutter 三方库移植到鸿蒙系统的读者参考。我这里说的“全栈质量守卫”不是简单地把代码扫描结果展示出来而是让sonar_analysis在鸿蒙端也能完成三个层面的任务第一采集 Flutter 侧的 Dart/TS 静态扫描结果第二通过原生通道读取鸿蒙工程产物和 HAP 包内的可分析文件第三把分析数据汇聚到 SonarQube 服务端形成统一的代码质量门禁。这套东西跑通之后鸿蒙应用和 Flutter 应用在同一个质量体系下被审查才是真正的“全栈”。1. 为什么要给 sonar_analysis 做鸿蒙适配而不是另起炉灶1.1 sonar_analysis 到底解决了什么问题sonar_analysis不是一个简单的“报错插件”它的定位是 Flutter 侧的代码审计客户端。在 Android 和 iOS 上它通常负责三件事收集 Dart 代码的静态分析指标复杂度、重复率、代码行数、触发本地声纳扫描器sonar-scanner进行分析、然后通过通道把分析结果推给上层应用或后端服务。听起来功能不复杂但它所在的生态位置很特殊。很多中大型 Flutter 项目并不是只有 Flutter 一门语言工程里混杂着原生代码、ArkTS鸿蒙侧、Kotlin/Swift双端原生。如果只用原生 SonarQube 插件分析Flutter 层的 Dart 代码基本处于“裸奔”状态。而sonar_analysis这种插件能充当桥梁让 Flutter 层的质量数据也进入同一个 SonarQube 项目。鸿蒙适配的难点不在于插件复杂度高而在于它的通信链路完全依赖 Flutter 与原生平台之间的通道机制。通道一端是 Dart另一端是平台实现鸿蒙没有 Android 的PluginRegistry也不能直接用 iOS 的FlutterPlugin协议需要重新在 ArkTS 侧实现一套等价的通道逻辑。1.2 所谓“全栈质量守卫”具体指什么“全栈”这个词在质量领域经常被滥用但放在这个场景里是有明确含义的。一个鸿蒙应用从源码到可交付的 HAP 包中间要经历 Dart 层编写、ArkTS 层编写、资源编译、依赖打包等多个阶段。质量守卫需要覆盖到每个阶段产生的可分析产物Dart 源码使用flutter analyze和自定义 linter 规则扫描。ArkTS 源码使用鸿蒙侧的代码检查工具和 SonarQube 的 ArkTS 规则插件。构建产物 HAP解包后检查 so 库、资源文件、配置文件是否存在安全隐患。运行时行为通过日志、性能指标回传发现内存泄漏、异常调用等问题。sonar_analysis在 Android/iOS 上已经跑通了这套流程鸿蒙适配要做的不是重新发明轮子而是把其中依赖平台能力的部分文件访问、进程调用、数据通道迁移到鸿蒙的 ArkTS 环境中。1.3 鸿蒙适配和普通 Android 移植的差异很多人第一个念头是“鸿蒙不是兼容 APK 吗直接把 Android 插件拿过来跑不就行了”这个想法在早期兼容 Android 的版本里有一定道理但在面向鸿蒙原生应用开发时插件必须走 ArkTS 的通道实现和 Android 插件完全是两套东西。具体差异体现在三个地方。第一插件发现机制不同Flutter 引擎在鸿蒙上会寻找ohos目录下的原生插件入口而不是 Android 的android目录第二通道的值编码和平台侧 API 名称有差异MethodChannel在 ArkTS 侧要使用兼容层的MethodChannel实现不能直接照搬 Android 代码第三权限模型不同鸿蒙的沙箱、权限声明方式和 Android 截然不同sonar_analysis要读取 HAP 文件、扫描目录就必须重新申请权限。2. 适配前必须吃透的通道模型与工程骨架2.1 sonar_analysis 依赖的三类通道sonar_analysis不是只用一种通道而是根据业务场景混合使用。理解这一点是适配成功的前提。它通常依赖三类 Flutter 通道一是MethodChannel用于方法调用比如“启动一次扫描”、“获取当前工程路径”、“取消任务”。这类通道是双向的Dart 侧发起调用原生侧返回结果适合一次性的请求-响应模式。二是EventChannel用于持续事件流比如扫描进度、实时日志、文件遍历状态等。这类通道是单向的原生侧主动向 Dart 侧推送事件Dart 侧只负责监听。sonar_analysis中告警信息的分批到达就是通过它实现的。三是BasicMessageChannel用于双向的低层消息通信通常在传递大量自定义数据结构时使用比如扫描结果的 JSON 序列化大对象。这类通道不会在本次适配中重点展开但工程里也会用到。2.2 鸿蒙 Flutter 引擎下的通道兼容层鸿蒙的 Flutter SDK俗称 flax 或 flutter-flutter 的鸿蒙版在设计时保留了和官方 Flutter 一致的通道 API。也就是说Dart 侧代码完全不用为鸿蒙单独写一套真正要适配的是原生侧。ArkTS 侧实现通道的姿势大概是下面这样在鸿蒙工程中创建一个继承自Plugin的类实现对应的方法然后用引擎内部的PluginRegistry注册。和 Android 的MethodCallHandler相比ArkTS 侧多了Result的异步回调方式稍不留神就会写出无法返回结果的空通道代码。我在实际适配中经常遇到一个现象Dart 侧invokeMethod一直等不到回调但插件在应用启动时明明已经被加载了。原因多半是 ArkTS 侧的消息编解码器和 Dart 侧不一致鸿蒙版本的引擎虽然兼容通道但值类型的转换和标准 Flutter 引擎仍有细微差别。2.3 工程骨架在 pubspec.yaml 里为鸿蒙开一扇门sonar_analysis的鸿蒙适配第一步不是写 ArkTS 代码而是先在插件工程里把鸿蒙平台声明出来。Flutter 插件在发布时需要通过pubspec.yaml声明各平台的原生入口。对鸿蒙来说核心就是在插件声明里增加ohos的pluginClass。示例配置大致长这样flutter: plugin: platforms: android: package: com.example.sonar_analysis pluginClass: SonarAnalysisPlugin ios: pluginClass: SonarAnalysisPlugin ohos: pluginClass: SonarAnalysisPlugin dartPluginClass: SonarAnalysisFlutterPlugin这里有两个细节要注意。第一dartPluginClass是可选字段但如果你希望在 Dart 侧统一处理原生通道注册顺序建议配置上这样可以让插件在 Dart 层初始化时自动注册通道避免偶发的时序问题第二ohos平台声明后插件工程根目录下必须存在ohos目录内部要符合鸿蒙模块的标准结构否则 Flutter 工具链在编译时会直接跳过这个平台而且不会报明显的错误表现得像“适配没做一样”。3. ArkTS 侧通道落地从空 channel 到真实审计数据3.1 先搭 MethodChannel把“扫描一次”变成一次方法调用sonar_analysis最核心的方法调用是startAnalysis。在 ArkTS 侧实现时我会在插件类里定义一个方法处理器用MethodChannel接收来自 Flutter 侧的调用。下面是一段简化后的 ArkTS 实现示意import { MethodChannel, MethodCall, Plugin } from ohos/flutter_ohos; export default class SonarAnalysisPlugin implements Plugin { private channel: MethodChannel new MethodChannel(sonar_analysis/methods); onAttachedToEngine(binding: any): void { this.channel.setMethodCallHandler(this.handleMethodCall.bind(this)); } private async handleMethodCall(call: MethodCall, result: any): Promisevoid { switch (call.method) { case startAnalysis: const path: string call.arguments[path] as string; try { const summary await this.runAnalysis(path); result.success(summary); } catch (e) { result.error(ANALYSIS_FAILED, JSON.stringify(e), null); } break; default: result.notImplemented(); } } private async runAnalysis(projectPath: string): Promiseobject { // 调用鸿蒙侧代码检查服务这里根据实际能力扩展 return { files: 1024, warnings: 13, defects: 2 }; } }这段代码虽然简单但能带你跑通第一个链路。关键的几个点MethodChannel的名字必须和 Dart 侧完全一致否则 Dart 会报MissingPluginExceptioncall.arguments在鸿蒙侧可能被解码成Mapstring, Object所以在取值前最好做一个类型守卫result是异步回调如果你在runAnalysis里调用耗时任务千万不要把result.success放到同步代码后面否则一旦任务长时间未返回Dart 侧会超时。3.2 用 EventChannel 把扫描进度和告警推成流代码审计是一个耗时操作用户肯定不希望等所有分析完成才看到结果。sonar_analysis在设计上会把扫描进度、命中的规则、实时日志通过EventChannel分批推送。鸿蒙侧的实现要比 MethodChannel 稍微复杂一点因为你需要实现一个事件流对象。import { EventChannel, EventSink } from ohos/flutter_ohos; export default class AnalysisEventPlugin { private eventChannel: EventChannel new EventChannel(sonar_analysis/events); private sink: EventSink | null null; constructor() { this.eventChannel.setStreamHandler({ onListen: (args: any, events: EventSink) { this.sink events; }, onCancel: (args: any) { this.sink null; } }); } pushProgress(percent: number, message: string): void { if (this.sink) { this.sink.success({ percent: percent, message: message }); } } pushWarning(defect: object): void { if (this.sink) { this.sink.success(defect); } } pushError(error: Error): void { if (this.sink) { this.sink.error(SCAN_ERROR, error.message); } } }这里最容易翻车的点在于EventSink的生命周期。如果 Dart 侧的EventChannel.receiveBroadcastStream没有被激活onListen就不会触发你在 ArkTS 侧拼命推数据是没用的数据全部被引擎丢弃。所以我在适配时会在 Dart 侧做一次“冷启动探测”先让事件流处于监听状态再触发扫描任务保证进度推送不会丢失。3.3 沙箱与权限能让分析器读到 HAP 才算第一步sonar_analysis到鸿蒙之后要做的第一件实际工作是找到 HAP 包的位置并读取出可分析内容。鸿蒙应用的沙箱机制比 Android 更严格普通应用能读到的路径只有自己的沙箱目录和公共媒体目录。我一开始最天真的做法是直接读取应用安装路径下的 HAP结果发现代码审计进程根本没有权限访问安装目录。正确的做法是通过应用上下文获取到 bundle 信息把需要分析的产物复制到沙箱的 cache 目录然后让分析逻辑在沙箱内完成读取。权限部分的 ArkTS 声明也只能落在两处一是module.json5中声明相关权限比如读取存储的权限二是运行时判断权限是否已授权。有一点需要特别提醒如果你只是分析 HAP 内的静态资源有时候并不需要存储权限因为你可以直接通过BundleManager拿到资源的绝对路径但不一定能直接打开文件流还是要靠沙箱中转。3.4 线程模型别让扫描任务堵住 UIArkTS 侧实现代码审计时最危险的做法是直接在方法调用线程里执行文件遍历、zip 解包、规则匹配。这些操作动辄几百毫秒到几秒一旦跑在 UI 线程用户就会明显感到卡顿严重时会被系统判定为应用无响应。我建议的做法是把分析任务放到 WorkScheduler 或者自建的 worker 线程中去执行。下面这个思路在鸿蒙上是可行的先构建一个任务队列把startAnalysis请求封装成任务然后利用异步回调把结果传递回通道。ArkTS 的async/await并不自动切换线程所以如果你在插件方法里写了await this.unzip()它依然可能阻塞调用线程。实测下来最稳的方案是在Ability侧启动一个独立线程来处理扫描或者用鸿蒙提供的任务分发机制。这里不能为了图省事而省略线程设计否则线上环境一旦在高频上报日志时触发通道拥堵整个质量守卫链路都会反噬业务。4. 打通代码审计链路把 sonar_analysis 与 sonar-scanner 接起来4.1 拿到可分析的构建产物sonar_analysis在 Flutter 侧的工作本质上只是“数据采集和质量指标托管”真正完成代码审计的是 sonar-scanner。鸿蒙适配的第二步是把 Flutter 构建产物和鸿蒙构建产物都整理成 sonar-scanner 能识别的目录结构。Flutter 产物通常位于build/app/outputs/flutter-apk或鸿蒙引擎对应的输出目录中鸿蒙的 HAP 产物则位于entry/build/default/outputs/。要让 sonar-scanner 同时分析 Dart 和 ArkTS我需要把两种产物映射到一个临时目录或者直接用多个sonar.sources指定。4.2 sonar-project.properties 关键配置SonarQube 的项目配置是整个质量守卫的“指挥中心”。结合鸿蒙项目的特殊性我整理了一份通常可以跑通的配置模板sonar.projectKeycom.example.harmony_quality sonar.projectNameHarmony Flutter Quality Guard sonar.projectVersion1.0.0 sonar.sourceslib,entry/src/main/ets sonar.exclusions**/*.g.dart,**/generated/** sonar.sourceEncodingUTF-8 sonar.languagemulti sonar.dart.analysisTimeout120 sonar.analysis.modepublish sonar.host.urlhttps://sonar.internal.example.com sonar.login${SONAR_TOKEN}这里几个字段值得展开说一下。sonar.sources必须同时包含 Flutter 的lib目录和鸿蒙的ets目录否则审计范围就会偏科达不到“全栈”的目的sonar.languagemulti是为了让 SonarQube 的多个语言插件同时生效sonar.exclusions一定要排除生成代码Flutter 里最常见的噪音来源是*.g.dart和*.freezed.dart不排除的话重复率指标会被严重稀释。4.3 规则集覆盖Dart、ArkTS 双线审计大多数团队为了快点上线会让 SonarQube 只跑默认规则集这样在鸿蒙项目上的结果其实很有限。因为默认规则集不会覆盖 ArkTS 的专属问题类型比如状态管理滥用、taskpool 误用、分布式对象生命周期问题等。在我的适配方案里sonar_analysis会作为 Dart 侧的扫描触发器执行完成后生成sonar-report.jsonArkTS 侧则通过自定义分析器导出问题列表。最终这些结果都会被sonar-scanner收集起来汇总成可审计的质量数据。两条线的规则集建议分开管理Dart 层规则聚焦可维护性、复杂度、空安全、反模式。ArkTS 层规则聚焦生命周期、并发模型、资源释放、API 合规。4.4 CI/CD 门禁集成质量守卫不能只在本地跑要真正“守卫”工程就得接入 CI 流水线。我这里的落地方式是在 GitLab 流水线里加一个 job先执行 Flutter 侧分析和 ArkTS 侧分析再由 sonar-scanner 把结果上报给 SonarQube最后用 Quality Gate 的返回状态来决定构建是否继续。#!/usr/bin/env bash set -euo pipefail flutter pub get flutter analyze --no-fatal-infos --no-fatal-warnings || true dart run sonar_analysis \ --project-path . \ --output build/sonar/dart-report.json ohpm install --all hvigorw assembleHap --mode module -p productdefault sonar-scanner \ -Dsonar.host.url$SONAR_HOST_URL \ -Dsonar.login$SONAR_TOKEN \ -Dsonar.projectKey$SONAR_PROJECT_KEY \ -Dsonar.sourceslib,entry/src/main/ets \ -Dsonar.dart.reportPathbuild/sonar/dart-report.json需要注意一个细节flutter analyze不能因为发现 warning 就直接终止否则会被 CI 的set -e卡死。做法是先允许分析完成把结果转成报告再交给 sonar-scanner 统一判定。这套流水线跑起来之后每次提交的质量反馈不再是零散的而是一个带告警趋势、文件维度和规则分布的中枢报告。5. 适配过程中最容易翻车的五个场景完整排查链路5.1 插件声明不生效ohos 目录存在但 Flutter 引擎不加载我遇到的第一个坑是pubspec.yaml里明明写了ohos的pluginClassFlutter 项目在鸿蒙引擎上运行也没有报错但 Dart 侧一调用就提示MissingPluginException。这种问题的排查链路是先检查ohos目录是否存在于插件根目录并且是否被正确发布到 pub 缓存中。再检查Index.ets中是否导出了插件入口类。鸿蒙插件的注册依赖Index.ets里把插件实例抛给 Flutter 引擎漏掉这一步引擎根本感知不到。最后检查插件类的onAttachedToEngine是否被调用如果这个生命周期方法没执行多半是注册方式写错了而不是通道实现的问题。5.2 通道收到的数据从 Map 变成 List 乱码sonar_analysis传参和返回值经常使用嵌套的 Map。在 Android 上这套做法很稳但鸿蒙引擎的编解码器对Map的键顺序和嵌套类型处理会有差异。表现为Android 侧好好的数据鸿蒙侧解析出来键名全没了或者Map变成了Array。排查时我先在 Dart 侧打了日志确认传入的Map是正常的然后回归 ArkTS 侧打印call.arguments的类型发现直接被解析成了Array。根源是标准通道编码对Map的 Key 类型要求是字符串而我在 Dart 侧传的时候用了非字符串键Android 的编解码器自动容错了鸿蒙侧没有。解决办法不复杂统一参数结构所有 map 的 key 强制字符串避免使用数字或枚举做键。5.3 权限与沙箱读取不到缓存目录sonar_analysis在鸿蒙上读取cacheDir的时候一度返回空目录但应用明明可以正常写入缓存。最后排查发现Flutter 引擎的 Dart 侧拿到的path_provider缓存路径和鸿蒙原生沙箱路径并不一致直接拼接出的路径根本不存在。破解方法是在数据返回前先通过鸿蒙 API 归一化路径确保 Dart 拿到的路径是沙箱内真实存在且可读的。有时还需要主动在 native 侧创建目录因为某些系统版本下缓存子目录不会自动生成。处理完后最好再回头在 Dart 侧做一个existsSync校验避免后续扫描流程静默失败。5.4 HAP 内的 so 没有被 sonar-scanner 识别代码审计不能只看源码HAP 包里集成的 so 库、二进制资源也是检查对象。我在对接 sonar-scanner 时发现它默认只按源码扩展名识别文件so、hap都没被纳入分析范围。解决方法是在配置中增加二进制分析插件或者先把 HAP 解包到临时目录、把里面的*.so导出成 ELF 分析产物再让 sonar-scanner 扫描这个临时目录。说白了就是让扫描器不要直接面对 HAP 这个压缩包而是面对解包后的真实文件树。这个环节最容易出现“结果假绿”的假象看着质量门禁通过了实际上核心资产根本没有被审计。5.5 回归验证Charles 抓包与日志对照适配完成后必须做的事是回归验证。我的习惯是同时打开 Charles 抓包和鸿蒙侧的 hilog 日志检查sonar_analysis是否真的把分析请求发到了 SonarQube 服务端而不是在本地模拟结果糊弄过去。具体验证步骤是执行一次全量分析然后在 Charles 里过滤 SonarQube 域名应该能看到 scanner 上报的POST请求再在 hilog 里观察 ArkTS 侧的事件推送日志确认进度流和告警流都有数据。两端数据对照完整才算真正跑通。这一步不能省很多团队就是栽在“本地截图看起来成功服务端却没有记录”的假适配里。6. 实测收益和后续可以继续做的事这套方案在我的工程里跑通之后最直观的变化是Dart 层和 ArkTS 层的质量数据终于合到同一个 SonarQube 仪表盘里了。团队做代码审查时不再是“看谁的报错少”而是能直接按模块、按规则、按提交记录去追溯质量波动。鸿蒙侧新引入的规则问题也会在 MR 阶段被门禁拦住而不是等到发版之后才被用户反馈暴露。后续我计划做两件事。第一把sonar_analysis的分析能力从“静态扫描”扩展到“运行时采集”定时上报鸿蒙应用的内存占用、崩溃堆栈和分布式调用链数据进一步补全运行时质量维度。第二把当前依赖本地构建产物路径的逻辑改成服务端下发配置这样 CI 和本地开发环境就不需要手工维护目录映射每位新同事接入时也不会因为路径问题卡壳。如果你也在做 Flutter 插件的鸿蒙适配我给你一个建议先别急着改业务逻辑把一个最小的通道跑通从 MethodChannel 到 EventChannel 一点点递进。通道通了后续的权限、线程、产物收集这些问题都会有明确的方向。鸿蒙的适配表象上看是 API 迁移实际上是对插件架构理解的重新梳理至少我现在看任何 Flutter 三方库第一反应都是先拆解它的通道依赖鸿蒙侧能不能接得住心里马上有数。