Java注解（Annotation）

簡介

Java 注解（Annotation）又稱 Java 標(biāo)注，是 JDK5.0 引入的一種注釋機制。

Java 語言中的類怔昨、方法、變量宿稀、參數(shù)和包等都可以被標(biāo)注趁舀。和 Javadoc 不同，Java 標(biāo)注可以通過反射獲取標(biāo)注內(nèi)容原叮。在編譯器生成類文件時赫编，標(biāo)注可以被嵌入到字節(jié)碼中。Java 虛擬機可以保留標(biāo)注內(nèi)容奋隶，在運行時可以獲取到標(biāo)注內(nèi)容擂送。當(dāng)然它也支持自定義 Java 標(biāo)注。

內(nèi)置的注解

Java 定義了一套注解唯欣，共有 7 個嘹吨，3 個在 java.lang 中，剩下 4 個在 java.lang.annotation 中境氢。

作用在代碼的注解是

@Override - 檢查該方法是否是重寫方法蟀拷。如果發(fā)現(xiàn)其父類碰纬，或者是引用的接口中并沒有該方法時，會報編譯錯誤问芬。
@Deprecated - 標(biāo)記過時方法悦析。如果使用該方法，會報編譯警告此衅。
@SuppressWarnings - 指示編譯器去忽略注解中聲明的警告强戴。

作用在其他注解的注解(元注解)是:

@Retention - 用來指定 Annotation 的策略。
標(biāo)識這個注解怎么保存挡鞍，是只在代碼中骑歹，還是編入class文件中，或者是在運行時可以通過反射訪問墨微。
@Documented - 標(biāo)記這些注解是否包含在用戶文檔javadoc中道媚。

** javadoc**：是Sun公司提供的一個技術(shù)，它從程序源代碼中抽取類翘县、方法最域、成員等注釋形成一個和源代碼配套的API幫助文檔。

只要在編寫程序時以一套特定的標(biāo)簽作注釋锈麸，在程序編寫完成后羡宙，通過Javadoc就可以同時形成程序的開發(fā)文檔了。

@Target - 用來指定 Annotation 的類型
標(biāo)記這個注解應(yīng)該是哪種 Java 成員掐隐。
@Inherited - 標(biāo)記這個注解是繼承于哪個注解類
(默認注解并沒有繼承于任何子類)

從 Java 7 開始，額外添加了 3 個注解:

@SafeVarargs - Java 7 開始支持钞馁，忽略任何使用參數(shù)為泛型變量的方法或構(gòu)造函數(shù)調(diào)用產(chǎn)生的警告虑省。
@FunctionalInterface - Java 8 開始支持，標(biāo)識一個匿名函數(shù)或函數(shù)式接口僧凰。
@Repeatable - Java 8 開始支持探颈，標(biāo)識某注解可以在同一個聲明上使用多次。

Annotation架構(gòu)

1 個 Annotation 和 1 個 RetentionPolicy 關(guān)聯(lián)训措。

每1個Annotation對象伪节，都會有唯一的RetentionPolicy屬性。

1 個 Annotation 和 1~n 個 ElementType 關(guān)聯(lián)绩鸣。

對于每 1 個 Annotation 對象怀大，可以有若干個 ElementType 屬性呀闻。

Annotation 有許多實現(xiàn)類化借，包括：Deprecated, Documented, Inherited, Override 等等。

Annotation組成

java Annotation 的組成中捡多，有 3 個非常重要的主干類。

Annotation 的每一個實現(xiàn)類，都 "和 1 個 RetentionPolicy 關(guān)聯(lián)" 并且 " 和 1~n 個 ElementType 關(guān)聯(lián)"鳞溉。

Annotation.java

package java.lang.annotation;
public interface Annotation {

    boolean equals(Object obj);

    int hashCode();

    String toString();

    Class<? extends Annotation> annotationType();
}

ElementType.java

package java.lang.annotation;

public enum ElementType {
    TYPE,               /* 類、接口（包括注釋類型）或枚舉聲明  */

    FIELD,              /* 字段聲明（包括枚舉常量）  */

    METHOD,             /* 方法聲明  */

    PARAMETER,          /* 參數(shù)聲明  */

    CONSTRUCTOR,        /* 構(gòu)造方法聲明  */

    LOCAL_VARIABLE,     /* 局部變量聲明  */

    ANNOTATION_TYPE,    /* 注釋類型聲明  */

    PACKAGE             /* 包聲明  */
}

RetentionPolicy.java

package java.lang.annotation;
public enum RetentionPolicy {
    SOURCE,            /* Annotation信息僅存在于編譯器處理期間呆贿，編譯器處理完之后就沒有該Annotation信息了  */

    CLASS,             /* 編譯器將Annotation存儲于類對應(yīng)的.class文件中冒晰。默認行為  */

    RUNTIME            /* 編譯器將Annotation存儲于class文件中，并且可由JVM讀入 */
}

1. Annotation 就是個接口竟块。

"每 1 個 Annotation" 都與 "1 個 RetentionPolicy" 關(guān)聯(lián)壶运，并且與 "1～n 個 ElementType" 關(guān)聯(lián)±嗣兀可以通俗的理解為：每 1 個 Annotation 對象蒋情，都會有唯一的 RetentionPolicy 屬性；至于 ElementType 屬性耸携，則有 1~n 個棵癣。

2. ElementType 是 Enum 枚舉類型，它用來指定 Annotation 的類型夺衍。

"每 1 個 Annotation" 都與 "1～n 個 ElementType" 關(guān)聯(lián)浙巫。當(dāng) Annotation 與某個 ElementType 關(guān)聯(lián)時，就意味著：Annotation有了某種用途。例如的畴，若一個 Annotation 對象是 METHOD 類型渊抄，則該 Annotation 只能用來修飾方法。

3. RetentionPolicy 是 Enum 枚舉類型丧裁，它用來指定 Annotation 的策略护桦。通俗點說，就是不同 RetentionPolicy 類型的 Annotation 的作用域不同煎娇。

"每 1 個 Annotation" 都與 "1 個 RetentionPolicy" 關(guān)聯(lián)二庵。

SOURCE
Annotation 僅存在于編譯器處理期間，編譯器處理完之后缓呛，該 Annotation 就沒用了催享。

例如，@Override"標(biāo)志就是一個 Annotation哟绊。當(dāng)它修飾一個方法的時候因妙，就意味著該方法覆蓋父類的方法；并且在編譯期間會進行語法檢查票髓！編譯器處理完后攀涵，@Override就沒有任何作用了。

CLASS
編譯器將 Annotation 存儲于類對應(yīng)的 .class 文件中洽沟，它是 Annotation 的默認行為以故。

RUNTIME
編譯器將 Annotation 存儲于 class 文件中，并且可由JVM讀入裆操。

java 常用的 Annotation：

@Deprecated  -- @Deprecated 所標(biāo)注內(nèi)容怒详，不再被建議使用。
@Override    -- @Override 只能標(biāo)注方法踪区，表示該方法覆蓋父類中的方法棘利。
@Documented  -- @Documented 所標(biāo)注內(nèi)容，可以出現(xiàn)在javadoc中朽缴。
@Inherited   -- @Inherited只能被用來標(biāo)注“Annotation類型”，它所標(biāo)注的Annotation具有繼承性水援。
@Retention   -- @Retention只能被用來標(biāo)注“Annotation類型”密强，而且它被用來指定Annotation的RetentionPolicy屬性。
@Target      -- @Target只能被用來標(biāo)注“Annotation類型”蜗元，而且它被用來指定Annotation的ElementType屬性或渤。
@SuppressWarnings -- @SuppressWarnings 所標(biāo)注內(nèi)容產(chǎn)生的警告，編譯器會對這些警告保持靜默奕扣。

@Inherited 所標(biāo)注的Annotation將具有繼承性

@Inherited 的定義如下：

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Inherited {
}

使用示例：

import java.lang.annotation.Target;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Inherited;

/**
 * 自定義的Annotation薪鹦。
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Inherited
@interface Inheritable
{
}

@Inheritable
class InheritableFather
{
    public InheritableFather() {
        // InheritableBase是否具有 Inheritable Annotation
        System.out.println("InheritableFather:"+InheritableFather.class.isAnnotationPresent(Inheritable.class));
    }
}

/**
 * InheritableSon 類只是繼承于 InheritableFather，
 */
public class InheritableSon extends InheritableFather
{
    public InheritableSon() {
        super();    // 調(diào)用父類的構(gòu)造函數(shù)
        // InheritableSon類是否具有 Inheritable Annotation
        System.out.println("InheritableSon:"+InheritableSon.class.isAnnotationPresent(Inheritable.class));
    }
   
    public static void main(String[] args)
    {
        InheritableSon is = new InheritableSon();
    }
}

運行結(jié)果：

InheritableFather:true
InheritableSon:true

對 InheritableSon.java 進行修改：注釋掉 "Inheritable 的 @Inherited 注解"。

運行結(jié)果：

InheritableFather:true
InheritableSon:false

當(dāng)注解 Inheritable 被 @Inherited 標(biāo)注時池磁，它具有繼承性奔害。否則，沒有繼承性地熄。

注解作用

注解是一系列元數(shù)據(jù)华临，它提供數(shù)據(jù)用來解釋程序代碼，但是注解并非是所解釋的代碼本身的一部分端考。注解對于代碼的運行效果沒有直接影響雅潭。

注解有許多用處，主要如下：

**提供信息給編譯器： **編譯器可以利用注解來探測錯誤和警告信息
編譯階段時的處理： 軟件工具可以用來利用注解信息來生成代碼却特、Html文檔或者做其它相應(yīng)處理扶供。
運行時的處理： 某些注解可以在程序運行的時候接受代碼的提取
值得注意的是，注解不是代碼本身的一部分裂明。

注解主要針對的是編譯器和APT使用椿浓。

當(dāng)開發(fā)者使用了Annotation 修飾了類、方法漾岳、Field 等成員之后轰绵，這些 Annotation 不會自己生效，必須由開發(fā)者提供相應(yīng)的代碼來提取并處理 Annotation 信息尼荆。這些處理提取和處理 Annotation 的代碼統(tǒng)稱為 APT（Annotation Processing Tool)左腔。

Annotation 是一個輔助類，它在 Junit捅儒、Struts液样、Spring 等工具框架中被廣泛使用。

我們在編程中經(jīng)常會使用到的 Annotation 作用有：

1）編譯檢查

Annotation 具有"讓編譯器進行編譯檢查的作用"巧还。

例如鞭莽，@SuppressWarnings, @Deprecated 和 @Override 都具有編譯檢查作用。

2) 在反射中使用 Annotation

在反射的 Class, Method, Field 等函數(shù)中麸祷，有許多于 Annotation 相關(guān)的接口澎怒。

這也意味著，我們可以在反射中解析并使用 Annotation阶牍。

注解通過反射獲取喷面。
可以通過 Class 對象的 isAnnotationPresent() 方法判斷它是否應(yīng)用了某個注解

public boolean isAnnotationPresent(Class<? extends Annotation> annotationClass) {}

通過 getAnnotation() 或者是 getAnnotations() 方法來獲取 Annotation 對象。如果獲取到的 Annotation 如果不為 null走孽，則就可以調(diào)用它們的屬性方法了惧辈。

getAnnotation()：返回指定類型的注解
getAnnotations()：返回注解到這個元素上的所有注解

public <A extends Annotation> A getAnnotation(Class<A> annotationClass) {}
public Annotation[] getAnnotations() {}

import java.lang.annotation.Annotation;
import java.lang.annotation.Target;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Inherited;
import java.lang.reflect.Method;

/**
 * Annotation在反射函數(shù)中的使用示例
 */
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    String[] value() default "unknown";
}

/**
 * Person類。它會使用MyAnnotation注解磕瓷。
 */
class Person {
   
    /**
     * empty()方法同時被 "@Deprecated" 和 "@MyAnnotation(value={"a","b"})"所標(biāo)注
     * (01) @Deprecated盒齿，意味著empty()方法念逞，不再被建議使用
     * (02) @MyAnnotation, 意味著empty() 方法對應(yīng)的MyAnnotation的value值是默認值"unknown"
     */
    @MyAnnotation
    @Deprecated
    public void empty(){
        System.out.println("\nempty");
    }
   
    /**
     * sombody() 被 @MyAnnotation(value={"girl","boy"}) 所標(biāo)注，
     * @MyAnnotation(value={"girl","boy"}), 意味著MyAnnotation的value值是{"girl","boy"}
     */
    @MyAnnotation(value={"girl","boy"})
    public void somebody(String name, int age){
        System.out.println("\nsomebody: "+name+", "+age);
    }
}

public class AnnotationTest {

    public static void main(String[] args) throws Exception {
       
        // 新建Person
        Person person = new Person();
        // 獲取Person的Class實例
        Class<Person> c = Person.class;
        // 獲取 somebody() 方法的Method實例
        Method mSomebody = c.getMethod("somebody", new Class[]{String.class, int.class});
        // 執(zhí)行該方法
        mSomebody.invoke(person, new Object[]{"lily", 18});
        iteratorAnnotations(mSomebody);
       

        // 獲取 somebody() 方法的Method實例
        Method mEmpty = c.getMethod("empty", new Class[]{});
        // 執(zhí)行該方法
        mEmpty.invoke(person, new Object[]{});        
        iteratorAnnotations(mEmpty);
    }
   
    public static void iteratorAnnotations(Method method) {

        // 判斷 somebody() 方法是否包含MyAnnotation注解
        if(method.isAnnotationPresent(MyAnnotation.class)){
            // 獲取該方法的MyAnnotation注解實例
            MyAnnotation myAnnotation = method.getAnnotation(MyAnnotation.class);
            // 獲取 myAnnotation的值边翁，并打印出來
            String[] values = myAnnotation.value();
            for (String str:values)
                System.out.printf(str+", ");
            System.out.println();
        }
       
        // 獲取方法上的所有注解翎承，并打印出來
        Annotation[] annotations = method.getAnnotations();
        for(Annotation annotation : annotations){
            System.out.println(annotation);
        }
    }
}

運行結(jié)果：

somebody: lily, 18
girl, boy, 
@com.skywang.annotation.MyAnnotation(value=[girl, boy])

empty
unknown, 
@com.skywang.annotation.MyAnnotation(value=[unknown])
@java.lang.Deprecated()

3) 根據(jù) Annotation 生成幫助文檔

通過給 Annotation 注解加上 @Documented 標(biāo)簽，能使該 Annotation 標(biāo)簽出現(xiàn)在 javadoc 中倒彰。

4）能夠幫忙查看查看代碼

通過 @Override, @Deprecated 等审洞，我們能很方便的了解程序的大致結(jié)構(gòu)。

注解應(yīng)用實例

注解運用的地方太多了待讳，如JUnit框架芒澜、ssm框架等運用了大量的注解。

JUnit 這個是一個測試框架创淡，典型使用方法如下：

public class ExampleUnitTest {
    @Test
    public void addition_isCorrect() throws Exception {
        assertEquals(4, 2 + 2);
    }
}

總結(jié)

如果注解難于理解痴晦，你就把它類同于標(biāo)簽，標(biāo)簽為了解釋事物琳彩，注解為了解釋代碼誊酌。
注解的基本語法，創(chuàng)建如同接口露乏，但是多了個 @ 符號碧浊。
注解的元注解。
注解的屬性瘟仿。
注解主要給編譯器及工具類型的軟件用的箱锐。
注解的提取需要借助于 Java 的反射技術(shù)，反射比較慢劳较，所以注解使用時也需要謹(jǐn)慎計較時間成本驹止。

整理自
Java 注解（Annotation）
java注解-最通俗易懂的講解