用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'); Future<String> 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 resolution，API 上表现为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 RecursiveAstVisitor<void> { final List<ChannelInfo> channels = []; final Map<String, 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 文件一定要提交到仓库。不然同事拉下来一个不同版本的 analyzer，AST 节点属性和遍历行为出现细微差异，很容易产生“我本地扫得出来，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 BasicMessageChannel<String> _messages = BasicMessageChannel( 'my_plugin/messages', StringCodec(), ); }

我们希望自动生成鸿蒙侧的一段代码，包含这三个通道的注册逻辑和方法分发骨架。完全自动生成所有业务逻辑是不现实的，但通道名称、通道类型、泛型参数、方法名这些“形状信息”，AST 完全可以拿到。生成的产物是“带 TODO 的业务骨架”，程序员只需要填充实际业务实现。

这里的关键是：通道名称和类型可以通过 Visitor 拿到，而要生成注册代码，必须知道这些通道在哪个类里、是静态字段还是实例字段。AST 的 parent 链可以帮我们回溯到FieldDeclaration和ClassDeclaration。

4.2 关键步骤与代码实现

第一步，收集通道信息。我们在第二章的 Visitor 基础上，增加字段归属信息：

class PluginScanner { final List<ChannelDefinition> channels = []; void scan(ResolvedUnitResult result) { final visitor = _PluginVisitor(); result.unit.visitChildren(visitor); channels.addAll(visitor.channels); } } class _PluginVisitor extends RecursiveAstVisitor<void> { final List<ChannelDefinition> 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, )); } } } } }

第二步，根据泛型参数生成解析代码。BasicMessageChannel<String>的泛型参数在 AST 里是TypeArgumentList节点，取它的第一个参数，对应到鸿蒙侧就是编解码器的选择。这里需要查一个映射表：Dart 的StringCodec对应鸿蒙的TextCodec，JSONMethodCodec对应JSONCodec，StandardMethodCodec对应StandardCodec。

第三步，生成鸿蒙代码。这里我用的是字符串模板拼接，没有引入代码生成框架。好处是生成逻辑完全可控，坏处是模板和逻辑耦合，复杂场景下维护成本高。如果你只是做一次性适配工具，字符串拼接完全够了；如果工具要长期演进，可以考虑 source_gen 那套的CodeBuilder思路。

String generateEntryClass(List<ChannelDefinition> 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 侧泛型是BasicMessageChannel<List<Map<String, dynamic>>>，鸿蒙侧对应的是Array<Record<string, 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)方法，返回List<Issue>。

abstract class ScanRule { String get id; String get message; List<Issue> check(ResolvedUnitResult result); } class UnregisteredChannelRule implements ScanRule { @override String get id => 'harmony/unregistered_channel'; @override String get message => '检测到 MethodChannel 未在鸿蒙侧注册'; @override List<Issue> check(ResolvedUnitResult result) { // 扫描 Dart 侧 channel // 扫描鸿蒙侧注册文件 // 对比后返回缺失项 return []; // 简化示例 } }

这里的核心难点是“跨语言检查”。Dart 侧的 result 是 analyzer 给的，鸿蒙侧的代码是 ets 文件，analyzer 不认识。我的做法是：鸿蒙侧不做 AST 解析，而是用正则抽取MethodChannel(...)、EventChannel(...)里的字符串字面量，形成注册清单，再和 Dart 侧的清单做差集。正则的准确率比不上 AST，但对于通道名这种固定格式，足够用了。

5.2 合规性自检清单与落地

把规则落到工程里，最终输出格式应该是一个可读性强的报告。我用了两种输出格式：控制台文本和 HTML 报告。控制台文本用于本地快速排查，HTML 报告用于 CI 归档和团队周报。

报告内容至少包含四个维度：

1. 通道清单：全部扫描到的通道，标注 Dart 侧/鸿蒙侧的注册状态。
2. 风险项列表：按严重级别排序，列出规则命中的代码位置、规则 ID、建议修改方案。
3. 统计信息：总文件数、总代码行数、异常项占比。
4. 时间戳与版本号：用于追溯是哪次代码改动引入的问题。

5.3 CI 集成

工具最终要跑在 CI 里才有价值。我们的做法是在 GitLab CI 上加一个 stage，在 MR 创建后跑一遍扫描任务，产物作为 artifact 输出，同时用exit code控制流水线是否放行。这里有几个坑：

• 扫描工具要用dart compile exe编译成二进制，不能每次 CI 都现拉依赖现编译，否则一次 MR 流水线要多等两分钟。
• 依赖版本要固化到pubspec.lock，CI 环境里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 1

6. 常见问题与排查技巧实录

6.1 问题速查表

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 的加持下，比大多数团队想象中要简单得多。最后再分享一个小技巧：写扫描工具的时候，先拿一个只有十几个文件的简单插件做端到端验证，再逐步扩展到全量工程，这样调试成本最低，也最能快速暴露机制理解的偏差。