*本篇文章已授權微信公眾號 guolin_blog （郭霖）獨家釋出

什麼是註解

        Annotation（註解）就是Java提供了一種元程式中的元素關聯任何資訊和著任何元資料（metadata）的途徑和方法。Annotion(註解)是一個介面，程式可以通過反射來獲取指定程式元素的Annotion物件，然後通過Annotion物件來獲取註解裡面的元資料。

        Annotation(註解)是JDK5.0及以後版本引入的。它可以用於建立文件，跟蹤程式碼中的依賴性，甚至執行基本編譯時檢查。從某些方面看，annotation就像修飾符一樣被使用，並應用於包、類 型、構造方法、方法、成員變數、引數、本地變數的宣告中。這些資訊被儲存在Annotation的“name=value”結構對中。

什麼是metadata元資料

元資料從metadata一詞譯來，就是“關於資料的資料”的意思。

元資料的功能作用有很多，比如：你可能用過Javadoc的註釋自動生成文件。這就是元資料功能的一種。總的來說，元資料可以用來建立文件，跟蹤程式碼的依賴性，執行編譯時格式檢查，代替已有的配置檔案。如果要對於元資料的作用進行分類，目前還沒有明確的定義，不過我們可以根據它所起的作用，大致可分為三類： 
　　 1. 編寫文件：通過程式碼裡標識的元資料生成文件
　　 2. 程式碼分析：通過程式碼裡標識的元資料對程式碼進行分析
　　 3. 編譯檢查：通過程式碼裡標識的元資料讓編譯器能實現基本的編譯檢查

Annotation和Annotation型別

Annotation使用了在java5.0所帶來的新語法，它的行為十分類似public、final這樣的修飾符。每個Annotation具有一個名字和成員個數>=0。每個Annotation的成員具有被稱為name=value對的名字和值（就像javabean一樣），name=value裝載了Annotation的資訊。

Annotation型別定義了Annotation的名字、型別、成員預設值。一個Annotation型別可以說是一個特殊的java介面，它的成員變數是受限制的，而宣告Annotation型別時需要使用新語法。當我們通過java反射api訪問Annotation時，返回值將是一個實現了該 annotation型別介面的物件，通過訪問這個物件我們能方便的訪問到其Annotation成員。後面的章節將提到在java5.0的 java.lang包裡包含的3個標準Annotation型別。

註解的分類

根據註解的引數個數分類：

        1.標記註解，一個沒有成員的Annotation型別被稱為標記註解，這種型別僅僅使用自身的存在與否來為我們提供資訊，比如常見的@Override

        2.單值註解

        3.完整註解

        根據註解使用的方法和用途分類：

        1.JDK內建系統註解

        2.元註解

        3.自定義註解

元註解

元註解的作用就是負責註解其他註解，java 5.0定義了4個meta-annotation型別，用來提供對愛他的annotation型別做說明。

 java.lang.annotation

[email protected]

 [email protected]

 [email protected]

 [email protected]

 @Target

修飾的物件範圍：packages、types（類、介面、列舉、Annotation型別）、型別成員（方法、構造方法、成員變數、列舉值）、方法引數和本地變數（如迴圈變數、catch引數）。

作用：用於描述註解的使用範圍。

ElementType取值：

   1.CONSTRUCTOR:用於描述構造器

                2.FIELD:用於描述域

                3.LOCAL_VARIABLE:用於描述區域性變數

                4.METHOD:用於描述方法

                5.PACKAGE:用於描述包

                6.PARAMETER:用於描述引數

                7.TYPE:用於描述類、介面(包括註解型別) 或enum宣告

                例如：

Name可以註解類的成員變數

@Target(ElementType.FIELD)
@Documented
public @interface Name {
    String value() default "";
}

Person可以註解類、介面（包括註解型別）、或者enum宣告

@Target(ElementType.TYPE)
public @interface Person {
    String value() default "";
}

 @Retention

定義了該Annotation被保留的時間長短：某些Annotation僅出現在原始碼中，而被編譯器丟棄；而另一些卻被編譯在class檔案中；編譯在class檔案中的Annotation可能會被虛擬機器忽略，而另一些在class被裝載時將被讀取（請注意並不影響class的執行，因為Annotation與class在使用上是被分離的）。使用這個meta-Annotation可以對 Annotation的“生命週期”限制。

作用：表示需要在什麼級別儲存該註釋資訊，用於描述註解的生命週期（即：被描述的註解在什麼範圍內有效）

RetentionPoicy取值

1.SOURCE:在原始檔中有效（即原始檔保留）

 2.CLASS:在class檔案中有效（即class保留）

 3.RUNTIME:在執行時有效（即執行時保留）

                例如：

Name註解的RetentionPolicy的值為RUNTIME，這樣註解處理器可以通過反射，獲取到該註解的屬性，從而做一些執行時的邏輯處理。

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Name {
    String value() default "";
}

@Document

        用於描述其它型別的annotation應該被作為被標註的程式成員的公共API，因此可以被例如javadoc此類的工具文件化。Documented是一個標記註解，沒有成員。

作用：表示需要在什麼級別儲存該註釋資訊，用於描述註解的生命週期（即：被描述的註解在什麼範圍內有效）。

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Name {
    String value() default "";
}

 @Inhrited

是一個標記註解，@Inherited闡述了某個被標註的型別是被繼承的。如果一個使用了@Inherited修飾的annotation型別被用於一個class，則這個annotation將被用於該class的子類。

@Inherited annotation型別是被標註過的class的子類所繼承。類並不從它所實現的介面繼承annotation，方法並不從它所過載的方法繼承annotation

當@Inherited annotation型別標註的annotation的Retention是RetentionPolicy.RUNTIME，則反射API增強了這種繼承性。如果我們使用java.lang.reflect去查詢一個@Inherited annotation型別的annotation時，反射程式碼檢查將展開工作：檢查class和其父類，直到發現指定的annotation型別被發現，或者到達類繼承結構的頂層。

自定義註解

使用@interface自定義註解時，自動繼承了java.lang.annotation.Annotation介面，由編譯程式自動完成其他細節。在定義註解時，不能繼承其他的註解或介面。@interface用來宣告一個註解，其中的每一個方法實際上是聲明瞭一個配置引數。方法的名稱就是引數的名稱，返回值型別就是引數的型別（返回值型別只能是基本型別、Class、String、enum）。可以通過default來宣告引數的預設值。

自定義註解格式：

        public @interface 註解名{註解體}

                1.所有基本資料型別（int,float,boolean,byte,double,char,long,short)

                2.String型別

                3.Class型別

                4.enum型別

                5.Annotation型別

                6.以上所有型別的陣列

        Annotation型別裡面的引數該怎麼設定:

                第一,只能用public或預設(default)這兩個訪問權修飾.例如,String value();這裡把方法設為defaul預設型別；　 　
                第二,引數成員只能用基本型別byte,short,char,int,long,float,double,boolean八種基本資料型別和 String,Enum,Class,annotations等資料型別,以及這一些型別的陣列.例如,String value();這裡的引數成員就為String;　　
                第三,如果只有一個引數成員,最好把引數名稱設為"value",後加小括號.例:下面的例子Name註解就只有一個引數成員。 

                例如：

Name姓名註解：

/**
 * Created by mingwei on 12/2/16.
 * <p/>
 * 姓名註解
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Name {
    String value() default "";
}

Gander性別註解：

/**
 * Created by mingwei on 12/2/16.
 * 性別註解
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Gender {

    public enum GenderType {
        
        Male("男"),
        Female("女"),
        Other("中性");

        private String genderStr;

        private GenderType(String arg0) {
            this.genderStr = arg0;
        }

        @Override
        public String toString() {
            return genderStr;
        }
    }

    GenderType gender() default GenderType.Male;

}

Profile個人資料註解：

/**
 * Created by mingwei on 12/2/16.
 * 基本資料註解
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Profile {
    /**
     * ID
     *
     * @return
     */
    public int id() default -1;

    /**
     * 身高
     *
     * @return
     */
    public int height() default 0;

    /**
     * 籍貫
     *
     * @return
     */
    public String nativePlace() default "";
}

註解元素的預設值

註解元素必須有確定的值，要麼在定義註解的預設值中指定，要麼在使用註解時指定，非基本型別的註解元素的值不可為null。因此, 使用空字串或0作為預設值是一種常用的做法。這個約束使得處理器很難表現一個元素的存在或缺失的狀態，因為每個註解的宣告中，所有元素都存在，並且都具有相應的值，為了繞開這個約束，我們只能定義一些特殊的值，例如空字串或者負數，一次表示某個元素不存在，在定義註解時，這已經成為一個習慣用法。

註解處理器類庫(java.lang.reflect.AnnotatedElement)

註解元素Java使用Annotation介面來代表程式元素前面的註解，該介面是所有Annotation型別的父介面。除此之外，Java在java.lang.reflect 包下新增了AnnotatedElement介面，該介面代表程式中可以接受註解的程式元素，該介面主要有如下幾個實現類：

Class：類定義

Constructor：構造器定義

Field：累的成員變數定義

Method：類的方法定義

Package：類的包定義

當一個Annotation被定義為執行時Annotation後，改註解才是執行時可見的，當class檔案被裝載時被儲存在class檔案中的Annotation才會被虛擬姐讀取。 AnnotatedElement   

介面提供了以下四個方法來訪問Annotation的資訊：

方法1：<T extends Annotation> T getAnnotation(Class<T> annotationClass): 返回改程式元素上存在的、指定型別的註解，如果該型別註解不存在，則返回null。

方法2：Annotation[] getAnnotations():返回該程式元素上存在的所有註解。

方法3：boolean is AnnotationPresent(Class<?extends Annotation> annotationClass):判斷該程式元素上是否包含指定型別的註解，存在則返回true，否則返回false.

方法4：Annotation[] getDeclaredAnnotations()：返回直接存在於此元素上的所有註釋。與此介面中的其他方法不同，該方法將忽略繼承的註釋。（如果沒有註釋直接存在於此元素上，則返回長度為零的一個數組。）該方法的呼叫者可以隨意修改返回的陣列；這不會對其他呼叫者返回的陣列產生任何影響。

我們為前面定義好的自定義註解寫一個簡單的處理器：

/**
 * Created by mingwei on 12/2/16.
 */
public class CustomUtils {

    public static void getInfo(Class<?> clazz) {
        String name = "";
        String gender = "";
        String profile = "";
        Field fields[] = clazz.getDeclaredFields();
        for (Field field : fields) {
            if (field.isAnnotationPresent(Name.class)) {
                Name arg0 = field.getAnnotation(Name.class);
                name = name + arg0.value();
                Log.i("Gmw", "name=" + name);
            }
            if (field.isAnnotationPresent(Gender.class)) {
                Gender arg0 = field.getAnnotation(Gender.class);
                gender = gender + arg0.gender().toString();
                Log.i("Gmw", "gender=" + gender);
            }
            if (field.isAnnotationPresent(Profile.class)) {
                Profile arg0 = field.getAnnotation(Profile.class);
                profile = "[id=" + arg0.id() + ",height=" + arg0.height() + ",nativePlace=" + arg0.nativePlace() + "]";
                Log.i("Gmw", "profile=" + profile);
            }
        }
    }

}

使用自定義註解：

/**
 * Created by mingwei on 12/2/16.
 */
public class Person {

    @Name("阿特羅伯斯")
    private String name;

    @Gender(gender = Gender.GenderType.Male)
    private String gender;

    @Profile(id = 1001, height = 180, nativePlace = "CN")
    private String profile;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getGender() {
        return gender;
    }

    public void setGender(String gender) {
        this.gender = gender;
    }

    public String getProfile() {
        return profile;
    }

    public void setProfile(String profile) {
        this.profile = profile;
    }
}

執行：

CustomUtils.getInfo(Person.class);

輸出：

I/Gmw: gender=男
I/Gmw: name=阿特羅伯斯
I/Gmw: profile=[id=1001,height=180,nativePlace=CN]

－－－－－－－－－－分割線－－－－－－－－－－－

參考連結：

http://www.cnblogs.com/peida/archive/2013/04/24/3036689.html

https://www.zhihu.com/question/24401191

http://www.open-open.com/lib/view/open1423558996951.html