Flutter for OpenHarmony 实战：Code Builder — 自动化元编程大师

前言

在进行 Flutter for OpenHarmony 开发时，随着业务规模的膨胀，我们不可避免地会遇到大量重复的“样板代码”（Boilerplate Code）。常见的场景包括：为数百个接口编写 DTO（数据传输对象）、手动将鸿蒙原生的 ArkTS 接口定义映射为对应的 Dart 类型、或者是构建一套私有的序列化框架。

这种重复劳动不仅低效，而且极易引入人为错误。Code Builder 是 Dart 官方维护的元编程核心库，它不仅仅是一个“字符串拼接工具”，而是一套基于 AST（抽象语法树） 的顶级代码生成引擎。本文将带你领略“代码生成代码”的魅力，助你迈向鸿蒙高级架构师之路。

---

一、为什么选用 Code Builder 而非字符串拼接？

在编写代码生成器时，很多开发者喜欢使用 StringBuffer 配合模板字符串。这种方法虽然直观，但存在严重的工程隐患：

1. 语法正确性难验证：缺失闭合括号或漏掉分号在复杂模板中极难排查。
2. 导入管理混乱：手动打理 import 语句及其别名（As-prefix）非常痛苦。
3. 格式化丢失：代码风格难以统一。

Code Builder 的优势：

• 🧩 强类型安全：它将 Class、Method、Field 定义为对象，只有模型构建正确，才能输出代码。
• 🧩 自动管理依赖：它能根据你引用的 Type 自动在文件顶部计算并归纳所需的 import。
• 🧩 完美配合 dart_style：生成的代码自带标准的格式化基因，可直接通过鸿蒙 DevEco Studio 的 Linter 校验。

---

二、配置环境 📦

在项目的 pubspec.yaml 中，通常将其放置在 dev_dependencies 中，连同 dart_style 一起使用。

dev_dependencies:
  code_builder: ^4.10.0
  dart_style: ^2.3.6      # 用于对生成后的字符串进行排版
  build_runner: ^2.4.0

💡 注意：code_builder 专注于内存中的代码建模，实际写入磁盘通常建议配合脚本或 build 包。

---

三、核心功能：3 个代码建模核心技巧

3.1 定义一个带构造函数的鸿蒙 Service (Class)

使用链式调用定义一个完整的类，并为其注入构造参数。

import 'package:code_builder/code_builder.dart';

final myClass = Class((b) => b
  ..name = 'OhosDeviceService' // 类名
  ..constructors.add(Constructor((con) => con
    ..constant = true
    ..requiredParameters.add(Parameter((p) => p
      ..name = 'deviceId'
      ..toThis = true)) // 自动映射 this.deviceId
  ))
);

3.2 声明带有逻辑的方法 (Method)

定义一个返回 Future 的异步函数，并添加 Overidding 注解。

final initMethod = Method((m) => m
  ..name = 'initialize'
  ..returns = refer('Future<void>')
  ..annotations.add(refer('override'))
  ..modifier = MethodModifier.async // 💡 技巧：自动注入 async 关键字
  ..body = const Code('print("🚀 鸿蒙环境就绪");')
);

3.3 构建带有复杂依赖的库 (Library)

将多个类整合进一个文件，并自动补充头部的特定引用。

final library = Library((l) => l
  ..body.addAll([myClass, initMethod])
  ..directives.add(Directive.import('package:flutter/foundation.dart'))
);

// 渲染为字符串
final emitter = DartEmitter(orderDirectives: true);
print(library.accept(emitter));

---

四、OpenHarmony 平台适配与最佳实践

在鸿蒙工程中引入自动化代码生成时，建议遵循以下流程：

4.1 自动绑定鸿蒙原生接口 (Glue Code) 🏗️

⚠️ 现状：鸿蒙有大量的 Native 模块（ArkTS 写法）。

• ✅ 建议做法：编写一个 Node.js 或 Dart 脚本，解析 ArkTS 的接口定义（.d.ts），然后通过 Code Builder 动态生成对应的 Dart MethodChannel 封装层。这样每当鸿蒙原生接口变更，只需重跑脚本即可。

4.2 避免手动修改生成内容

• 💡 技巧：生成的代码文件应当以 .g.dart 或 .gen.dart 结尾，并在顶部加入 // GENERATED CODE - DO NOT MODIFY BY HAND 标志。这能有效防止团队协作中因手动修改后被覆盖导致的逻辑丢失。

---

五、完整实战示例：构建鸿蒙“数据模型”一键生成器

我们将模拟一个极具实用价值的工具：根据给定的字段列表，自动生成一个完整的、不可变的（Immutable）鸿蒙 Data Model 类。它包含私有字段、构造函数以及标准的代码注释。

import 'package:flutter/material.dart';
import 'package:code_builder/code_builder.dart';
import 'package:dart_style/dart_style.dart';

class OhosModelGeneratorPage extends StatefulWidget {
  const OhosModelGeneratorPage({super.key});

  @override
  State<OhosModelGeneratorPage> createState() => _OhosModelGeneratorPageState();
}

class _OhosModelGeneratorPageState extends State<OhosModelGeneratorPage> {
  String _generatedCode = "";
  final List<String> _fields = ['productId', 'title', 'versionMark', 'desc'];

  void _generate() {
    const modelName = 'OhosProductInfo';

    // 1. 构建 Class 骨架
    final dataClass = Class((c) => c
      ..name = modelName
      ..docs.add('/// 鸿蒙系统专用：自动生成的不可变数据模型')
      ..fields.addAll(_fields.map((field) => Field((f) => f
        ..name = field
        ..modifier = FieldModifier.final$
        ..type = refer('String'))))
      ..constructors.add(Constructor((con) => con
        ..constant = true
        ..requiredParameters.addAll(_fields.map((field) => Parameter((p) => p
          ..name = field
          ..toThis = true))))));

    // 2. 将 Class 封装进 Library
    final library = Library((l) => l.body.add(dataClass));

    // 3. 渲染代码并美化
    final emitter = DartEmitter(orderDirectives: true);
    final rawSource = library.accept(emitter).toString();

    setState(() {
      _generatedCode = DartFormatter().format(rawSource);
    });
  }

  @override
  void initState() {
    super.initState();
    _generate();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('鸿蒙 Data Model 生成器')),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          children: [
            const Text('配置字段: productId, title, versionMark, desc',
                style: TextStyle(color: Colors.blueGrey, fontSize: 13)),
            const SizedBox(height: 16),
            Expanded(
              child: Container(
                width: double.infinity,
                padding: const EdgeInsets.all(12),
                decoration: BoxDecoration(
                  color: const Color(0xFF2B2B2B),
                  borderRadius: BorderRadius.circular(12),
                ),
                child: SingleChildScrollView(
                  child: Text(
                    _generatedCode,
                    style: const TextStyle(
                      fontFamily: 'monospace',
                      color: Color(0xFFA9B7C6),
                      fontSize: 12,
                    ),
                  ),
                ),
              ),
            ),
            const SizedBox(height: 16),
            ElevatedButton.icon(
              onPressed: _generate,
              icon: const Icon(Icons.refresh),
              label: const Text('重新生成代码'),
              style: ElevatedButton.styleFrom(
                minimumSize: const Size(double.infinity, 45),
              ),
            ),
          ],
        ),
      ),
    );
  }
}

---

六、总结

在 Flutter for OpenHarmony 时代的开发者不仅仅是代码的搬运工，更应该是工具链的创造者。掌握了 Code Builder，你就能如同操作“上帝视角”一般，操控 AST 级别的代码流。

无论是处理鸿蒙特有的 MethodChannel 冗余，还是构建高性能的数据模型解析，这类元编程技巧都将是你技术溢价的最强背书。

---

🌐 欢迎加入开源鸿蒙跨平台社区：开源鸿蒙跨平台开发者社区