Flutter 注解处理及代码生成

清理生成的文件无需手动删除，可执行以下命令：

flutter packages pub run build_runner clean

Dart-APT Api详解

• 1.注解创建与使用
• 2.创建生成器 Generator
• 3.generateForAnnotatedElement 参数: element
• 4.generateForAnnotatedElement 参数: annotation
• 5.generateForAnnotatedElement 参数: buildStep
• 6.模板代码生成技巧
• 7.配置文件字段含义

1.注解创建与使用

Dart的注解创建和普通的class创建没有任何区别，可以 extends, 可以 implements ，甚至可以 with。

唯一必须的要求是：构造方法需要用 const 来修饰。

不同于java注解的创建需要指明@Target（定义可以修饰对象范围）

Dart 的注解没有修饰范围，定义好的注解可以修饰类、属性、方法、参数。

但值得注意的是，如果你的 Generator 直接继承自 GeneratorForAnnotation， 那你的 Generator 只能拦截到 top-level 级别的元素，对于类内部属性、方法等无法拦截，类内部属性、方法修饰注解暂时没有意义。（不过这个事情扩展一下肯定可以实现的啦~）

2.创建生成器 Generator

Generator 为创建代码而生。通常情况下，我们将继承 GeneratorForAnnotation，并在其泛型参数中添加目标 annotation。然后复写 generateForAnnotatedElement 方法，最终 return 一个字符串，便是我们要生成的代码。

class TestGenerator extends GeneratorForAnnotation {
@override
generateForAnnotatedElement(
Element element, ConstantReader annotation, BuildStep buildStep) {
return “class Tessss{}”;
}
}

GeneratorForAnnotation的注意点有：

2.1 GeneratorForAnnotation与annotation的对应关系

GeneratorForAnnotation是单注解处理器，每一个 GeneratorForAnnotation 必须有且只有一个 annotation 作为其泛型参数。也就是说每一个继承自GeneratorForAnnotation的生成器只能处理一种注解。

2.2 generateForAnnotatedElement 参数含义

最值得关注的是 generateForAnnotatedElement 方法的三个参数：Element element, ConstantReader annotation, BuildStep buildStep。我们生成代码所依赖的信息均来自这三个参数。

• Element element：被 annotation 所修饰的元素，通过它可以获取到元素的name、可见性等等。
• ConstantReader annotation：表示注解对象，通过它可以获取到注解相关信息以及参数值。
• BuildStep buildStep：这一次构建的信息，通过它可以获取到一些输入输出信息，例如输入文件名等

generateForAnnotatedElement 的返回值是一个 String，你需要用字符串拼接出你想要生成的代码，return null 意味着不需要生成文件。

2.3 代码与文件生成规则

不同于java apt，文件生成完全由开发者自定义。GeneratorForAnnotation 的文件生成有一套自己的规则。

在不做其他深度定制的情况下，如果 generateForAnnotatedElement 的返回值 永不为空，则：

• 若一个源文件仅含有一个被目标注解修饰的类，则每一个包含目标注解的文件，都对应一个生成文件；

• 若一个源文件含有多个被目标注解修饰的类，则生成一个文件，generateForAnnotatedElement方法被执行多次，生成的代码通过两个换行符拼接后，输出到该文件中。

3.generateForAnnotatedElement 参数: Element

例如我们有这样一段代码，使用了 @TestMetadata 这个注解：

@ParamMetadata(“ParamMetadata”, 2)
@TestMetadata(“papapa”)
class TestModel {
int age;
int bookNum;

void fun1() {}

void fun2(int a) {}
}

在 generateForAnnotatedElement 方法中，我们可以通过 Element 参数获取 TestModel 的一些简单信息：

element.toString: class TestModel
element.name: TestModel
element.metadata: [@ParamMetadata(“ParamMetadata”, 2),@TestMetadata(“papapa”)]
element.kind: CLASS
element.displayName: TestModel
element.documentationComment: null
element.enclosingElement: flutter_annotation|lib/demo_class.dart
element.hasAlwaysThrows: false
element.hasDeprecated: false
element.hasFactory: false
element.hasIsTest: false
element.hasLiteral: false
element.hasOverride: false
element.hasProtected: false
element.hasRequired: false
element.isPrivate: false
element.isPublic: true
element.isSynthetic: false
element.nameLength: 9
element.runtimeType: ClassElementImpl
…

由前文我们知道，GeneratorForAnnotation的域仅限于class, 通过 element 只能拿到 TestModel 的类信息，那类内部的 Field 和 method 信息如何获取呢？

关注 kind 属性值： element.kind: CLASS，kind 标识 Element 的类型，可以是 CLASS、FIELD、FUNCTION 等等。

对应这些类型，还有相应的 Element 子类：ClassElement、FieldElement、FunctionElement等等，所以你可以这样：

if(element.kind == ElementKind.CLASS){
for (var e in ((element as ClassElement).fields)) {
print(“KaTeX parse error: Undefined control sequence: \n at position 3: e \̲n̲"); } for (var …e \n”);
}
}

输出：
int age
int bookNum
fun1() → void
fun2(int a) → void

4.generateForAnnotatedElement 参数: annotation

注解除了标记以外，携带参数也是注解很重要的能力之一。注解携带的参数，可以通过 annotation 获取：

annotation.runtimeType: _DartObjectConstant
annotation.read(“name”): ParamMetadata
annotation.read(“id”): 2
annotation.objectValue: ParamMetadata (id = int (2); name = String (‘ParamMetadata’))

annotation 的类型是 ConstantReader，除了提供 read 方法来获取具体参数以外，还提供了peek方法，它们两个的能力相同，不同之处在于，如果read方法读取了不存在的参数名，会抛出异常，peek则不会，而是返回null。

5.generateForAnnotatedElement 参数: buildStep

buildStep 提供的是该次构建的输入输出信息:

buildStep.runtimeType: BuildStepImpl
buildStep.inputId.path: lib/demo_class.dart
buildStep.inputId.extension: .dart
buildStep.inputId.package: flutter_annotation
buildStep.inputId.uri: package:flutter_annotation/demo_class.dart
buildStep.inputId.pathSegments: [lib, demo_class.dart]
buildStep.expectedOutputs.path: lib/demo_class.g.dart
buildStep.expectedOutputs.extension: .dart
buildStep.expectedOutputs.package: flutter_annotation

6.模板代码生成技巧

现在，你已经获取了所能获取的三个信息输入来源，下一步则是根据这些信息来生成代码。

如何生成代码呢？你有以下两个选择：

6.1 简单模板代码，字符串拼接：

如果需要生成的代码不是很复杂，则可以直接用字符串进行拼接，比如这样：

generateForAnnotatedElement(
Element element, ConstantReader annotation, BuildStep buildStep) {
…
StringBuffer codeBuffer = StringBuffer(“\n”);
codeBuffer…write(“class “)
…write(element.name)
…write(”_APT{”)
…writeln(“\n”)
…writeln(“}”);

return codeBuffer.toString();
}

不过一般情况下我们并不建议这样做，因为这样写起来太容易出错了，且不具备可读性。

6.2 复杂模板代码，dart 多行字符串+占位符

dart提供了一种三引号的语法，用于多行字符串：

var str3 = “”“大王叫我来巡山
路口遇见了如来
“””;

结合占位符后，可以实现比较清晰的模板代码：

tempCode(String className) {
return “”"
class ${className}APT {

}
“”";
}

generateForAnnotatedElement(
Element element, ConstantReader annotation, BuildStep buildStep) {
…
return tempCode(element.name);
}

如果参数过多的话，tempCode方法的参数可以替换为一个Map。

(在模板代码中不要忘记import package哦~ 建议先在编译器里写好模板代码，编译器静态检查没有问题了，再放到三引号中修改占位符)

如果你熟悉java-apt的话，看到这里应该会想问，dart里有没有类似 javapoet 这样的代码库来辅助生成代码啊？从个人角度来说，更推荐第二种方式去生成代码，因为它表现的足够清晰，具有足够高的可读性，比起javapoet这种模式，可以更容易的理解模板代码意义，编写也更加简单。

7.配置文件字段含义

在工程根目录下创建build.yaml 文件，用来配置Builder相关信息。

以下面配置为例：

builders:
test_builder:
import: ‘package:flutter_annotation/test_builder.dart’
builder_factories: [‘testBuilder’]
build_extensions: { ‘.dart’: [‘.g1.dart’] }
required_inputs:[‘.dart’]
auto_apply: root_package
build_to: source

test_builder2:
import: ‘package:flutter_annotation/test_builder2.dart’
builder_factories: [‘testBuilder2’]
build_extensions: { ‘.dart’: [‘.g.dart’] }
auto_apply: root_package
runs_before: [‘flutter_annotation|test_builder’]
build_to: source

在builders 下配置你所有的builder。test_builder与 test_builder2 均是你的builder命名。

• import 关键字用于导入 return Builder 的方法所在包 （必须）
• builder_factories 填写的是我们 return Builder 的方法名（必须）
• build_extensions 指定输入扩展名到输出扩展名的映射，比如我们接受.dart文件的输入，最终输出.g.dart 文件（必须）
• auto_apply 指定builder作用于，可选值： （可选，默认为 none）
• “none”：除非手动配置，否则不要应用此Builder
• “dependents”：将此Builder应用于包，直接依赖于公开构建器的包。
• “all_packages”：将此Builder应用于传递依赖关系图中的所有包。
• “root_package”：仅将此Builder应用于顶级包。
• build_to 指定输出位置,可选值： （可选，默认为 cache）
• “source”: 输出到其主要输入的源码树上
• “cache”: 输出到隐藏的构建缓存上
• required_inputs 指定一个或一系列文件扩展名，表示在任何可能产生该类型输出的Builder之后运行（可选）
• runs_before 保证在指定的Builder之前运行

配置字段的解释较为拗口，这里我只列出了常用的一些配置字段，还有一些不常用的字段可以在 source_gen 的github主页 查阅。

Java-APT & Dart-APT对比以及 Dart-APT 的特殊性

下面我们将列出 Java-APT 和 Dart-APT 的主要区别，做一下对比，以此加深你的理解和提供注意事项。

1.注解定义

Java-APT： 需在定义注解时指定注解被解析时机（编码阶段、源码阶段、运行时阶段）,以及注解作用域（类、方法、属性）

Dart-APT： 无需指定注解被解析时机以及注解作用域，默认 Anytime and anywhere

2.注解与注解处理器的关系

Java-APT： 一个注解处理器可以指定多个注解进行处理

Dart-APT： 使用 source_gen 提供的默认处理器： GeneratorForAnnotation ，一个处理器只能处理一个注解。

3.注解拦截范围

Java-APT： 每一个合法使用的注解均可以被注解处理器拦截。

Dart-APT： 使用 source_gen 提供的默认处理器： GeneratorForAnnotation ，处理器只能处理 top-level级别的元素，例如直接在.dart 文件定义的Class、function、enums等等，但对于类内部Fields、functions 上使用的注解则无法拦截。

4.注解与生成文件的关系

Java-APT： 注解和生成文件的个数并无直接关系，开发者自行定义

Dart-APT： 在注解处理器返回值不为空的情况下，通常一个输入文件对应一个输出文件，如果不想生成文件，只需要在Generate的方法中return null即可 。若一个输入文件包含多个注解，每个成功被拦截到的注解都会触发generateForAnnotatedElement 方法的调用，多次触发而得到的返回值，最终会写入到同一个文件当中。

5.注解处理器之间的运行顺序

Java-APT： 无法直接指定多个处理器之间的执行顺序

Dart-APT： 可以指定多个处理器之间的执行顺序，在配置文件build.yaml中指定key值 runs_before 或 required_inputs

6.多个注解信息合并处理

Java-APT： 注解处理器指定多个需要处理的注解后，可以在信息采集结束后统一处理

Dart-APT： 默认一个处理器只能处理一个注解，想要合并处理需指定处理器的执行顺序，先执行的注解处理器负责不同类型注解的信息采集（采集的数据可以用静态变量保存），最后执行的处理器负责处理之前保存好的数据。

第3、第4点与Java-APT非常不一样，你可能还有点懵，这里用一个栗子来说明：

栗子

假设我们有两个文件：

example.dart

@ParamMetadata(“ClassOne”, 1)
class One {
@ParamMetadata(“field1”, 2)
int age;
@ParamMetadata(“fun1”, 3)
void fun1() {}
}

@ParamMetadata(“ClassTwo”, 4)
class Two {
int age;
void fun1() {}
}

example1.dart

@ParamMetadata(“ClassThree”, 5)
class Three {
int age;
void fun1() {}
}

Generate实现如下：

class TestGenerator extends GeneratorForAnnotation {
@override
generateForAnnotatedElement(Element element, ConstantReader annotation, BuildStep buildStep) {
print(“当前输入源： ${buildStep.inputId.toString()} 被拦截到的元素： ${element.name} 注解值： ${annotation.read(“name”).stringValue} ${annotation.read(“id”).intValue}”);
return tempCode(element.name);
}

tempCode(String className) {
return “”"
class ${className}APT {
}
“”";
}
}

执行 flutter packages pub run build_runner build

控制台输出信息：

当前输入源： flutter_annotation|lib/example.dart 被拦截到的元素： One 注解值： ClassOne 1
当前输入源： flutter_annotation|lib/example.dart 被拦截到的元素： Two 注解值： ClassTwo 4
当前输入源： flutter_annotation|lib/example1.dart 被拦截到的元素： Three 注解值： ClassThree 5

生成的文件：

• lib
• example.dart
• example.g.dart
• example.dart
• example1.g.dart

example.g.dart

class OneAPT {}

class TwoAPT {}

example1.g.dart

class ThreeAPT {}

栗子总结

在文件 example.dart 中，我们有两个Class使用了注解，其中一个Class除了Class本身以外，它的field 和 function 也使用了注解。

但在输出中，我们只拦截到了 ClassOne, 并没有被拦截到 field1 fun1。

这解释了：

• library.annotatedWith 遍历的 Element 仅包括top-level级别的 Element，也就是那些文件级别的 Class、function等等，而Class 内部的 fields、functions并不在遍历范围，如果在 Class 内部的fields 或 functions 上修饰注解，GeneratorForAnnotation并不能拦截到！

生成的 .g.dart 文件当中，因为Class One 和 Class Two 都在文件 example.dart 中，所以生成的代码也都拼接在了文件_example.g.dart_中。

这解释了：

• 若一个输入文件包含多个注解，每个成功被拦截到的注解都会触发 generateForAnnotatedElement 方法的调用，多次触发而得到的返回值，最终会写入到同一个文件当中。

另外一个文件_example1.dart_ 则单独生成了文件 example1.g.dart。

这解释了：

• 当返回值不为空的情况下，每一个文件输入源对应着一个文件输出。也就是说源码中，每一个*.dart文件都会触发一次generate方法调用，如果返回值不为空，则输出一个文件。

Dart-APT Generator 源码浅析

1.Generator 源码浅析

Generator源码炒鸡炒鸡简单：

abstract class Generator {
const Generator();

/// Generates Dart code for an input Dart library.
///
/// May create additional outputs through the buildStep, but the ‘primary’
/// output is Dart code returned through the Future. If there is nothing to
/// generate for this library may return null, or a Future that resolves to
/// null or the empty string.
FutureOr generate(LibraryReader library, BuildStep buildStep) => null;

@override
String toString() => runtimeType.toString();
}

就这么几行代码，在 Builder 运行时，会调用 Generator 的 generate方法，并传入两个重要的参数：

• library 通过它，我们可以获取源代码信息以及注解信息
• buildStep 它表示构建过程中的一个步骤，通过它，我们可以获取一些文件的输入输出信息

值得注意的是，library 包含的源码信息是一个个的 Element 元素，这些 Element 可以是Class、可以是function、enums等等。

ok，让我们再来看看 source_gen 中，Generator 的唯一子类 ：GeneratorForAnnotation 的源码：

abstract class GeneratorForAnnotation extends Generator {
const GeneratorForAnnotation();

//1 typeChecker 用来做注解检查
TypeChecker get typeChecker => TypeChecker.fromRuntime(T);

@override
FutureOr generate(LibraryReader library, BuildStep buildStep) async {
var values = Set();

//2 遍历所有满足 注解 类型条件的element
for (var annotatedElement in library.annotatedWith(typeChecker)) {
//3 满足检查条件的调用 generateForAnnotatedElement 执行开发者自定义的代码生成逻辑
var generatedValue = generateForAnnotatedElement(
annotatedElement.element, annotatedElement.annotation, buildStep);
//4 generatedValue是将要生成的代码字符串，通过normalizeGeneratorOutput格式化
await for (var value in normalizeGeneratorOutput(generatedValue)) {
assert(value == null || (value.length == value.trim().length));
//5 生成的代码加入集合
values.add(value);
}
}
//6
自我介绍一下，小编13年上海交大毕业，曾经在小公司待过，也去过华为、OPPO等大厂，18年进入阿里一直到现在。

深知大多数初中级Android工程师，想要提升技能，往往是自己摸索成长或者是报班学习，但对于培训机构动则近万的学费，着实压力不小。自己不成体系的自学效果低效又漫长，而且极易碰到天花板技术停滞不前！

因此收集整理了一份《2024年Android移动开发全套学习资料》，初衷也很简单，就是希望能够帮助到想自学提升又不知道该从何学起的朋友，同时减轻大家的负担。

既有适合小白学习的零基础资料，也有适合3年以上经验的小伙伴深入学习提升的进阶课程，基本涵盖了95%以上Android开发知识点，真正体系化！

由于文件比较大，这里只是将部分目录截图出来，每个节点里面都包含大厂面经、学习笔记、源码讲义、实战项目、讲解视频，并且会持续更新！

如果你觉得这些内容对你有帮助，可以扫码获取！！（备注：Android）

题外话

不管怎么样，不论是什么样的大小面试，要想不被面试官虐的不要不要的，只有刷爆面试题题做好全面的准备，当然除了这个还需要在平时把自己的基础打扎实，这样不论面试官怎么样一个知识点里往死里凿，你也能应付如流啊

这里我为大家准备了一些我工作以来以及参与过的大大小小的面试收集总结出来的一套进阶学习的视频及面试专题资料包，主要还是希望大家在如今大环境不好的情况下面试能够顺利一点，希望可以帮助到大家~

欢迎评论区讨论。

《互联网大厂面试真题解析、进阶开发核心学习笔记、全套讲解视频、实战项目源码讲义》点击传送门即可获取！

果你觉得这些内容对你有帮助，可以扫码获取！！（备注：Android）**

题外话

不管怎么样，不论是什么样的大小面试，要想不被面试官虐的不要不要的，只有刷爆面试题题做好全面的准备，当然除了这个还需要在平时把自己的基础打扎实，这样不论面试官怎么样一个知识点里往死里凿，你也能应付如流啊

这里我为大家准备了一些我工作以来以及参与过的大大小小的面试收集总结出来的一套进阶学习的视频及面试专题资料包，主要还是希望大家在如今大环境不好的情况下面试能够顺利一点，希望可以帮助到大家~

[外链图片转存中…(img-48feW9XR-1712754945692)]

欢迎评论区讨论。

《互联网大厂面试真题解析、进阶开发核心学习笔记、全套讲解视频、实战项目源码讲义》点击传送门即可获取！