欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

前言

在 OpenHarmony 应用开发中，我们经常使用 json_serializable 或 riverpod 等库，它们通过 dart run build_runner build 命令自动生成大量的样板代码。这些库背后的核心引擎正是 source_gen。

如果你想为鸿蒙项目编写一些“黑科技”工具，例如：

• 扫描所有包含 @OhosAbility 注解的类并自动生成路由表。
• 根据自定义注解自动生成跨端桥接代码。
• 自动为 Data 类生成字段映射器。

那么，掌握 source_gen 是从“代码搬运工”走向“架构设计师”的必经之路。

一、核心原理解析

source_gen 为 Dart 的 build 库提供了更高层的抽象。它通过分析 AST（抽象语法树）来识别注解，并生成对应的字符串代码。

二、核心 API 实战

2.1 定义自定义注解

在代码生成的语境下，注解通常是一个简单的 const 类，用于在源代码中标记需要被扫描的目标。

class OhosRoute {
  final String path;
  final String title;
  
  // 💡 注解必须有 const 构造函数，因为它运行在编译期
  const OhosRoute({required this.path, this.title = ""});
}

// 使用方式：
@OhosRoute(path: '/details', title: '详情页')
class DetailAbility {}

2.2 实现生成器 (Generator)

生成器是 source_gen 的核心。它会拿到被注解标记的元素，并返回一个生成的代码字符串。

import 'package:source_gen/source_gen.dart';
import 'package:analyzer/dart/element/element.dart';

class OhosRouteGenerator extends GeneratorForAnnotation<OhosRoute> {
  @override
  String generateForAnnotatedElement(
    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 代码的拼接逻辑
class OhosPermissionGenerator {
  String generateCheckFunction(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();
  }
}

void main() {
  final gen = OhosPermissionGenerator();
  // 生成代码字符串
  final generatedCode = gen.generateCheckFunction('CameraAbility', ['ohos.camera', 'ohos.mic']);
  
  print(generatedCode);
}

五、总结

source_gen 软件包是构建 OpenHarmony 高级开发工具的基石。它赋予了开发者“通过代码编写代码”的超能力。在追求“零重复劳动”的鸿蒙工业化开发流程中，学会利用 source_gen 构建自动化的元数据处理流程，能极大地提升项目的稳定性和开发效率。