作者：閒魚技術-龍湫
1、背景
最近在項目中使用到了Dart中的註解代碼生成技術，這跟之前Java中APT+JavaPoet生成代碼那套技術還是有一些不同的地方，比如
Flutter中在禁用了dart:mirror，無法使用反射情況下如何得到類相關信息？
Dart的文件不限制是class，可以是function、class，因而在註解掃描的範圍不同的情況下如何拿到層層信息而不僅僅是toplevel信息？
提取到註解信息時又是如何生成複雜的模板代碼?
在Flutter中究竟是如何上面的問題呢？下面將一步步揭開這神祕的面紗。
2、一個簡單的例子
先從一個簡單的例子感受下dart中如何通過註解生成代碼
- 聲明一個註解，並使用註解
在Dart中構造器用const修飾就好，可以看出Dart的註解聲明起來比較簡單，不像java中還得有運行類型如RunTime、Source等
- 解析註解的生成器
在Dart中我們一般使用source_gen中的GeneratorForAnnotation,該類繼承自Generator這個跟Java APT中的processor職責類似,需要在GeneratorForAnnotation的泛型中填入我們需要處理的註解
- 觸發生成器的Builer
有了上面的生成註解的生成器，我們還需要Builder來觸發
- 創建配置文件 build.yaml
- 運行builder
由於Flutter 禁用了dart:mirror無法使用反射，因此只能在通過命令在編譯期觸發，執行如下命令，將會看到生成的代碼
是不是感受到了Dart註解生成代碼的奇特之處了，有像Java中AnnotationProcessor Tool的Generator，但是又多了Builder和build.yaml，那麼這些是如何相互配合運行生成註解的呢？
3、宏觀概覽
使用望遠鏡宏觀概覽整個過程
當我們使用build_runner的 build之後 觸發build，會去讀取build.yaml文件的配置信息，這個信息最終會被
build_config.dart中的BuildConfig類讀取到，然後通過讀取到builder,上面例子的testBuilder，觸發了其中的註解生成器（TestGenerator)，來對抽象語法樹進行信息提取(由於source_gen封裝了語法分析庫analysis和資源處理庫build,這裏實際上是屏蔽了語法分析過程)，跟java一樣都是一個個Element,具體可以看下代碼的實現類
歸納一下主要有以下個核心部分：
用戶觸發 - 文件掃描 - 詞法分析 - 註解提取 - 代碼生成
4、微觀探索
再使用放大鏡仔仔細細研究一下其中的細節:
4.1 build.yaml配置
在Java中我們使用谷歌提供的AutoService註解來生成META-INF/services/javax.annotation.processing.Processor 文件關聯註解處理器，但是Flutter中的dart註解只能在編譯期做文章，因此需要一個配置告訴編譯器，觸發哪些builder，對應的就是build.yaml文件，
先看一個build.yaml配置感受一下
build.yaml 配置的信息，最終都會被 build_config.dart 中的 BuildConfig 類讀取到。
關於參數說明，目前也沒有太多資料，這裏推薦官方說明build_config,通過build_config包下的Builde_Config解析
解析入口如下
從build_config.dart中可以看到，主要解析4個大的部分，下面將挑選常用的2個進行分析
4.1.1 targets
在 build_target.dart#BuildTarget 可以看到支持屬性的描述，其中有個builder屬性使用的比較多
在TargetBuilderConfig中有3個常用的屬性
- enable
當前builder是否生效
- generate_for
這個屬性比較重要，可以決定針對那些文件/文件夾做掃描，或者排除哪些文件 input_set.dart，使用如下
在json_seriable的build.yaml中也可以看到它的yaml文件中對generate_for屬性的使用
- options
這個屬性可以允許你以鍵值對形式攜帶一些配置數據到代碼生成器中，對應的是BuildOption參數，下面在解讀builder時候會再次講述
4.1.2 builder
來一個builder
BuilderOptions可以提取到上面的option屬性配置
在build.yaml文件中描述如上，
Map<String, BuilderDefinition> 即 BuilderDefinition 信息，下面將介紹一下常用的配置
更多配置可以參考builder_definition.dart
其中有2個重要的屬性單獨解釋一下
- run_before
可以指定builder的運行順序，如果幾個buidler有互相依賴可以，比如在阿里的路由框架annotation_route中就使用到了這個屬性，可以看看其yaml文件，主要在路由框架中使用到了mustache4dart需要收集路由信息來填充模板，它的解法是使用兩個builder，一個用來收集信息(routeWriteBuilder)，收集完之後給另一個builder(routeBuilder)結合mustache4dart模板來生成需要的路由表，具體可以參考其route_generator.dart
- auto_apply
看文字可能理解起來可能有點晦澀，搞個圖來解釋一下，比如上圖 libB中使用了註解功能:
- 當我們將auto_apply設置成dependents時:
如果 註解package 是直接依賴在 libB 上的，那麼只能在 libB 上正常使用註解，雖然 頂層Package 包依賴了 libB，但是依然無法正常使用該註解
- 當我們將auto_apply設置成all_packages時:
如果 註解package 是直接依賴在 libB 上的，那麼在 libB 和 頂層Package上都能正常使用註解
- 當我們將auto_apply設置成root_package時:
如果 註解package 是直接依賴在 libB 上的，那麼只能在頂層 Package 上正常使用註解，雖然是 libB 上做的依賴，但是就是不能用,不過 註解package 是直接依賴在 頂層Package 上的時候，不管 auto_apply 設置的是 dependents、all_packages 或者是 root_package 時，其實都是能正常使用的
4.2 關於source_gen
4.2.1 簡介
瞭解完了基本配置的yaml文件之後，不得不提source_gen這個強大的庫，
source_gen基於官方的 analysis/build提供了一系列友好的封裝，source_gen 基於 analyzer 和 build 庫，其中
- build庫主要是資源文件的處理
- analyser庫是對dart文件生成語法結構
source_gen主要提處理dart源碼，可以通過註解生成代碼。
4.2.2核心類介紹
source_gen從build庫提供的Builder派生出自己的_builder，並且封裝了3個
Builder (builder.dart)
|_Builder (builder.dart)
|-LibraryBuilder (builder.dart)
|-SharedPartBuilder (builder.dart)
|-PartBuilder (builder.dart)
• SharedPartBuilder
生成.g.dart文件，類似json_seriable一樣，使用地方需要用是part of引用，這樣有個最大的好處就是引用問題不需要過於關注，要注意的是，需要使用 source_gen|combining_builder，它會將所有.g文件進行合併。
• LibraryBuilder
生成獨立的文件
• PartBuilder
自定義part文件
生成器Generator
並且source_gen封裝了一套Generator，以上的buidler接收Generator的集合,收集Generator的產出生成一份文件，Generator只是一個抽象類，具體實現類是GeneratorForAnnotation，默認只能攔截到top-level級別的(後面會解釋)元素，會被註解生成器接受一個指定註解類型，即GeneratorForAnnotation是單註解處理器例如
由於analyser提供了語法節點的抽象元素Element和其metadata字段，對應ElementAnnotation，註解生成器可以檢查元素的metadata類型是否匹配聲明的註解類型，從而找出被註解的元素及元素所在上下文的信息，然後將這些信息包裝給使用者。
核心方法generateForAnnotatedElement
例如我們有這樣一段註解代碼
從上面可以看出主要覆寫了generateForAnnotatedElement方法，有三個關鍵參數
- Element element
被 annotation 所修飾的元素，通過它可以獲取到元素的name、metadata、可見性等等。
更多api可以查看element
關於toplevel註解
前文提到只能攔截到toplevel級別的元素，因此class內部的方法其實都沒有掃描到，這是由於dart 文件是不像java，一個文件只能對應一個類，dart文件可以是function，也是是class或者其他，因此只能默認攔截到top-level級別的，後面需要開發者自己手動處理，比如ClassElement提供了 methods、fields來給開發者進一步處理註解的機會，下面展示瞭解析類中的方法，屬性也是類似的
Element除了ClassElementImpl外還有多個派生如 FunctionElementImpl、ParamElementImpl等，具體可以自行查閱。
- ConstantReader annotation
表示註解對象，通過它可以提取到註解相關信息以及參數值
有兩個關鍵方法
• read
• peek
不同之處在於，如果read方法讀取了不存在的參數名，會拋出異常，peek則不會，而是返回null。
- BuildStep buildStep
這一次構建的信息，通過它可以獲取到一些輸入輸出信息，例如輸入文件名等
4.2.3核心代碼分析
source_gen也是從build庫的Builder封裝而來
source_gen根據Builder實現自己的的_Builder,根據不同的特點派生出 SharedPartBuilder、LibraryBuilder、PartBuilder
這裏面有個核心的 Generator
在 Builder 運行時，會調用 Generator 的 generate方法，並傳入兩個重要的參數：
- library 可以獲取源代碼信息以及註解信息
- buildStep 它表示構建過程中的一個步驟，通過它，我們可以獲取一些文件的輸入輸出信息
其中library 包含的源碼信息是一個個的 Element 元素，Element只是抽象類，具體還是一個個ClassElementImpl、FuncationElementImpl等。
source_gen實現了該類 GeneratorForAnnotation
其中 第2點中library.annotatedWith(typeChecker)跟進去看下
5、關於代碼生成
- 純字符串拼接
使用三引號語法，這種只能解決一些低級生成
- mustach
預製模板，通過一定的規則，提取信息之後填充信息到模板中，一個典型的例子如下
學習成本較低(瞭解mustach更多規則)，適合一些固定格式的代碼生成，比如路由表，阿里的annotation_route框架就是採用這個，可以看下它的模板tpl，
然後使用了2個生成器，一個用來採集信息，另一個用來將採集後的信息注入到mustach模板中
非常強大，玩過java註解生成代碼的朋友一定熟悉javapoet，二者非常類似，code_builder可以細分爲表達式、語句、函數、類等等，就是學習成本比較高，需要按照它的語法去生成對應的代碼，比如生成一個類
生成一個表達式
更多技巧需要看下源碼去學習使用。
6、與Java註解生成代碼對比
7、小結
本文初步探索了在Dart通過註解生成代碼的技術，比起java的apt，沒有運行時反射用起來還是有點點麻煩，需要手動執行build，而且各種繁瑣的builder配置，讓人感覺晦澀難懂，生成代碼的技巧也跟java有着異曲同工之妙，需要藉助一些外力比如mustach,code_builder等。這種技術給我們在解決一些例如路由，模板代碼、動態代理等，多了一種處理手段，其他更多的使用場景需要我們去開發中慢慢探索。