用Dart analyzer打造鸿蒙化适配自动化工具链

Flutter 生态里的 analyzer 这个包很多人的印象停留在“IDE 语法检查的后台引擎”但真正把它玩透之后你会发现它完全能扛起鸿蒙化适配里最脏最累的活儿扫源码、建 AST、自动生成桥接代码、做合规自检。这篇文章我结合自己在鸿蒙化改造项目里的实操经验从 analyzer 的解析机制讲起一步步拆解怎么用它构建一套面向鸿蒙工程的自动化工具链。无论是刚接触 Dart 源码分析的初学者还是已经在做跨端适配的团队都能从中找到可以直接落地的思路和代码。1. 为什么盯上 analyzer鸿蒙化场景下的真实痛点1.1 手工适配的瓶颈鸿蒙化适配 Flutter 工程绕不开一个问题Flutter 的三方库和插件怎么迁移到鸿蒙侧。拿我们团队的实际项目来说一个中型 App 依赖了上百个 Pub 包其中真正纯 Dart 实现的还好说麻烦的是那些通过 MethodChannel 调用原生能力的插件。这些插件在 Android 侧有 Kotlin/Java 实现在 iOS 侧有 Swift/OC 实现但鸿蒙侧往往什么都没有。手工去翻每个插件的源码找出所有 channel 名称、方法名、参数类型再逐个手写鸿蒙侧的 Bridge效率低不说漏掉一个 channel 或类型对不上运行期就是一片红。更头疼的是这些插件还在持续升级。今天适配完了明天插件更新一版新增一个 channel你又得重新人工 diff 一遍。这种重复劳动完全可以自动化而自动化最好的抓手就是从 Dart 源码本身入手——因为插件对外暴露的 API 全部写在 Dart 代码里MethodChannel 的调用点也全部散落在 Dart 代码中。1.2 analyzer 是什么、能做什么analyzer 是 dart.dev 官方维护的静态分析库平时我们运行的dart analyze、IDE 里的语法高亮和错误提示底层都是它在工作。它本质上做了一件事把 Dart 源码解析成结构化的数据模型然后在这套模型上提供查询、遍历、类型推断的能力。这套能力拆开看有三个层次Lexer 与 Parser把源码字符串切分成 Token再按 Dart 语法生成 AST抽象语法树。AST 里的每个节点代表一个语法元素比如类声明、方法调用、变量引用。Element 层在 AST 之上构建的语义模型。AST 只告诉你“这里有个 Identifier”Element 能告诉你“这个 Identifier 到底指向哪个类、哪个方法、哪个变量”。AnalysisSession 层负责解析 import、处理 part of、解析类型让跨文件的符号引用变得可查询。对我们做鸿蒙化适配来说第三层尤其关键。因为一个插件往往由多个文件组成A 文件里调用了 B 文件定义的方法只有把整个工程的解析上下文建起来才能准确判断某个调用到底是什么类型的方法、参数是什么类型、返回值是什么类型这些信息在自动生成桥接代码时缺一不可。1.3 适配的整体思路我们的目标不是写一个通用的鸿蒙化编译器而是聚焦三件事扫清楚、生成准、查得住。扫清楚遍历工程里所有 Dart 文件识别出 MethodChannel、EventChannel、BasicMessageChannel 的调用点以及自定义平台通道的封装类建立一张“通道-方法-参数类型”的清单。生成准根据这张清单结合模板引擎自动生成鸿蒙侧的桥接骨架代码包括 Ability 侧的通道注册、方法分发、参数解析、返回值回传。查得住用一套自定义规则扫描工程检查哪些插件尚未适配、哪些 API 在鸿蒙环境不可用、哪些配置项不符合鸿蒙工程规范把这些检查固化到 CI 里形成合规性自检能力。这三个能力的底层引擎都是 analyzer。所以接下来的内容我会先从 analyzer 的核心机制讲起再逐层展开这三个能力的实现。如果你只是急着要代码可以直接跳到第四章但建议还是把第二章过一遍因为很多坑都藏在机制理解不透上。2. analyzer 的核心机制从源码到 AST 再到语义模型2.1 解析管线从字符到节点用 analyzer 解析一段 Dart 代码标准流程是三步先建 Driver再拿 Session最后用 Parser 或parseFile接口产出 CompilationUnit。import package:analyzer/dart/analysis/analysis_context.dart; import package:analyzer/dart/analysis/analysis_context_collection.dart; import package:analyzer/dart/analysis/results.dart; // 1. 传入工程根目录创建上下文集合 final collection AnalysisContextCollection( includedPaths: [lib/, test/], ); // 2. 获取某个文件的解析上下文 final AnalysisContext context collection.contextFor(lib/main.dart); // 3. 异步解析文件得到包含 AST 的结果 final SomeFileResult result await context.currentSession.getResolvedUnit(lib/main.dart);这里有两个关键点容易搞混getResolvedUnit拿到的是 ResolvedUnitResult里面既有 AST又有完整的语义解析信息而parseFile这类接口拿到的只是 Unresolved 的 AST只有语法结构没有类型绑定。做鸿蒙化扫描时必须用 Resolved 版本否则遇到跨文件引用AST 上就只能看到一个没有语义的SimpleIdentifier你根本不知道它调用的是什么对象的方法也就没法判断是不是 MethodChannel。说到 AST 本身它的设计是典型的组合模式。一个 CompilationUnit 是整个文件的根节点往下依次是 LibraryDirective、ClassDeclaration、MethodDeclaration、Expression 等。每个节点都继承自 AstNode带有parent指针、offset、length以及visitChildren方法。这意味着你可以不用写复杂的递归遍历逻辑而是基于 Visitor 模式只关心自己感兴趣的那几类节点。2.2 Element 模型与类型解析AST 解决的是“这段代码长什么样”Element 模型解决的是“这段代码指的是什么”。这两者的区别在鸿蒙化适配里影响很大。举个例子插件代码里很常见这种写法class FlutterPlugin { static const MethodChannel _channel MethodChannel(com.example/plugin); FutureString getVersion() async { return await _channel.invokeMethod(getVersion); } }在 AST 层面MethodChannel(com.example/plugin)是一个 InstanceCreationExpression但这个表达式里的com.example/plugin只是一个字符串字面量。要拿到 channel 的名称需要先定位构造函数再去看它的第一个参数的值。在 Element 层面_channel.invokeMethod(...)这个 MethodInvocation 的方法名是invokeMethod但要判断它到底是不是 MethodChannel 的方法需要通过元素解析找到_channel这个变量的类型再顺着类型找到invokeMethod方法定义。这个过程在 analyzer 里叫 type inference 和 element resolutionAPI 上表现为DartType和Element的互相转换。这里我给出一个常用的模式import package:analyzer/dart/element/element.dart; import package:analyzer/dart/element/type.dart; DartType? resolveType(ResolvedUnitResult result, SimpleIdentifier identifier) { final element identifier.staticElement; // 变量元素 if (element is VariableElement) { return element.type; } // 方法返回值的类型 if (element is MethodElement) { return element.returnType; } return null; }staticElement是 Resolved AST 上每个标识符都带有的一个重要属性它指向前一个符号的真实定义。有了它我们才能跨文件判断类型——比如判断某个 Channel 的泛型参数是 String 还是 StringBuffer这在生成鸿蒙侧解析代码时是硬需求。2.3 Visitor 模式遍历 AST 的正确姿势analyzer 提供了AstVisitor接口你可以继承RecursiveAstVisitor然后在visitMethodInvocation、visitInstanceCreationExpression等回调里写自己的逻辑。注意一点RecursiveAstVisitor 默认会遍历所有子节点但如果你在某个节点处理完后不想继续往下钻需要重写对应的 visit 方法并手动控制。我在做通道扫描时写了一个精简版 Visitor核心逻辑是先找到MethodChannel(...)的构造调用然后往上回溯看它被赋给了哪个字段再到类里找出所有调用这个字段 invokeMethod 的地方。class ChannelVisitor extends RecursiveAstVisitorvoid { final ListChannelInfo channels []; final MapString, String _fieldToChannelName {}; override void visitInstanceCreationExpression(InstanceCreationExpression node) { super.visitInstanceCreationExpression(node); final name node.constructorName.type.name.lexeme; if (name MethodChannel || name EventChannel || name BasicMessageChannel) { // 第一个参数通常是 channel 名 final channelName _stringLiteralOf(node.argumentList.arguments.first); // 如果构造表达式被赋值给字段则记录字段名与 channel 名的映射 final assignment node.parent; if (assignment is VariableDeclaration) { _fieldToChannelName[assignment.name.lexeme] channelName; } } } }这里有个细节super.visitInstanceCreationExpression(node)一定要先调用否则嵌套在构造参数里的子节点不会被遍历到。我在早期版本漏掉这行导致部分 channel 名没扫到排查了很久才发现是遍历中断的问题。3. 鸿蒙化适配的关键改造点3.1 依赖引入与版本锁定analyzer 的 API 演进很快版本之间的 break change 不少。我们最开始用的 5.x后来升到 6.x 时AnalysisContextCollection的构造参数和getResolvedUnit的返回类型都变了。所以我建议在 pubspec.yaml 里锁死版本不要用^通配dependencies: analyzer: 6.4.1 path: ^1.9.0同时analyzer 内部依赖了_fe_analyzer_shared、pub_semver等包lock 文件一定要提交到仓库。不然同事拉下来一个不同版本的 analyzerAST 节点属性和遍历行为出现细微差异很容易产生“我本地扫得出来CI 上就扫不出来”的诡异问题。如果你是要把 analyzer 作为命令行工具嵌入到团队内部建议用dart run而不是flutter pub run因为 Flutter 工程的依赖树里经常混入不同版本的 analyzer比如 flutter_test 也依赖它不锁版本会有解析上下文冲突。3.2 读取 Flutter 与鸿蒙工程结构的差异处理纯粹的 analyzer 只认识 Dart 文件但鸿蒙化适配工具还必须读懂工程结构。Flutter 工程和鸿蒙工程的目录差异很大Flutter 侧有lib/、android/、ios/鸿蒙工程是 DevEco Studio 标准结构有entry/src/main/ets/pages、entry/src/main/ets/feature这些路径。我们定制工具时把工程根目录当成一个“复合工程”来读通过配置文件告诉工具哪些目录是 Dart 侧源码、哪些是鸿蒙侧源码。这一步处理上有一个省事的做法把所有需要扫描的目录塞进includedPaths然后自己维护一个目录映射表把 Dart 侧的 package 名与鸿蒙侧的 module 名对应起来。字段、方法的注释里如果含有harmonyChannel这类标记我们也通过 AST 的注释节点提取出来作为生成代码时的补充信息。这样 analyzer 本身不需要感知鸿蒙的概念我们只是在它之上加了一个工程语义层。3.3 自定义 API 兼容性规则注入analyzer 自带的 lint 规则是针对 Dart 语言本身的鸿蒙化场景我们需要的是业务级规则。比如某些包在主流的 Dart 环境下可用但在鸿蒙 runtime 里没有对应实现某些 API 的调用在鸿蒙侧会导致崩溃或死锁。这些规则没法靠 analyzer 内置机制直接表达我的做法是自己维护一个规则文件YAML 或 JSON里面记录不允许调用的 API 签名、可替代方案、严重级别。扫描器每到一个 MethodInvocation就把解析出的方法全名库名类名方法名和规则库比对命中就走报告逻辑。规则文件示例rules: - id: HARMONY_DISALLOW_NETWORK_METHOD target: dart:io symbol: HttpClient method: openUrl message: 鸿蒙侧不支持直接使用 dart:io 的 HttpClient请迁移到 ohos.net.http severity: error这套设计把“合规性自检”从代码里解耦出来业务同学不需要写 Dart 代码改一版 YAML 就能调整扫描策略。4. 基于 AST 的自动化代码生成实战4.1 场景设定自动生成鸿蒙侧桥接代码现在进入最核心的实战部分。我们以“自动生成鸿蒙侧 MethodChannel 桥接代码”为例把这个流程完整跑一遍。目标插件我们先简化为一个定义了三个通道的 Flutter 插件class MyPlugin { static const MethodChannel _basic MethodChannel(my_plugin/basic); static const EventChannel _events EventChannel(my_plugin/events); static const BasicMessageChannelString _messages BasicMessageChannel( my_plugin/messages, StringCodec(), ); }我们希望自动生成鸿蒙侧的一段代码包含这三个通道的注册逻辑和方法分发骨架。完全自动生成所有业务逻辑是不现实的但通道名称、通道类型、泛型参数、方法名这些“形状信息”AST 完全可以拿到。生成的产物是“带 TODO 的业务骨架”程序员只需要填充实际业务实现。这里的关键是通道名称和类型可以通过 Visitor 拿到而要生成注册代码必须知道这些通道在哪个类里、是静态字段还是实例字段。AST 的 parent 链可以帮我们回溯到FieldDeclaration和ClassDeclaration。4.2 关键步骤与代码实现第一步收集通道信息。我们在第二章的 Visitor 基础上增加字段归属信息class PluginScanner { final ListChannelDefinition channels []; void scan(ResolvedUnitResult result) { final visitor _PluginVisitor(); result.unit.visitChildren(visitor); channels.addAll(visitor.channels); } } class _PluginVisitor extends RecursiveAstVisitorvoid { final ListChannelDefinition channels []; override void visitFieldDeclaration(FieldDeclaration node) { super.visitFieldDeclaration(node); final field node.fields; for (final variable in field.variables) { final initializer variable.initializer; if (initializer is InstanceCreationExpression) { final typeName initializer.constructorName.type.name.lexeme; if (typeName MethodChannel) { final channelName _literalString(initializer.argumentList.arguments.first); final className _enclosingClassName(node); channels.add(ChannelDefinition( name: channelName, kind: MethodChannel, className: className, fieldName: variable.name.lexeme, isStatic: field.isStatic, )); } } } } }第二步根据泛型参数生成解析代码。BasicMessageChannelString的泛型参数在 AST 里是TypeArgumentList节点取它的第一个参数对应到鸿蒙侧就是编解码器的选择。这里需要查一个映射表Dart 的StringCodec对应鸿蒙的TextCodecJSONMethodCodec对应JSONCodecStandardMethodCodec对应StandardCodec。第三步生成鸿蒙代码。这里我用的是字符串模板拼接没有引入代码生成框架。好处是生成逻辑完全可控坏处是模板和逻辑耦合复杂场景下维护成本高。如果你只是做一次性适配工具字符串拼接完全够了如果工具要长期演进可以考虑 source_gen 那套的CodeBuilder思路。String generateEntryClass(ListChannelDefinition channels, String className) { final buffer StringBuffer(); buffer.writeln(import { MethodChannel, EventChannel, BasicMessageChannel } from \kit.AbilityKit\;); buffer.writeln(export class ${className}Bridge {); buffer.writeln( private constructor() {}); buffer.writeln( static registerAll(): void {); for (final ch in channels) { final memberName _toCamelCase(ch.name.split(/).last); switch (ch.kind) { case MethodChannel: buffer.writeln( MethodChannel( \${ch.name}\ ).on(call, (data) {); buffer.writeln( // TODO: 处理 ${ch.name} 的方法分发); buffer.writeln( return null;); buffer.writeln( });); break; case EventChannel: buffer.writeln( EventChannel( \${ch.name}\ ).on(listen, (data) {); buffer.writeln( // TODO: 处理 ${ch.name} 的事件流); buffer.writeln( });); break; } } buffer.writeln( }); buffer.writeln(}); return buffer.toString(); }第四步把生成的代码写入鸿蒙工程对应目录。写入前必须做一件事用 analyzer 再解析一遍生成的代码做语法校验。这块不能省因为模板里拼接的类名、方法名如果出现非法字符生成的代码很可能语法错误而语法错误在鸿蒙侧编译时才暴露反馈链路太长。用 analyzer 的parseString接口即可final parseResult parseString(content: generatedCode, path: generated/xxx.ets); if (parseResult.errors.isNotEmpty) { // 打印错误并中断生成 }4.3 代码生成的质量保障自动化生成最容易翻车的是“看起来对、实际类型不对”。比如 Dart 侧泛型是BasicMessageChannelListMapString, dynamic鸿蒙侧对应的是ArrayRecordstring, Object这种嵌套类型靠简单模板拼接容易漏掉泛型参数。所以在生成逻辑里我建议做一次显式的类型递归转换把 DartType 递归解析成鸿蒙类型签名而不是直接从toString()拿结果。另外生成后的代码一定要过一遍文字对比测试。我们团队写了一个 snapshot 测试把插件 A 扫一遍生成代码把结果存成 golden 文件每次改动工具逻辑后重新生成diff 一下有变化就说明生成结果被影响了。这比人工 review 可靠得多。5. 静态扫描与工程合规性自检5.1 扫描规则设计静态扫描的本质是把“人眼检查”转成“程序检查”。在鸿蒙化场景里我总结出三类高频规则通道一致性检查Dart 侧声明了 channel鸿蒙侧是否有对应注册。漏注册是运行时才报错工具上提前发现能省很多联调时间。禁用 API 检查某些包里的 API 明确不支持鸿蒙 runtime直接命中规则库时报错。工程规范检查比如 Dart 侧的插件注册文件pubspec.yaml里的 flutter-plugin 声明是否在鸿蒙工程里补充了对应的 plugin 映射包名是否符合 ohos 包名规范。规则引擎我建议分两层。底层复用 analyzer 的 AST 遍历上层提供规则注册接口。每个规则是一个类实现ScanRule接口有一个check(ResolvedUnitResult result)方法返回ListIssue。abstract class ScanRule { String get id; String get message; ListIssue check(ResolvedUnitResult result); } class UnregisteredChannelRule implements ScanRule { override String get id harmony/unregistered_channel; override String get message 检测到 MethodChannel 未在鸿蒙侧注册; override ListIssue check(ResolvedUnitResult result) { // 扫描 Dart 侧 channel // 扫描鸿蒙侧注册文件 // 对比后返回缺失项 return []; // 简化示例 } }这里的核心难点是“跨语言检查”。Dart 侧的 result 是 analyzer 给的鸿蒙侧的代码是 ets 文件analyzer 不认识。我的做法是鸿蒙侧不做 AST 解析而是用正则抽取MethodChannel(...)、EventChannel(...)里的字符串字面量形成注册清单再和 Dart 侧的清单做差集。正则的准确率比不上 AST但对于通道名这种固定格式足够用了。5.2 合规性自检清单与落地把规则落到工程里最终输出格式应该是一个可读性强的报告。我用了两种输出格式控制台文本和 HTML 报告。控制台文本用于本地快速排查HTML 报告用于 CI 归档和团队周报。报告内容至少包含四个维度通道清单全部扫描到的通道标注 Dart 侧/鸿蒙侧的注册状态。风险项列表按严重级别排序列出规则命中的代码位置、规则 ID、建议修改方案。统计信息总文件数、总代码行数、异常项占比。时间戳与版本号用于追溯是哪次代码改动引入的问题。5.3 CI 集成工具最终要跑在 CI 里才有价值。我们的做法是在 GitLab CI 上加一个 stage在 MR 创建后跑一遍扫描任务产物作为 artifact 输出同时用exit code控制流水线是否放行。这里有几个坑扫描工具要用dart compile exe编译成二进制不能每次 CI 都现拉依赖现编译否则一次 MR 流水线要多等两分钟。依赖版本要固化到pubspec.lockCI 环境里dart pub get --offline跑一遍确保和本地一致。规则库的 YAML 文件要放到仓库里让扫描工具用相对路径读取而不是绝对路径否则换一台机器就找不到规则。CI 脚本核心逻辑长这样dart run tool/scanner.dart scan \ --input lib/ \ --harmony-dir entry/src/main/ets \ --rules tool/rules.yaml \ --report out/report.html test $? -eq 0 echo 合规性检查通过 || exit 16. 常见问题与排查技巧实录6.1 问题速查表现象可能原因解决办法getResolvedUnit抛异常提示文件不在 context 中文件的父目录没被加入includedPaths确认目录配置扫描前先打印 context 包含的目录AST 里staticElement为 null用的是parseFile而不是getResolvedUnit未做语义解析切换到 Resolved 版本接口channel 名扫出来一半另一半缺失Visitor 里遗漏了super.visitXxx()调用导致子节点未遍历检查所有 visit 回调确保调用了 super生成的鸿蒙代码编译报错重复注册同一个 Dart 文件被扫描了两遍主文件和 import 的文件都扫了维护一个已扫描文件集合用文件绝对路径去重泛型参数类型不对直接用toString()取类型没有做递归解析自己写类型递归转换函数CI 上和本地扫描结果不一致依赖版本不一致或锁文件未提交锁定 analyzer 版本提交 pubspec.lockCI 用--offline安装6.2 避坑心得第一个坑是性能。大型 Flutter 工程可能有上千个 Dart 文件逐个调用getResolvedUnit会非常慢一次全量扫描可能跑好几分钟。我后来改成优先用分析上下文的缓存只解析发生过变化的文件其余文件直接复用上次的 ResolutionResult。如果你只是做一次性适配可以忽略性能优化但如果你打算把工具接到 CI 上这个优化必做。第二个坑是 AST 节点的生命周期。ResolvedUnitResult返回的 AST 节点关联着内部缓存不能长期持有节点引用否则会把整个工程的内存顶上去。我的做法是在每个文件的 visitor 回调里立刻把需要的信息提取成普通对象比如前文中的ChannelDefinition处理完就丢掉 AST只保留提取结果。第三个坑是我自己在鸿蒙侧桥接代码上踩过的通道名称在 Dart 侧是常量拼接出来的比如my_plugin/$version这种动态 channel 名 AST 拿不到真实值。遇到这种情况我建议在插件代码里加一个静态常量表把所有通道名列出来扫描器优先读这个常量表读不到再回退到 AST 解析。这也是从实际项目里总结出的妥协方案——纯静态扫描做不到 100% 覆盖工具要设计成“能扫则扫扫不到就提示人工确认”。在实际适配了十多个插件之后我的体会是analyzer 这套库最大的价值不是“能解析 Dart”而是它把“源代码结构”变成了一套标准化的、可程序化查询的数据模型。你不需要自己去写词法分析器、不用纠结注释怎么提取、不用处理泛型的复杂推导这些都是 analyzer 已经做好的事。我们要做的只是理解它的机制然后把自己的业务规则挂在上面。鸿蒙化适配的自动化代码生成也好静态扫描也好本质都是“读懂源码、建立映射、输出结果”而这三步在 analyzer 的加持下比大多数团队想象中要简单得多。最后再分享一个小技巧写扫描工具的时候先拿一个只有十几个文件的简单插件做端到端验证再逐步扩展到全量工程这样调试成本最低也最能快速暴露机制理解的偏差。