Java 注解

一、概念和基本注解

從JDK1.5開始，引入了源代碼中的注解這一機制。注解使得 Java 源代碼中不但可以包含功能性的實作代碼，還可以包含中繼資料。

那麼什麼是中繼資料呢？所謂中繼資料，就是描述資料的資料。比如說一張圖檔，圖檔内容是它的主體資料，那麼像圖檔的建立時間、修改時間、建立者等等這些資料，就是這張圖檔的中繼資料。

那麼中繼資料有什麼用呢？我們可以用中繼資料來建立文檔、跟蹤代碼的依賴性和執行編譯時的格式檢查，并可以代替系統中原有的配置檔案。

Java 注解是 Java 代碼裡的特殊标記，為我們在代碼中添加用 Java 程式無法表達的額外資訊提供了一種格式化方法，使我們可以在編譯、類加載、運作時使用這些被注解修飾的程式元素（這些程式元素包括：類、屬性、方法等）。

使用注解時要在其前面加上一個 “@” 符号，表明後面的内容為注解。

在 Java 的 java.lang 包中，預定義了三個注解，它們分别是限定重寫父類方法的@Override、标記已過時的@Deprecated和抑制編譯器警告的@SuppressWarnings，通常稱這三個注解為内建注解或基本注解。

@Override 在我們程式設計過程中經常遇到，就不細講了；@Deprecated 表示該類成員已經過時，在未來的版本中可能會被删除，不建議使用。@SuppressWarnings 和前兩個注解有些不同，這個注解帶有一個屬性，表示要抑制什麼樣的警告資訊，相關屬性值的含義如下：

@SuppressWarnings(value = "deprecation") //使用了過時的程式元素
@SuppressWarnings(value = "unchecked") //執行了未檢查的轉換
@SuppressWarnings(value = "unused") //有程式元素未被使用
@SuppressWarnings(value = "fallthrough") //switch 程式塊直接通往下一種情況，而沒有break
@SuppressWarnings(value = "path") //在類路徑中有不存在的路徑
@SuppressWarnings(value = "serial") //在可序列化的類上缺少 serialVersionUID 定義
@SuppressWarnings(value = "finally") //任何 finally 子句不能正常完成
@SuppressWarnings(value = "all") //所有情況

二、自定義注解

注解之是以強大，能被衆多架構所使用的主要原因在于，它可以允許程式員自定義注解，使 Java 程式變成自描述的。注解的文法形式和接口差不多，隻不過在 interface 前面多了一個 @ 符号。

我們可以在自定義注解時定義屬性，在注解類型的定義中以無參方法的形式來聲明，其方法名和傳回值分别定義了該屬性的名字和類型。另外需要注意的是，使用帶屬性的注解時，需要給屬性指派，不過可以在定義注解時，給屬性賦預設值。

Java中注解成員的類型必須是如下幾類:

1. 基本資料類型(boolean, byte, char, short, int, long, float, double);

2. String；

3. Class；

4. 枚舉；

5. 其他的注解；

6. 以上類型的數組；

public @interface MyAnnotation {
      String name() default "張三";
      int age() default 22;
}

三、元注解

上面提到了中繼資料——描述資料的資料。還有一個元注解的概念，即描述注解的注解——使用不同注解對注解進行注解。Java 為注解單獨提供了四種元注解，即@Target、@Retention、@Documented和@Inherited。下面将分别介紹這四種元注解。

1、@Target

使用 @Target 注解的目的是用于指定被修飾的注解能用于修飾哪些程式元素。如果注解定義中不存在 @Target 元注解，則此注解可以用于任意程式元素上，如果存在這樣的元注解，則編譯器強制實施指定的使用規則。

/**
 * ElementType.ANNOTATION_TYPE : 限制此注解用于注解類
 * ElementType.CONSTRUCTOR : 限制此注解用于構造方法
 * ElementType.FIELD : 限制此注解用于字段屬性（包括枚舉變量）
 * ElementType.LOCAL_VARIABLE : 限制此注解用于局部變量聲明
 * ElementType.METHOD : 限制此注解用于方法聲明
 * ElementType.PACKAGE : 限制此注解用于包聲明
 * ElementType.PARAMETER : 限制此注解用于參數聲明
 * ElementType.TYPE : 限制此注解用于類、接口（包括注解類型）或枚舉聲明
 */
@Target({ElementType.ANNOTATION_TYPE, ElementType.CONSTRUCTOR, ElementType.FIELD, ElementType.LOCAL_VARIABLE,
        ElementType.METHOD, ElementType.PACKAGE, ElementType.PARAMETER, ElementType.TYPE})
public @interface MyAnnotation {

}

Java 8 新增加了兩個注解的程式元素類型 ElementType.TYPE_USE 和 ElementType.TYPE_PARAMETER。現在我們幾乎可以在所有的地方：局部變量、泛型、超類和接口實作、甚至是方法的Exception聲明：

public class Annotations {
    @Retention( RetentionPolicy.RUNTIME )
    @Target( { ElementType.TYPE_USE, ElementType.TYPE_PARAMETER } )
    public @interface NonEmpty {
    }

    public static class Holder< @NonEmpty T > extends @NonEmpty Object {
        public void method() throws @NonEmpty Exception {
        }
    }
public static void main(String[] args) {
        final Holder< String > holder = new @NonEmpty Holder< String >();
        @NonEmpty Collection< @NonEmpty String > strings = new ArrayList<>();
    }
}

2、@Retention

@Retention 用于指定被修飾的注解的生命周期，生命周期分為三種，分别是 RetentionPolicy.CLASS、RetentionPolicy.RUNTIME 和 RetentionPolicy.SOURCE。如果注解定義中不存在 @Retention 元注解，則生命周期預設為 RetentionPolicy.CLASS。

/**
 * RetentionPolicy.CLASS : 編譯器将把注解記錄在 class 檔案中，當運作 Java 程式時，虛拟機不再保留注解。
 * RetentionPolicy.RUNTIME : 編譯器将把注解記錄在 class 檔案中，當運作 Java 程式時，虛拟機保留注解，程式可以通過反射獲得該注解。
 * RetentionPolicy.SOURCE : 編譯器将直接丢棄被修飾的注解
 */
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotation {
      String name() default "張三";
      int age() default 22;
}

Java 注解

public class TestMyAnnotation {

    public static void main(String[] args) throws NoSuchMethodException, ClassNotFoundException {
        TestMyAnnotation testMyAnnotation = new TestMyAnnotation();
        testMyAnnotation.getObjectInfo();
    }

    @MyAnnotation
    @Deprecated
    public void getObjectInfo() throws ClassNotFoundException, NoSuchMethodException {
        Annotation[] annotations = Class.forName("annotation.TestMyAnnotation").getMethod("getObjectInfo").getAnnotations();
        for (Annotation annotation : annotations) {
            System.out.println("該注解是" + annotation);
            if (annotation instanceof MyAnnotation) {
                MyAnnotation myAnnotation = (MyAnnotation) annotation;
                System.out.println(myAnnotation.name());
                System.out.println(myAnnotation.age());
            }
        }
    }
    
}

TestMyAnnotation.java

3、@Documented

在預設的情況下，使用 javadoc 工具自動生成文檔時，注解将被忽略掉。如果想在文檔中也包含注解，必須使用 @Documented 注解。

@Documented
public @interface MyAnnotation {
}

4、@Inherited

預設情況下，父類的注解不被子類繼承，如果要想繼承父類注解，就必須使用 @Inherited 注解。

@Inherited
public @interface MyAnnotation {
}

四、總結

其實，Java 注解可以簡單了解成一種标記符号、描述資訊。強大的并不是注解本身，而是對注解的靈活使用。以 Spring 常見的 @Component 注解為例。Spring 在啟動時，上下文利用反射找到包路徑下帶有 @Component 的類，然後把它裝載成 Spring 的 Bean。