2024 Flutter 重大更新，Dart 宏（Macros）编程开始支持，JSON 序列化有救

说起宏编程可能大家并不陌生，但是这对于 Flutter 和 Dart 开发者来说它一直是一个「遗憾」，这个「遗憾」体现在编辑过程的代码修改支持上，其中最典型的莫过于 Dart 的 JSON 序列化。

举个例子，目前 Dart 语言的 JSON 序列化高度依赖 build_runner 去生成 Dart 代码，例如在实际使用中我们需要：

  • 依赖 json_serializable ，通过注解声明一个 Event 对象
  • 运行 flutter packages pub run build_runner build 生成文件
  • 得到 Event.g.dart 文件，在项目中使用它去实现 JSON 的序列化和反序列化
2024 Flutter 重大更新，Dart 宏（Macros）编程开始支持，JSON 序列化有救 - 图1 2024 Flutter 重大更新，Dart 宏（Macros）编程开始支持，JSON 序列化有救 - 图2

这里最大的问题在于，我们需要通过命令行去生成一个项目文件，并且这个文件我们还可以随意手动修改，从开发角度来说，这并不优雅也不方便。

而宏声明是用户定义的 Dart 类，它可以实现一个或多个新的内置宏接口，Dart 中的宏是用正常的命令式 Dart 代码来开发，不存在单独的“宏语言”。

大多数宏并不是简单地从头开始生成新代码，而是根据程序的现有属性去添加代码，例如向 Class 添加 JSON 序列化的宏，可能会查看 Class 声明的字段，并从中合成一个 toJson() ，将这些字段序列化为 JSON 对象。

我们首先看一段官方的 Demo ， 如下代码所示，可以看到 ：

  • MyState 添加了一个自定义的 @AutoDispose() 注解，这是一个开发者自己实现的宏声明，并且继承了 State 对象，带有 dispose 方法。
  • 在 MyState 里有多个 a、a2 、b 和 c 三个对象，其中 a、a2 、b 都实现了 Disposable 接口，都有 dispose 方法
  • 虽然 a、a2 、b 和 MyState 的 dispose(); 方法来自不同基类实现，但是基于 @AutoDispose() 的实现，在代码调用 state.dispose(); 时， a、a2 、b 变量的 dispose 方法也会被同步调用
  1. import 'package:macro_proposal/auto_dispose.dart';
  3. void main() {
  4.   var state = MyState(a: ADisposable(), b: BDisposable(), c: 'hello world');
  5.   state.dispose();
  6. }
  8. @AutoDispose()
  9. class MyState extends State {
  10.   final ADisposable a;
  11.   final ADisposable? a2;
  12.   final BDisposable b;
  13.   final String c;
  15.   MyState({required this.a, this.a2, required this.b, required this.c});
  17.   @override
  18.   String toString() => 'MyState!';
  19. }
  21. class State {
  22.   void dispose() {
  23.     print('disposing of $this');
  24.   }
  25. }
  27. class ADisposable implements Disposable {
  28.   void dispose() {
  29.     print('disposing of ADisposable');
  30.   }
  31. }
  33. class BDisposable implements Disposable {
  34.   void dispose() {
  35.     print('disposing of BDisposable');
  36.   }
  37. }

如下图所示，可以看到，尽管 MyState 没用主动调用 a、a2 、b 变量的 dispose 方法，并且它们和 MyState 的 dispose 也来自不同基类，但是最终执行所有 dispose 方法都被成功调用，这就是@AutoDispose() 的宏声明实现在编译时对代码进行了调整。

2024 Flutter 重大更新，Dart 宏（Macros）编程开始支持，JSON 序列化有救 - 图3

如下图所示是 @AutoDispose() 的宏编程实现，其中 macro 就是一个标志性的宏关键字，剩下的代码可以看到基本就是 dart 脚本的实现， macro 里主要是实现 ClassDeclarationsMacro 和buildDeclarationsForClass方法，如下代码可以很直观看到关于 super.dispose(); 和 disposeCalls 的相关实现。

  1. import 'package:_fe_analyzer_shared/src/macros/api.dart';
  3. // Interface for disposable things.
  4. abstract class Disposable {
  5.   void dispose();
  6. }
  8. macro class AutoDispose implements ClassDeclarationsMacro, ClassDefinitionMacro {
  9.   const AutoDispose();
  11.   @override
  12.   void buildDeclarationsForClass(
  13.       ClassDeclaration clazz, MemberDeclarationBuilder builder) async {
  14.     var methods = await builder.methodsOf(clazz);
  15.     if (methods.any((d) => d.identifier.name == 'dispose')) {
  16.       // Don't need to add the dispose method, it already exists.
  17.       return;
  18.     }
  20.     builder.declareInType(DeclarationCode.fromParts([
  21.       // TODO: Remove external once the CFE supports it.
  22.       'external void dispose();',
  23.     ]));
  24.   }
  26.   @override
  27.   Future<void> buildDefinitionForClass(
  28.       ClassDeclaration clazz, TypeDefinitionBuilder builder) async {
  29.     var disposableIdentifier =
  30.         // ignore: deprecated_member_use
  31.         await builder.resolveIdentifier(
  32.             Uri.parse('package:macro_proposal/auto_dispose.dart'),
  33.             'Disposable');
  34.     var disposableType = await builder
  35.         .resolve(NamedTypeAnnotationCode(name: disposableIdentifier));
  37.     var disposeCalls = <Code>[];
  38.     var fields = await builder.fieldsOf(clazz);
  39.     for (var field in fields) {
  40.       var type = await builder.resolve(field.type.code);
  41.       if (!await type.isSubtypeOf(disposableType)) continue;
  42.       disposeCalls.add(RawCode.fromParts([
  43.         '\n',
  44.         field.identifier,
  45.         if (field.type.isNullable) '?',
  46.         '.dispose();',
  47.       ]));
  48.     }
  50.     // Augment the dispose method by injecting all the new dispose calls after
  51.     // either a call to `augmented()` or `super.dispose()`, depending on if
  52.     // there already is an existing body to call.
  53.     //
  54.     // If there was an existing body, it is responsible for calling
  55.     // `super.dispose()`.
  56.     var disposeMethod = (await builder.methodsOf(clazz))
  57.         .firstWhere((method) => method.identifier.name == 'dispose');
  58.     var disposeBuilder = await builder.buildMethod(disposeMethod.identifier);
  59.     disposeBuilder.augment(FunctionBodyCode.fromParts([
  60.       '{\n',
  61.       if (disposeMethod.hasExternal || !disposeMethod.hasBody)
  62.         'super.dispose();'
  63.       else
  64.         'augmented();',
  65.       ...disposeCalls,
  66.       '}',
  67.     ]));
  68.   }
  69. }

到这里大家应该可以直观感受到宏编程的魅力，上述 Demo 来自 dart-language 的 macros/example/auto_dispose_main ，其中 bin/ 目录下的代码是运行的脚本示例，lib/ 目录下的代码是宏编程实现的示例：

https://github.com/dart-lang/language/tree/main/working/macros/example

当然，因为现在是实验性阶段，API 和稳定性还有待商榷，所以想运行这些 Demo 还需要一些额外的处理，比如版本强关联，例如上述的 auto_dispose_main 例子：

另外，还有一个第三方例子是来自 millsteed 的 macros ，这是一个简单的 JSON 序列化实现 Demo ，并且可以直接不用额外下载 dark-sdk，通过某个 flutter 内置 dart-sdk 版本就可以满足条件：3.19.0-12.0.pre ：

在本地 Flutter 目录下，切换到 git checkout 3.19.0-12.0.pre ，然后执行 flutter doctor 初始化 dark sdk 即可。

代码的实现很简单，首先看 bin 下的示例，通过 @Model() 将 GetUsersResponse 和 User 声明为 JSON 对象，然后在运行时，宏编程会自动添加 fromJson 和 toJson 方式。

  1. import 'dart:convert';
  3. import 'package:macros/model.dart';
  5. @Model()
  6. class User {
  7.   User({
  8.     required this.username,
  9.     required this.password,
  10.   });
  12.   final String username;
  13.   final String password;
  14. }
  16. @Model()
  17. class GetUsersResponse {
  18.   GetUsersResponse({
  19.     required this.users,
  20.     required this.pageNumber,
  21.     required this.pageSize,
  22.   });
  24.   final List<User> users;
  25.   final int pageNumber;
  26.   final int pageSize;
  27. }
  29. void main() {
  30.   const body = '''
  31.     {
  32.       "users": [
  33.         {
  34.           "username": "ramon",
  35.           "password": "12345678"
  36.         }
  37.       ],
  38.       "pageNumber": 1,
  39.       "pageSize": 30
  40.     }
  41.   ''';
  42.   final json = jsonDecode(body) as Map<String, dynamic>;
  43.   final response = GetUsersResponse.fromJson(json);
  44.   final ramon = response.users.first;
  45.   final millsteed = ramon.copyWith(username: 'millsteed', password: '87654321');
  46.   final newResponse = response.copyWith(users: [...response.users, millsteed]);
  47.   print(const JsonEncoder.withIndent('  ').convert(newResponse));
  48. }

而 Model 的宏实现就相对复杂一些，但是实际上就是将类似 freezed/ json_serializable 是实现调整到宏实现了，而最终效果就是，开发者使用起来更加优雅了。

  1. // ignore_for_file: depend_on_referenced_packages, implementation_imports
  3. import 'dart:async';
  5. import 'package:_fe_analyzer_shared/src/macros/api.dart';
  7. macro class Model implements ClassDeclarationsMacro {
  8.   const Model();
  10.   static const _baseTypes = ['bool', 'double', 'int', 'num', 'String'];
  11.   static const _collectionTypes = ['List'];
  13.   @override
  14.   Future<void> buildDeclarationsForClass(
  15.     ClassDeclaration classDeclaration,
  16.     MemberDeclarationBuilder builder,
  17.   ) async {
  18.     final className = classDeclaration.identifier.name;
  20.     final fields = await builder.fieldsOf(classDeclaration);
  22.     final fieldNames = <String>[];
  23.     final fieldTypes = <String, String>{};
  24.     final fieldGenerics = <String, List<String>>{};
  26.     for (final field in fields) {
  27.       final fieldName = field.identifier.name;
  28.       fieldNames.add(fieldName);
  30.       final fieldType = (field.type.code as NamedTypeAnnotationCode).name.name;
  31.       fieldTypes[fieldName] = fieldType;
  33.       if (_collectionTypes.contains(fieldType)) {
  34.         final generics = (field.type.code as NamedTypeAnnotationCode)
  35.             .typeArguments
  36.             .map((e) => (e as NamedTypeAnnotationCode).name.name)
  37.             .toList();
  38.         fieldGenerics[fieldName] = generics;
  39.       }
  40.     }
  42.     final fieldTypesWithGenerics = fieldTypes.map(
  43.       (name, type) {
  44.         final generics = fieldGenerics[name];
  45.         return MapEntry(
  46.           name,
  47.           generics == null ? type : '$type<${generics.join(', ')}>',
  48.         );
  49.       },
  50.     );
  52.     _buildFromJson(builder, className, fieldNames, fieldTypes, fieldGenerics);
  53.     _buildToJson(builder, fieldNames, fieldTypes);
  54.     _buildCopyWith(builder, className, fieldNames, fieldTypesWithGenerics);
  55.     _buildToString(builder, className, fieldNames);
  56.     _buildEquals(builder, className, fieldNames);
  57.     _buildHashCode(builder, fieldNames);
  58.   }
  60.   void _buildFromJson(
  61.     MemberDeclarationBuilder builder,
  62.     String className,
  63.     List<String> fieldNames,
  64.     Map<String, String> fieldTypes,
  65.     Map<String, List<String>> fieldGenerics,
  66.   ) {
  67.     final code = [
  68.       'factory $className.fromJson(Map<String, dynamic> json) {'.indent(2),
  69.       'return $className('.indent(4),
  70.       for (final fieldName in fieldNames) ...[
  71.         if (_baseTypes.contains(fieldTypes[fieldName])) ...[
  72.           "$fieldName: json['$fieldName'] as ${fieldTypes[fieldName]},"
  73.               .indent(6),
  74.         ] else if (_collectionTypes.contains(fieldTypes[fieldName])) ...[
  75.           "$fieldName: (json['$fieldName'] as List<dynamic>)".indent(6),
  76.           '.whereType<Map<String, dynamic>>()'.indent(10),
  77.           '.map(${fieldGenerics[fieldName]?.first}.fromJson)'.indent(10),
  78.           '.toList(),'.indent(10),
  79.         ] else ...[
  80.           '$fieldName: ${fieldTypes[fieldName]}'
  81.                   ".fromJson(json['$fieldName'] "
  82.                   'as Map<String, dynamic>),'
  83.               .indent(6),
  84.         ],
  85.       ],
  86.       ');'.indent(4),
  87.       '}'.indent(2),
  88.     ].join('\n');
  89.     builder.declareInType(DeclarationCode.fromString(code));
  90.   }
  92.   void _buildToJson(
  93.     MemberDeclarationBuilder builder,
  94.     List<String> fieldNames,
  95.     Map<String, String> fieldTypes,
  96.   ) {
  97.     final code = [
  98.       'Map<String, dynamic> toJson() {'.indent(2),
  99.       'return {'.indent(4),
  100.       for (final fieldName in fieldNames) ...[
  101.         if (_baseTypes.contains(fieldTypes[fieldName])) ...[
  102.           "'$fieldName': $fieldName,".indent(6),
  103.         ] else if (_collectionTypes.contains(fieldTypes[fieldName])) ...[
  104.           "'$fieldName': $fieldName.map((e) => e.toJson()).toList(),".indent(6),
  105.         ] else ...[
  106.           "'$fieldName': $fieldName.toJson(),".indent(6),
  107.         ],
  108.       ],
  109.       '};'.indent(4),
  110.       '}'.indent(2),
  111.     ].join('\n');
  112.     builder.declareInType(DeclarationCode.fromString(code));
  113.   }
  115.   void _buildCopyWith(
  116.     MemberDeclarationBuilder builder,
  117.     String className,
  118.     List<String> fieldNames,
  119.     Map<String, String> fieldTypes,
  120.   ) {
  121.     final code = [
  122.       '$className copyWith({'.indent(2),
  123.       for (final fieldName in fieldNames) ...[
  124.         '${fieldTypes[fieldName]}? $fieldName,'.indent(4),
  125.       ],
  126.       '}) {'.indent(2),
  127.       'return $className('.indent(4),
  128.       for (final fieldName in fieldNames) ...[
  129.         '$fieldName: $fieldName ?? this.$fieldName,'.indent(6),
  130.       ],
  131.       ');'.indent(4),
  132.       '}'.indent(2),
  133.     ].join('\n');
  134.     builder.declareInType(DeclarationCode.fromString(code));
  135.   }
  137.   void _buildToString(
  138.     MemberDeclarationBuilder builder,
  139.     String className,
  140.     List<String> fieldNames,
  141.   ) {
  142.     final code = [
  143.       '@override'.indent(2),
  144.       'String toString() {'.indent(2),
  145.       "return '$className('".indent(4),
  146.       for (final fieldName in fieldNames) ...[
  147.         if (fieldName != fieldNames.last) ...[
  148.           "'$fieldName: \$$fieldName, '".indent(8),
  149.         ] else ...[
  150.           "'$fieldName: \$$fieldName'".indent(8),
  151.         ],
  152.       ],
  153.       "')';".indent(8),
  154.       '}'.indent(2),
  155.     ].join('\n');
  156.     builder.declareInType(DeclarationCode.fromString(code));
  157.   }
  159.   void _buildEquals(
  160.     MemberDeclarationBuilder builder,
  161.     String className,
  162.     List<String> fieldNames,
  163.   ) {
  164.     final code = [
  165.       '@override'.indent(2),
  166.       'bool operator ==(Object other) {'.indent(2),
  167.       'return other is $className &&'.indent(4),
  168.       'runtimeType == other.runtimeType &&'.indent(8),
  169.       for (final fieldName in fieldNames) ...[
  170.         if (fieldName != fieldNames.last) ...[
  171.           '$fieldName == other.$fieldName &&'.indent(8),
  172.         ] else ...[
  173.           '$fieldName == other.$fieldName;'.indent(8),
  174.         ],
  175.       ],
  176.       '}'.indent(2),
  177.     ].join('\n');
  178.     builder.declareInType(DeclarationCode.fromString(code));
  179.   }
  181.   void _buildHashCode(
  182.     MemberDeclarationBuilder builder,
  183.     List<String> fieldNames,
  184.   ) {
  185.     final code = [
  186.       '@override'.indent(2),
  187.       'int get hashCode {'.indent(2),
  188.       'return Object.hash('.indent(4),
  189.       'runtimeType,'.indent(6),
  190.       for (final fieldName in fieldNames) ...[
  191.         '$fieldName,'.indent(6),
  192.       ],
  193.       ');'.indent(4),
  194.       '}'.indent(2),
  195.     ].join('\n');
  196.     builder.declareInType(DeclarationCode.fromString(code));
  197.   }
  198. }
  200. extension on String {
  201.   String indent(int length) {
  202.     final space = StringBuffer();
  203.     for (var i = 0; i < length; i++) {
  204.       space.write(' ');
  205.     }
  206.     return '$space$this';
  207.   }
  208. }

2024 Flutter 重大更新，Dart 宏（Macros）编程开始支持，JSON 序列化有救 - 图5

目前宏还处于试验性质的阶段，所以 API 还在调整，这也是为什么上面的例子需要指定 dart 版本的原因，另外宏目前规划里还有一些要求，例如

  • 所有宏构造函数都必须标记为 const
  • 所有宏必须至少实现其中一个 Macro 接口
  • 宏不能是抽象对象
  • 宏 class 不能由其他宏生成
  • 宏 class 不能包含泛型类型参数
  • 每个宏接口都需要声明宏类必须实现的方法，例如，在声明阶段应用的 ClassDeclarationsMacro及其buildDeclarationsForClass方法。

未来规划里，宏 API 可能会作为 Pub 包提供，通过库 dart:_macros来提供支持 ，具体还要等正式发布时 dart 团队的决策。

总的来说，这对于 dart 和 flutter 是一个重大的厉害消息，虽然宏编程并不是什么新鲜概念，该是 dart 终于可以优雅地实现 JSON 序列化，并且还是用 dart 来实现，这对于 flutter 开发者来说，无疑是最好的新年礼物。

所以，新年快乐～我们节后再见～