Flutter for OpenHarmony: Flutter 三方库 source_gen 自动化代码生成的幕后英雄（打造自己的 build_runner 插件）
欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.ZEEKLOG.net
前言
在 OpenHarmony 应用开发中，我们经常使用 json_serializable 或 riverpod 等库，它们通过 dart run build_runner build 命令自动生成大量的样板代码。这些库背后的核心引擎正是 source_gen。
如果你想为鸿蒙项目编写一些“黑科技”工具，例如：
- 扫描所有包含
@OhosAbility注解的类并自动生成路由表。 - 根据自定义注解自动生成跨端桥接代码。
- 自动为 Data 类生成字段映射器。
那么，掌握 source_gen 是从“代码搬运工”走向“架构设计师”的必经之路。
一、核心原理解析
source_gen 为 Dart 的 build 库提供了更高层的抽象。它通过分析 AST（抽象语法树）来识别注解，并生成对应的字符串代码。
分析注解
源代码 (.dart)
Build Runner
source_gen Generator
Element Annotation Analyzer
生成逻辑代码字符串
生成的辅助文件 (.g.dart)
二、核心 API 实战
2.1 定义自定义注解
在代码生成的语境下，注解通常是一个简单的 const 类，用于在源代码中标记需要被扫描的目标。
classOhosRoute{finalString path;finalString title;// 💡 注解必须有 const 构造函数，因为它运行在编译期constOhosRoute({required this.path,this.title =""});}// 使用方式：@OhosRoute(path:'/details', title:'详情页')classDetailAbility{}
2.2 实现生成器 (Generator)
生成器是 source_gen 的核心。它会拿到被注解标记的元素，并返回一个生成的代码字符串。
import'package:source_gen/source_gen.dart';import'package:analyzer/dart/element/element.dart';classOhosRouteGeneratorextendsGeneratorForAnnotation<OhosRoute>{@overrideStringgenerateForAnnotatedElement(Element element,ConstantReader annotation,BuildStep buildStep ){// 1. 💡 获取被注解类的名称final className = element.name;// 2. 💡 从注解中读取参数值final path = annotation.read('path').stringValue;// 3. 💡 返回生成的代码字符串（将写入 .g.dart）return'void goTo$className(BuildContext context) => Navigator.pushNamed(context, "$path");';}}
2.3 配置 Builder 文件
要在项目中使用，需在 build.yaml 中配置：
builders:ohos_route_builder:import:"package:my_tool/builder.dart"builder_factories:["ohosRouteBuilder"]build_extensions:{".dart":[".ohos.g.dart"]}
三、OpenHarmony 平台适配
3.1 跨语言元数据提取
💡 技巧：在鸿蒙开发中，如果需要将 Dart 的接口定义同步给 ArkTS。你可以利用 source_gen 扫描 Dart 定义，并自动生成一份对应的 .ts 声明文件，从而保证两端接口的绝对同步。
3.2 离线代码生成优势
source_gen 的所有操作都在编译前完成。生成的代码是纯正的 Dart 源码，不包含任何运行时反射逻辑。这完美契合了鸿蒙系统的 AOT 安全与性能要求。
四、完整实战示例：鸿蒙权限声明自动检查器
本示例模拟了生成器在扫描到带权限注解的类后，如何自动生成一套配套的权限查验逻辑。
import'package:source_gen/source_gen.dart';/// 💡 模拟生成器产出 .g.dart 代码的拼接逻辑classOhosPermissionGenerator{StringgenerateCheckFunction(String className,List<String> permissions){final code =StringBuffer(); code.writeln('// 🛡️ 为 $className 自动生成的权限预检函数'); code.writeln('Future<bool> check${className}Auth() async {');for(var p in permissions){ code.writeln(' // 调用鸿蒙底层 API 校验权限: $p'); code.writeln(' if (!await OhosInternal.hasPermission("$p")) return false;');} code.writeln(' return true;'); code.writeln('}');return code.toString();}}voidmain(){final gen =OhosPermissionGenerator();// 生成代码字符串final generatedCode = gen.generateCheckFunction('CameraAbility',['ohos.camera','ohos.mic']);print(generatedCode);}
五、总结
source_gen 软件包是构建 OpenHarmony 高级开发工具的基石。它赋予了开发者“通过代码编写代码”的超能力。在追求“零重复劳动”的鸿蒙工业化开发流程中，学会利用 source_gen 构建自动化的元数据处理流程，能极大地提升项目的稳定性和开发效率。
