原文作者：deors
原文地址：https://deors.wordpress.com/2011/09/26/annotation-types/
譯文作者：Jianan - [email protected]
版本資訊：本文基於2015-10-09版本進行翻譯
版權宣告：經原作者許可進行翻譯，保留所有權利，未經允許不得複製和轉載。

從本文開始，我將開始寫一系列關於Java語言使用註解處理器生成程式碼的文章，包括這種方法的強大之處。最後還會描述如何確保在編譯的時候使用這種方法生成原始碼。

在這系列文章中，我們將會：

• 介紹Java語言的註解。
• 瞭解註解的常用方式以及使用範圍。
• 瞭解註解處理器以及它們所代表的角色。
• 學習如何建立註解處理器。
• 學習如何在終端命令列、Eclipse和Maven中執行註解處理器。
• 學習如何使用註解處理器生成原始碼。
• 學習如何使用像Apache Velocity這樣的外部模板引擎來使用註解處理器生成原始碼。

序

Java的註解從第三版的Java語言規範(1)中開始引入，並在Java 5中開始支援。

通過註解，我們可以為原始碼新增元資料資訊，包括編譯或部署資訊、配置屬性、編譯行為或者程式碼質量檢查。

與Javadoc不同，註解屬於強型別，用到的註解在類路徑下都能找到對應的註解型別定義。因此，定義的註解可以在執行時訪問到，而Javadoc是不可能的。

註解語法

註解通常出現在被註解的程式碼段前面，通常情況下都是獨立成行並且與程式碼段同樣縮排。

註解可以新增到package（包）、types（型別，包括類、介面、列舉和其它註解型別）、variable（變數、包括class、類例項、區域性變數——包括定義在for或者while迴圈裡面的區域性變數）、constructions（構造方法）、methods（方法）和parameters（引數）。

最簡單的註解結構就是內部什麼元素都沒有，例如：

@Override()
public void theMethod() {…}

在這個例子中，括號可以省略（因為沒有引數）：

@Override
 

public void theMethod() {…}

註解也可以包含元素，這些元素是通過逗號分隔的鍵值對。允許使用的值型別包括java原生資料型別、String型別、列舉型別，以及這些型別的陣列形式：

@Author(name = "Albert",
        created = "17/09/2010",
        revision = 3,
        reviewers = {"George", "Fred"})
public class SimpleAnnotationsTest {…}

當註解內部只有一個元素，並且這個元素名為value的時候，元素名可以省略：

@WorkProduct("WP00000182")
@Complexity(ComplexityLevel.VERY_SIMPLE)
public class SimpleAnnotationsTest {…}

註解可以為內部一些元素或者全部元素都設定預設值。在使用這類註解的時候，具備預設值的元素可以省略。

例如，假設有個註解為Author，它為內部元素revision（預設為1）以及reviewers（預設為空String陣列）設定了預設值，下面使用這個註解的兩種方式是等效的：

@Author(name = "Albert",
        created = "17/09/2010",
        revision = 1,
        reviewers = {})
public class SimpleAnnotationsTest() {…}
@Author(name = "Albert",        // defaults are revision 1
        created = "17/09/2010") // and no reviewers
public class SimpleAnnotationsTest() {…}

註解的典型使用

Java語言規範中定義了三種註解型別——它們都用於Java編譯器：

• @Deprecated： 用來宣告被註解的元素不應該再使用。每當這個註解被使用的時候，編譯器就會生成一個警告。它應該與Javadoc的@deprecated一起使用，在Javadoc中解釋捨棄被註解元素的原因。

• @Override： 用來宣告被註解的元素重寫了父類中宣告的元素。如果被註解的元素沒有在父類中找到對應的被重寫的元素，編譯器就會生成一個警告。儘管這個註解沒有要求一定要使用，但是它對於錯誤判斷非常有用——例如，如果在建立父類之後，有人又修改了父類方法的簽名，那麼我們在重新編譯原始碼的時候就能馬上得到提醒。

• @SuppressWarnings： 讓編譯器抑制指定的警告型別，否則被註解的元素就會觸發這類警告——例如，為了避免使用了被捨棄的API或者與舊程式碼（例如Java 5之前的版本）進行了未檢查的互動而產生過多的編譯器“干擾”。

自從引入這些註解後，很多庫和框架都將註解整合到它們新的發行版本中。通過在原始碼中使用註解，這些庫和框架都簡化甚至移除了所需要的配置檔案。

下面是一些成功使用註解的例子：

• Java企業版和它的主要模組——企業級JavaBeans、Java持久化API或者Web Service API。
• Spring框架——用於核心模組中的配置、依賴註解和控制反轉中，以及其它一些Spring專案。
• Sean、Weld、Guice.
• Apache Struts 2.

註解型別

在Java語言中註解型別是一種特殊的介面，用來自定義註解。

註解的定義要使用@interface關鍵字來代替interface：

public @interface Author {
    String name();
    String created();
    int revision() default 1;
    String[] reviewers() default {};
}
public @interface Complexity {
    ComplexityLevel value() default ComplexityLevel.MEDIUM;
}
public enum ComplexityLevel {
    VERY_SIMPLE, SIMPLE, MEDIUM, COMPLEX, VERY_COMPLEX;
}

註解型別與普通的介面有一些區別：

• 只允許原生資料型別、String、列舉、class，以及這些型別的陣列。注意註解型別中不允許常用的物件，也不允許陣列的陣列（因為每一個數組都是一個物件）。

• 註解元素的定義與定義方法的語法很類似，但是不允許有修飾符和引數。

• 註解元素的預設值定義需要使用default關鍵字，後面連線字面量、初始化陣列或者列舉值。

正如其它的類或者介面，列舉型別也可以巢狀在註解型別的內部：

public @interface Complexity {
    public enum Level {
        VERY_SIMPLE, SIMPLE, MEDIUM, COMPLEX, VERY_COMPLEX;
    }
    …
}

用於定義註解的註解

JDK自帶了一些註解，用於修改我們自定義的註解的預設行為。

• @Documented： 宣告被@Documented註解後的註解型別，一旦使用，被註解的元素就應該連同註解都記錄到Javadoc中。

• @Inherited： 宣告被註解的註解型別能夠繼承到它的子類上。通過這種方法，如果當前子類沒有受@Inherited註解的註解型別註解過，但是它的父類有，那麼當前子類也能通過繼承得到這個註解型別。不過它只適用於類繼承，不適用於介面實現。

• @Retention： 宣告被註解的註解型別生命週期。可選的值都包含在RetentionPolicy列舉中：CLASS（預設值——能被包含到class檔案中，但是在執行時訪問不到），SOURCE（建立class檔案的時候會被編譯器丟棄），RUNTIME（能夠在執行過程中訪問到）。

• @Target： 宣告註解型別能夠註解的元素型別。可選的值包含在ElementType列舉中：ANNOTATION_TYPE（用於註解型別），CONSTRUCTOR（用於構造方法），FIELE（用於成員變數），LOCAL_VARIABLE（用於區域性變數），METHOD（用於方法），PACKAGE（用於包），PARAMETER（用於方法引數），TYPE（用於類、介面、列舉）。

本系列將會在第二部分中繼續講解：註解處理器。請閱讀這裡.