摘要：注解功能編譯器可以使用注解來檢測錯(cuò)誤和取消警告使用注解可以生成特定代碼，如使用注解簡化等某些注解可以在運(yùn)行時(shí)進(jìn)行檢查和操作。

原文發(fā)于微信公眾號jzman-blog，歡迎關(guān)注交流。

Java 注解（Annotation）又稱之為 Java 標(biāo)注、元數(shù)據(jù)，是 Java 1.5 之后加入的一種特殊語法，通過注解可以標(biāo)注 Java 中的類、方法、屬性、參數(shù)、包等，可以通過反射原理對這些元數(shù)據(jù)進(jìn)行訪問，注解的使用不會影響程序的正常運(yùn)行，只會對編譯器警告等輔助工具產(chǎn)生影響。

編譯器可以使用注解來檢測錯(cuò)誤和取消警告；

使用注解可以生成特定代碼，如 ButtferKnife 使用注解簡化 findViewById等；

某些注解可以在運(yùn)行時(shí)進(jìn)行檢查和操作。

注解的定義使用 @interface 作為關(guān)鍵字，實(shí)際上表示自動(dòng)繼承了 java.lang.annotation.Annotation 接口，定義格式參考如下：

@元注解
public @interface AnnotationName{
    //配置參數(shù)（參數(shù)類型 參數(shù)名稱()）
    String name() default "hello";
}

配置參數(shù)里面的類型包括基本類型、String、class、枚舉以及相關(guān)類型的數(shù)組，可以使用 default 設(shè)置配置參數(shù)的默認(rèn)值，定義一個(gè)注解具體如下：

@Target(value = {ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface TestDefineAnnotation {
    String[] name() default "test";
}

@Override

@Deprecated

@SuppressWarnings

下面是上面三個(gè)內(nèi)置注解的聲明：

//表示當(dāng)前的方法將覆蓋超類中的方法，編譯時(shí)進(jìn)行格式檢查
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.SOURCE)
public @interface Override {
}
//表示一個(gè)類或者是方法不再建議使用，將其標(biāo)記為過時(shí)，但還是可以使用
@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE})
@Retention(RetentionPolicy.SOURCE)
public @interface SuppressWarnings {
    String[] value();
}
//表示關(guān)閉不當(dāng)?shù)木幾g器警告信息
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE})
public @interface Deprecated {
}

根據(jù)對上面三個(gè)注解的聲明來看，@SuppressWarnings 中定義了一個(gè)數(shù)組，這個(gè)數(shù)組表示在該注解上具體的目標(biāo)是那些，如可在 SuppressWarnings 上使用的值，常用的具體如下：

deprecation：使用了過時(shí)的類或方法時(shí)的警告

unused：有未使用的變量時(shí)的警告

unchecked：執(zhí)行了未檢查的轉(zhuǎn)換時(shí)的警告

fallthrough：當(dāng) switch 程序塊直接通往下一種情況而沒有 break 時(shí)的警告

path：在類路徑、源文件路徑等中有不存在的路徑時(shí)的警告

serial：當(dāng)在可序列化的類上缺少serialVersionUID 定義時(shí)的警告

finally ：任何 finally 子句不能正常完成時(shí)的警告

all：關(guān)于以上所有情況的警告

下面看一個(gè)案例，具體如下：

public void test() {
    long date = Date.parse("2018-04-22");
}

上面的代碼如果使用 eclipse 等其他 IDE 時(shí)會出現(xiàn)兩個(gè)警告，一是使用了過時(shí)的 API，二是變量 date 賦值后沒有被使用過，警告截圖如下：

當(dāng)然， IDE 會提示是否添加 SuppressWarnings 來取消這些警告，前文中可以看到注解 @SuppressWarnings 的聲明中需要配置參數(shù)，這個(gè)參數(shù)是一個(gè)數(shù)組,數(shù)組名稱是 value，可以省略這個(gè)名稱， 具體如下：

//不省略
public void test2() {
    @SuppressWarnings(value= {"deprecation", "unused"})
    long date = Date.parse("2018-04-22");
}
//省略
public void test2() {
    @SuppressWarnings({"deprecation", "unused"})
    long date = Date.parse("2018-04-22");
}

來張截圖說明一下使用 @SuppressWarnings 的效果，具體如下:

如果只想取消一種警告可以這樣寫，具體如下：

//第一種
public void test2() {
    @SuppressWarnings(value = {"deprecation"})
    long date = Date.parse("2018-04-22");
    System.out.println(date);
}
//第二種
public void test2() {
    @SuppressWarnings({"deprecation"})
    long date = Date.parse("2018-04-22");
    System.out.println(date);
}

注意：如果在定義注解的配置參數(shù)名稱為 value，那么可以在配置注解時(shí)可以省略 value，反之，使用其他名稱，則必須采用第一種方式，要指定配置參數(shù)名稱。

當(dāng)然其他注解和 @SuppressWarnings 也比較類似， @Override、@Deprecated 由它們的聲明可知直接使用即可，不需要指定具體目標(biāo)，在其聲明注解時(shí)用到了 @Documented、@Retention、@Target 等，這些用來注解其他注解的特殊注解稱之為元注解，具體請看下文。

@Target

@Retention

@Documented

@Inherited

@Target

@Target 用來描述注解的使用范圍，它的聲明如下：

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Target {
    ElementType[] value();
}

由 @Target 聲明可知使用 @Target 注解必須指定具體的 Java 成員，也就是該注解要使用到哪個(gè)位置，具體由枚舉 ElementType 中定義，具體如下：

public enum ElementType {
    TYPE,           //類、接口、注解、枚舉
    FIELD,          //屬性（包括枚舉常量） 
    METHOD,         //方法
    PARAMETER,      //參數(shù) 
    CONSTRUCTOR,    //構(gòu)造方法
    LOCAL_VARIABLE, //局部變量
    ANNOTATION_TYPE,//注解
    PACKAGE,        //包

    /**
     * 類型注解
     * @since 1.8
     */
    TYPE_PARAMETER,
    TYPE_USE
}

@Retention

@Retention 表示在什么級別保存該注解的信息，它的聲明如下：

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Retention {
    /**
     * Returns the retention policy.
     * @return the retention policy
     */
    RetentionPolicy value();
}

由 @Retention 的聲明可知，使用 @Retention 時(shí)，必須指定保存celue（RetentionPolicy），具體值如下：

public enum RetentionPolicy {
    SOURCE,  //在編譯時(shí)會被丟棄，僅僅在源碼中存在
    CLASS,   //默認(rèn)策略，運(yùn)行時(shí)就會被丟棄，僅僅在 class 文件中
    RUNTIME  //編譯時(shí)會將注解信息記錄到class文件，運(yùn)行時(shí)任然保留，可以通過反射獲取注解信息
}

@Documented 和 @Inherited 都沒有配置參數(shù)，是一種標(biāo)記注解，@Documented 表示將該注解顯示到用戶文檔中，@Inherited 表示該注解只有使用在類上才會有效，而且該注解會被子類繼承。

在對元注解的說明中可知從 Java8 開始新增了類型注解，如果在注解 @Target 使用這種注解，表明該注解可以在對應(yīng)的任何地方使用，如在 @Target 中指定 TYPE_PARAMETER 就可在自定義類型的聲明處使用該注解，如在 @Target 中指定 TYPE_USE 就可在任何類型前添加該類之間，主要是方便 Java 開發(fā)者使用類型注解和相關(guān)插件（Checker Framework）來檢查來在編譯期檢查運(yùn)行時(shí)的異常。

下面分別定義指定 TYPE_PARAMETER 和 TYPE_USE 的注解，具體如下：

//1. TYPE_PARAMETER
@Target(value = {ElementType.TYPE_PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
public @interface TypeParameterAnnotation {
    String value();
}
//2. TYPE_USE
@Target(value = ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
public @interface TypeUseAnnotation {
}

然后，在下面的案例中使用這兩個(gè)注解，具體如下：

/**
 * 測試注解
 * @author jzman
 */
public class TestAnnotation {

    //...
    
    /**
     * ElementType.TYPE_PARAMETER
     * 使用在自定義類型聲明的時(shí)候，如注解@TypeParameterAnnotation
     * @param 
     */
    static class TypeAnnotationA<@TypeParameterAnnotation(value="hello") T>{
        /**
         * ElementType.TYPE_USE
         * 可以使用在任意類型前面（包含TYPE_PARAMETER）
         */
        //創(chuàng)建實(shí)例
        MyType myType = new @TypeUseAnnotation MyType();
        //對象類型
        Object obj = (@TypeUseAnnotation Object) myType;
        //泛型
        ArrayList<@TypeUseAnnotation T> list = new ArrayList<>();
        //參數(shù)中的類型
        public String testA(@TypeUseAnnotation String test) {
            return "Hello"+test;
        }
        //枚舉
        public void testB(@TypeUseAnnotation Color color) {
            //...
        }
        
        enum Color{
            RED, GREEN, BLUE
        }
    }
    
    static class MyType{}    
}

其實(shí)注解的語法比較簡單，僅僅定義注解對實(shí)際開發(fā)是沒有幫助的，覺得注解只有在運(yùn)行時(shí)通過反射獲取注解信息才是最重要的，注解與反射相關(guān)的內(nèi)容會在以后的推文中學(xué)習(xí)，到此對注解的認(rèn)識就結(jié)束了。

可以選擇關(guān)注微信公眾號：jzman-blog 獲取最新更新，一起交流學(xué)習(xí)!