本文介紹瞭如何自定義Java註解處理器及涉及到的相關知識，看完本文可以很輕鬆看懂並理解各大開源框架的註解處理器的應用。

> 《遊園不值》
> 應憐屐齒印蒼苔 ，小扣柴扉久不開 。
> 春色滿園關不住 ，一枝紅杏出牆來 。
> -宋，葉紹翁

本文首發：[http://yuweiguocn.github.io/](https://link.jianshu.com?t=http://yuweiguocn.github.io/)

關於自定義Java註解請檢視[自定義註解](https://link.jianshu.com?t=http://yuweiguocn.github.io/java-annotation/)。

> 本文已授權微信公眾號：鴻洋（hongyangAndroid）原創首發。

## 基本實現

實現一個自定義註解處理器需要有兩個步驟，第一是實現Processor介面處理註解，第二是註冊註解處理器。

### 實現Processor介面

透過實現Processor介面可以自定義註解處理器，這裡我們採用更簡單的方法透過繼承AbstractProcessor類實現自定義註解處理器。實現抽象方法process處理我們想要的功能。

```
public class CustomProcessor extends AbstractProcessor {
    @Override
    public boolean process(Set extends TypeElement> annotations, RoundEnvironment roundEnvironment) {
        return false;
    }
}

```

除此之外，我們還需要指定支援的註解型別以及支援的Java版本透過重寫getSupportedAnnotationTypes方法和getSupportedSourceVersion方法：

```
public class CustomProcessor extends AbstractProcessor {
    @Override
    public boolean process(Set extends TypeElement> annotations, RoundEnvironment roundEnvironment) {
        return false;
    }
    @Override
    public Set<string> getSupportedAnnotationTypes() {
        Set<string> annotataions = new LinkedHashSet<string>();
        annotataions.add(CustomAnnotation.class.getCanonicalName());
        return annotataions;
    }

@Override
    public SourceVersion getSupportedSourceVersion() {
        return SourceVersion.latestSupported();
    }
}

```

對於指定支援的註解型別，我們還可以透過註解的方式進行指定：

```
@SupportedAnnotationTypes({"io.github.yuweiguocn.annotation.CustomAnnotation"})
public class CustomProcessor extends AbstractProcessor {
    @Override
    public boolean process(Set extends TypeElement> annotations, RoundEnvironment roundEnvironment) {
        return false;
    }
    @Override
    public SourceVersion getSupportedSourceVersion() {
        return SourceVersion.latestSupported();
    }
}

```

> 因為Android平臺可能會有相容問題，建議使用重寫getSupportedAnnotationTypes方法指定支援的註解型別。

### 註冊註解處理器

最後我們還需要將我們自定義的註解處理器進行註冊。新建res資料夾，目錄下新建META-INF資料夾，目錄下新建services資料夾，目錄下新建javax.annotation.processing.Processor檔案，然後將我們自定義註解處理器的全類名寫到此檔案：

```
io.github.yuweiguocn.processor.CustomProcessor

```

上面這種註冊的方式太麻煩了，谷歌幫我們寫了一個註解處理器來生成這個檔案。
github地址：[https://github.com/google/auto](https://link.jianshu.com?t=https://github.com/google/auto)
新增依賴：

```
compile 'com.google.auto.service:auto-service:1.0-rc2'

```

新增註解：

```
@AutoService(Processor.class)
public class CustomProcessor extends AbstractProcessor {
    ...
}

```

搞定，體會到註解處理器的強大木有。後面我們只需關注註解處理器中的處理邏輯即可。

我們來看一下最終的專案結構：

![](//upload-images.jianshu.io/upload_images/618971-49eb4ca95036c22e.png?imageMogr2/auto-orient/strip%7CimageView2/2/w/304/format/webp)

## 基本概念

抽象類中還有一個init方法，這是Processor介面中提供的一個方法，當我們編譯程式時註解處理器工具會呼叫此方法並且提供實現ProcessingEnvironment介面的物件作為引數。

```
@Override
public synchronized void init(ProcessingEnvironment processingEnvironment) {
    super.init(processingEnvironment);
}

```

我們可以使用ProcessingEnvironment獲取一些實用類以及獲取選項引數等：

| 方法 | 說明 |
| --- | --- |
| Elements getElementUtils() | 返回實現Elements介面的物件，用於操作元素的工具類。 |
| Filer getFiler() | 返回實現Filer介面的物件，用於建立檔案、類和輔助檔案。 |
| Messager getMessager() | 返回實現Messager介面的物件，用於報告錯誤資訊、警告提醒。 |
| Map<string> getOptions() | 返回指定的引數選項。 |
| Types getTypeUtils() | 返回實現Types介面的物件，用於操作型別的工具類。 |

### 元素

Element元素是一個介面，表示一個程式元素，比如包、類或者方法。以下元素型別介面全部繼承自Element介面：

| 型別 | 說明 |
| --- | --- |
| ExecutableElement | 表示某個類或介面的方法、構造方法或初始化程式（靜態或例項），包括註解型別元素。 |
| PackageElement | 表示一個包程式元素。提供對有關包及其成員的資訊的訪問。 |
| TypeElement | 表示一個類或介面程式元素。提供對有關型別及其成員的資訊的訪問。注意，列舉型別是一種類，而註解型別是一種介面。 |
| TypeParameterElement | 表示一般類、介面、方法或構造方法元素的形式型別引數。 |
| VariableElement | 表示一個欄位、enum 常量、方法或構造方法引數、區域性變數或異常引數。 |

如果我們要判斷一個元素的型別，應該使用Element.getKind()方法配合ElementKind列舉類進行判斷。儘量**避免使用instanceof進行判斷**，因為比如TypeElement既表示類又表示一個介面，這樣判斷的結果可能不是你想要的。例如我們判斷一個元素是不是一個類：

```
if (element instanceof TypeElement) { //錯誤，也有可能是一個介面
}

if (element.getKind() == ElementKind.CLASS) { //正確
    //doSomething
}

```

下表為ElementKind列舉類中的部分常量，詳細資訊請檢視官方文件。

| 型別 | 說明 |
| --- | --- |
| PACKAGE | 一個包。 |
| ENUM | 一個列舉型別。 |
| CLASS | 沒有用更特殊的種類（如 ENUM）描述的類。 |
| ANNOTATION_TYPE | 一個註解型別。 |
| INTERFACE | 沒有用更特殊的種類（如 ANNOTATION_TYPE）描述的介面。 |
| ENUM_CONSTANT | 一個列舉常量。 |
| FIELD | 沒有用更特殊的種類（如 ENUM_CONSTANT）描述的欄位。 |
| PARAMETER | 方法或構造方法的引數。 |
| LOCAL_VARIABLE | 區域性變數。 |
| METHOD | 一個方法。 |
| CONSTRUCTOR | 一個構造方法。 |
| TYPE_PARAMETER | 一個型別引數。 |

### 型別

TypeMirror是一個介面，表示 Java 程式語言中的型別。這些型別包括基本型別、宣告型別（類和介面型別）、陣列型別、型別變數和 null 型別。還可以表示萬用字元型別引數、executable 的簽名和返回型別，以及對應於包和關鍵字 void 的偽型別。以下型別介面全部繼承自TypeMirror介面：

| 型別 | 說明 |
| --- | --- |
| ArrayType | 表示一個陣列型別。多維陣列型別被表示為元件型別也是陣列型別的陣列型別。 |
| DeclaredType | 表示某一宣告型別，是一個類 (class) 型別或介面 (interface) 型別。這包括引數化的型別（比如 java.util.Set<string>）和原始型別。TypeElement 表示一個類或介面元素，而 DeclaredType 表示一個類或介面型別，後者將成為前者的一種使用（或呼叫）。 |
| ErrorType | 表示無法正常建模的類或介面型別。 |
| ExecutableType | 表示 executable 的型別。executable 是一個方法、構造方法或初始化程式。 |
| NoType | 在實際型別不適合的地方使用的偽型別。 |
| NullType | 表示 null 型別。 |
| PrimitiveType | 表示一個基本型別。這些型別包括 boolean、byte、short、int、long、char、float 和 double。 |
| ReferenceType | 表示一個引用型別。這些型別包括類和介面型別、陣列型別、型別變數和 null 型別。 |
| TypeVariable | 表示一個型別變數。 |
| WildcardType | 表示萬用字元型別引數。 |

同樣，如果我們想判斷一個TypeMirror的型別，應該使用TypeMirror.getKind()方法配合TypeKind列舉類進行判斷。儘量**避免使用instanceof進行判斷**，因為比如DeclaredType既表示類 (class) 型別又表示介面 (interface) 型別，這樣判斷的結果可能不是你想要的。

TypeKind列舉類中的部分常量，詳細資訊請檢視官方文件。

| 型別 | 說明 |
| --- | --- |
| BOOLEAN | 基本型別 boolean。 |
| INT | 基本型別 int。 |
| LONG | 基本型別 long。 |
| FLOAT | 基本型別 float。 |
| DOUBLE | 基本型別 double。 |
| VOID | 對應於關鍵字 void 的偽型別。 |
| NULL | null 型別。 |
| ARRAY | 陣列型別。 |
| PACKAGE | 對應於包元素的偽型別。 |
| EXECUTABLE | 方法、構造方法或初始化程式。 |

### 建立檔案

Filer介面支援透過註解處理器建立新檔案。可以建立三種檔案型別：原始檔、類檔案和輔助資原始檔。

1.建立原始檔

```
JavaFileObject createSourceFile(CharSequence name,
                                Element... originatingElements)
                                throws IOException

```

建立一個新的原始檔，並返回一個物件以允許寫入它。檔案的名稱和路徑（相對於原始檔的根目錄輸出位置）基於該檔案中宣告的型別。如果宣告的型別不止一個，則應該使用主要頂層型別的名稱（例如，宣告為 public 的那個）。還可以建立原始檔來儲存有關某個包的資訊，包括包註解。要為指定包建立原始檔，可以用 name 作為包名稱，後跟 ".package-info"；要為未指定的包建立原始檔，可以使用 "package-info"。

2.建立類檔案

```
JavaFileObject createClassFile(CharSequence name,
                               Element... originatingElements)
                               throws IOException

```

建立一個新的類檔案，並返回一個物件以允許寫入它。檔案的名稱和路徑（相對於類檔案的根目錄輸出位置）基於將寫入的型別名稱。還可以建立類檔案來儲存有關某個包的資訊，包括包註解。要為指定包建立類檔案，可以用 name 作為包名稱，後跟 ".package-info"；為未指定的包建立類檔案不受支援。

3.建立輔助資原始檔

```
FileObject createResource(JavaFileManager.Location location,
                          CharSequence pkg,
                          CharSequence relativeName,
                          Element... originatingElements)
                          throws IOException

```

建立一個用於寫入操作的新輔助資原始檔，併為它返回一個檔案物件。該檔案可以與新建立的原始檔、新建立的二進位制檔案或者其他受支援的位置一起被查詢。位置 CLASS_OUTPUT 和 SOURCE_OUTPUT 必須受支援。資源可以是相對於某個包（該包是原始檔和類檔案）指定的，並透過相對路徑名從中取出。從不太嚴格的角度說，新檔案的完全路徑名將是 location、 pkg 和 relativeName 的串聯。

對於生成Java檔案，還可以使用Square公司的開源類庫[JavaPoet](https://link.jianshu.com?t=https://github.com/square/javapoet)，感興趣的同學可以瞭解下。

### 列印錯誤資訊

Messager介面提供註解處理器用來報告錯誤訊息、警告和其他通知的方式。

> 注意：我們應該**對在處理過程中可能發生的異常進行捕獲**，透過Messager介面提供的方法通知使用者。此外，使用帶有Element引數的方法連線到出錯的元素，使用者可以直接點選錯誤資訊跳到出錯原始檔的相應行。如果你在process()中丟擲一個異常，那麼執行註解處理器的JVM將會崩潰（就像其他Java應用一樣），這樣使用者會從javac中得到一個非常難懂出錯資訊。

| 方法 | 說明 |
| --- | --- |
| void printMessage(Diagnostic.Kind kind, CharSequence msg) | 列印指定種類的訊息。 |
| void printMessage(Diagnostic.Kind kind, CharSequence msg, Element e) | 在元素的位置上列印指定種類的訊息。 |
| void printMessage(Diagnostic.Kind kind, CharSequence msg, Element e, AnnotationMirror a) | 在已註解元素的註解映象位置上列印指定種類的訊息。 |
| void printMessage(Diagnostic.Kind kind, CharSequence msg, Element e, AnnotationMirror a, AnnotationValue v) | 在已註解元素的註解映象內部註解值的位置上列印指定種類的訊息。 |

### 配置選項引數

我們可以透過getOptions()方法獲取選項引數，在gradle檔案中配置選項引數值。例如我們配置了一個名為yuweiguoCustomAnnotation的引數值。

```
android {
    defaultConfig {
        javaCompileOptions {
            annotationProcessorOptions {
                arguments = [ yuweiguoCustomAnnotation : 'io.github.yuweiguocn.customannotation.MyCustomAnnotation' ]
            }
        }
    }
}

```

在註解處理器中重寫getSupportedOptions方法指定支援的選項引數名稱。透過getOptions方法獲取選項引數值。

```
public static final String CUSTOM_ANNOTATION = "yuweiguoCustomAnnotation";

@Override
public boolean process(Set extends TypeElement> annotations, RoundEnvironment roundEnv) {
   try {
       String resultPath = processingEnv.getOptions().get(CUSTOM_ANNOTATION);
       if (resultPath == null) {
           ...
           return false;
       }
       ...
   } catch (Exception e) {
       e.printStackTrace();
       ...
   }
   return true;
}

@Override
public Set<string> getSupportedOptions() {
   Set<string> options = new LinkedHashSet<string>();
   options.add(CUSTOM_ANNOTATION);
   return options;
}

```

### 處理過程

Java官方文件給出的註解處理過程的定義：註解處理過程是一個有序的迴圈過程。在每次迴圈中，一個處理器可能被要求去處理那些在上一次迴圈中產生的原始檔和類檔案中的註解。第一次迴圈的輸入是執行此工具的初始輸入。這些初始輸入，可以看成是虛擬的第0次的迴圈的輸出。這也就是說我們實現的process方法有可能會被呼叫多次，因為我們生成的檔案也有可能會包含相應的註解。例如，我們的原始檔為SourceActivity.class，生成的檔案為Generated.class，這樣就會有三次迴圈，第一次輸入為SourceActivity.class，輸出為Generated.class；第二次輸入為Generated.class，輸出並沒有產生新檔案；第三次輸入為空，輸出為空。

每次迴圈都會呼叫process方法，process方法提供了兩個引數，第一個是我們請求處理註解型別的集合（也就是我們透過重寫getSupportedAnnotationTypes方法所指定的註解型別），第二個是有關當前和上一次 迴圈的資訊的環境。返回值表示這些註解是否由此 Processor 宣告，如果返回 true，則這些註解已宣告並且不要求後續 Processor 處理它們；如果返回 false，則這些註解未宣告並且可能要求後續 Processor 處理它們。

```
public abstract boolean process(Set extends TypeElement> annotations,
                                RoundEnvironment roundEnv)

```

### 獲取註解元素

我們可以透過RoundEnvironment介面獲取註解元素。process方法會提供一個實現RoundEnvironment介面的物件。

| 方法 | 說明 |
| --- | --- |
| Set extends Element> getElementsAnnotatedWith(Class extends Annotation> a) | 返回被指定註解型別註解的元素集合。 |
| Set extends Element> getElementsAnnotatedWith(TypeElement a) | 返回被指定註解型別註解的元素集合。 |
| processingOver() | 如果迴圈處理完成返回true，否則返回false。 |

## 示例

瞭解完了相關的基本概念，接下來我們來看一個示例，**本示例只為演示無實際意義**。主要功能為自定義一個註解，此註解只能用在public的方法上，我們透過註解處理器拿到類名和方法名儲存到List集合中，然後生成透過引數選項指定的檔案，透過此檔案可以獲取List集合。

自定義註解：

```
@Documented
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface CustomAnnotation {
}

```

註解處理器中關鍵程式碼：

```
@Override
public boolean process(Set extends TypeElement> annotations, RoundEnvironment roundEnv) {
   try {
       String resultPath = processingEnv.getOptions().get(CUSTOM_ANNOTATION);
       if (resultPath == null) {
           messager.printMessage(Diagnostic.Kind.ERROR, "No option " + CUSTOM_ANNOTATION +
                   " passed to annotation processor");
           return false;
       }

round++;
       messager.printMessage(Diagnostic.Kind.NOTE, "round " + round + " process over " + roundEnv.processingOver());
       Iterator extends TypeElement> iterator = annotations.iterator();
       while (iterator.hasNext()) {
           messager.printMessage(Diagnostic.Kind.NOTE, "name is " + iterator.next().getSimpleName().toString());
       }

if (roundEnv.processingOver()) {
           if (!annotations.isEmpty()) {
               messager.printMessage(Diagnostic.Kind.ERROR,
                       "Unexpected processing state: annotations still available after processing over");
               return false;
           }
       }

if (annotations.isEmpty()) {
           return false;
       }

for (Element element : roundEnv.getElementsAnnotatedWith(CustomAnnotation.class)) {
           if (element.getKind() != ElementKind.METHOD) {
               messager.printMessage(
                       Diagnostic.Kind.ERROR,
                       String.format("Only methods can be annotated with @%s", CustomAnnotation.class.getSimpleName()),
                       element);
               return true; // 退出處理
           }

if (!element.getModifiers().contains(Modifier.PUBLIC)) {
               messager.printMessage(Diagnostic.Kind.ERROR, "Subscriber method must be public", element);
               return true;
           }

ExecutableElement execElement = (ExecutableElement) element;
           TypeElement classElement = (TypeElement) execElement.getEnclosingElement();
           result.add(classElement.getSimpleName().toString() + "#" + execElement.getSimpleName().toString());
       }
       if (!result.isEmpty()) {
           generateFile(resultPath);
       } else {
           messager.printMessage(Diagnostic.Kind.WARNING, "No @CustomAnnotation annotations found");
       }
       result.clear();
   } catch (Exception e) {
       e.printStackTrace();
       messager.printMessage(Diagnostic.Kind.ERROR, "Unexpected error in CustomProcessor: " + e);
   }
   return true;
}

private void generateFile(String path) {
   BufferedWriter writer = null;
   try {
       JavaFileObject sourceFile = filer.createSourceFile(path);
       int period = path.lastIndexOf('.');
       String myPackage = period > 0 ? path.substring(0, period) : null;
       String clazz = path.substring(period + 1);
       writer = new BufferedWriter(sourceFile.openWriter());
       if (myPackage != null) {
           writer.write("package " + myPackage + ";\n\n");
       }
       writer.write("import java.util.ArrayList;\n");
       writer.write("import java.util.List;\n\n");
       writer.write("/** This class is generated by CustomProcessor, do not edit. */\n");
       writer.write("public class " + clazz + " {\n");
       writer.write("    private static final List<string> ANNOTATIONS;\n\n");
       writer.write("    static {\n");
       writer.write("        ANNOTATIONS = new ArrayList<>();\n\n");
       writeMethodLines(writer);
       writer.write("    }\n\n");
       writer.write("    public static List<string> getAnnotations() {\n");
       writer.write("        return ANNOTATIONS;\n");
       writer.write("    }\n\n");
       writer.write("}\n");
   } catch (IOException e) {
       throw new RuntimeException("Could not write source for " + path, e);
   } finally {
       if (writer != null) {
           try {
               writer.close();
           } catch (IOException e) {
               //Silent
           }
       }
   }
}

private void writeMethodLines(BufferedWriter writer) throws IOException {
   for (int i = 0; i < result.size(); i++) {
       writer.write("        ANNOTATIONS.add(\"" + result.get(i) + "\");\n");
   }
}

```

編譯輸出：

```
Note: round 1 process over false
Note: name is CustomAnnotation
Note: round 2 process over false
Note: round 3 process over true

```

獲取完整程式碼：[https://github.com/yuweiguocn/CustomAnnotation](https://link.jianshu.com?t=https://github.com/yuweiguocn/CustomAnnotation)

關於上傳自定義註解處理器到jcenter中，請檢視[上傳類庫到jcenter](https://link.jianshu.com?t=http://yuweiguocn.github.io/publishing-lib-to-jcenter/)。

很高興你能閱讀到這裡，此時再去看EventBus 3.0中的註解處理器的原始碼，相信你可以很輕鬆地理解它的原理。

> 注意：如果你clone了工程程式碼，你可能會發現**註解和註解處理器是單獨的module**。有一點可以肯定的是我們的註解處理器只需要在編譯的時候使用，並不需要打包到APK中。因此為了使用者考慮，我們需要將註解處理器分離為單獨的module。

## 參考

*   [https://www.race604.com/annotation-processing/](https://link.jianshu.com?t=https://www.race604.com/annotation-processing/)
*   [http://docs.oracle.com/javase/7/docs/api/javax/annotation/processing/package-summary.html](https://link.jianshu.com?t=http://docs.oracle.com/javase/7/docs/api/javax/annotation/processing/package-summary.html)
*   [http://tool.oschina.net/uploads/apidocs/jdk-zh/](https://link.jianshu.com?t=http://tool.oschina.net/uploads/apidocs/jdk-zh/)
*   [https://github.com/greenrobot/EventBus](https://link.jianshu.com?t=https://github.com/greenrobot/EventBus)
*   [http://hannesdorfmann.com/annotation-processing/annotationprocessing101](https://link.jianshu.com?t=http://hannesdorfmann.com/annotation-processing/annotationprocessing101)
*   [https://github.com/sockeqwe/annotationprocessing101](https://link.jianshu.com?t=https://github.com/sockeqwe/annotationprocessing101)

作者：於衛國
連結：https://www.jianshu.com/p/50d95fbf635c/
來源：簡書
簡書著作權歸作者所有，任何形式的轉載都請聯絡作者獲得授權並註明出處。</string></string></string></string></string></string></string></string></string></string>

@lombok註解背後的原理是什麼，讓我們走近自定義Java註解處理器

相關文章