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
方法,并传入两个重要的参数:
自我介绍一下,小编13年上海交大毕业,曾经在小公司待过,也去过华为、OPPO等大厂,18年进入阿里一直到现在。
深知大多数初中级安卓工程师,想要提升技能,往往是自己摸索成长,但自己不成体系的自学效果低效又漫长,而且极易碰到天花板技术停滞不前!
因此收集整理了一份《2024年最新Android移动开发全套学习资料》送给大家,初衷也很简单,就是希望能够帮助到想自学提升又不知道该从何学起的朋友,同时减轻大家的负担。
由于文件比较大,这里只是将部分目录截图出来,每个节点里面都包含大厂面经、学习笔记、源码讲义、实战项目、讲解视频
如果你觉得这些内容对你有帮助,可以添加下面V无偿领取!(备注Android)
新的开始
改变人生,没有什么捷径可言,这条路需要自己亲自去走一走,只有深入思考,不断反思总结,保持学习的热情,一步一步构建自己完整的知识体系,才是最终的制胜之道,也是程序员应该承担的使命。
如果有需要进阶Android高级工程师系统学习资料的,我可以免费分享给大家,需要完整版的朋友,【点这里可以看到全部内容】。
《系列学习视频》
《系列学习文档》
《我的大厂面试之旅》
)]
新的开始
改变人生,没有什么捷径可言,这条路需要自己亲自去走一走,只有深入思考,不断反思总结,保持学习的热情,一步一步构建自己完整的知识体系,才是最终的制胜之道,也是程序员应该承担的使命。
如果有需要进阶Android高级工程师系统学习资料的,我可以免费分享给大家,需要完整版的朋友,【点这里可以看到全部内容】。
《系列学习视频》
[外链图片转存中…(img-R1D4fYiN-1710658937513)]
《系列学习文档》
[外链图片转存中…(img-akQ29rDn-1710658937514)]
《我的大厂面试之旅》
[外链图片转存中…(img-N0bVnr90-1710658937514)]