【轉載】原來 java 註解只是個標記，沒什麼本領，一文精通，值得收藏！

title: 【轉載】原來 java 註解只是個標記，沒什麼本領，一文精通，值得收藏！
date: 2021-08-16 09:18:01
comment: false
toc: true
category:

Java
tags:
轉載
Java
註解
標記
本領
收藏
精通

前言#

java 裡有個神奇的存在，註解，就是那個天天 @別人的家伙，它到底是何方神聖啊？#

什麼是註解#

從 JDK5 開始，Java 增加對元數據的支持，也就是註解，註解與註釋是有一定區別的，可以把註解理解為代碼裡的特殊標記，這些標記可以在編譯，類加載，運行時被讀取，並執行相應的處理。通過註解開發人員可以在不改變原有代碼和邏輯的情況下在源代碼中嵌入補充信息。

內置的註解#

二當家的發現在 IDE 中如果創建一個類並實現一個接口之後，那些實現接口的方法上面會自動幫我添加 @Override 的標記。

而這個標記就是註解，像 @Override 這樣 JDK 內置的註解還有好幾個呢，他們都在 java.lang 包下面，我們分別看看。

@Override#

當子類重寫父類方法時，子類可以加上這個註解，那這有什麼用？這可以確保子類確實重寫了父類的方法，避免出現低級錯誤。

開始不知道有什麼用，直到有一天，我把接口裡的這個方法刪除了，結果就編譯不通過了。

下面是直接在命令行編譯的結果。這回我知道這個標記的作用了，它可以告訴編譯器和閱讀源碼的人這個方法是覆蓋或實現超類型的方法。

@Deprecated#

這個註解用於表示某個程序元素類，方法等已過時，當其他程序使用已過時的類，方法時編譯器會給出警告（刪除線，這個見了不少了吧）。

@SuppressWarnings#

抑制警告。

package com.secondgod.annotation;

import java.util.ArrayList;
import java.util.List;

public class Test {

    public static void main(String[] args) {
        List<Integer> intList = new ArrayList<>();
        List          objList = intList;
        objList.add("二當家的");
    }
}

在命令行啟用建議警告的編譯 (命令形如 javac -d . -Xlint Test.java , 下文再提到啟用建議警告的編譯，不再贅述解釋)。

代碼稍作修改，則可以消除編譯警告。

package com.secondgod.annotation;

import java.util.ArrayList;
import java.util.List;

public class Test {

    @SuppressWarnings({"unchecked", "rawtypes"})
    public static void main(String[] args) {
        List<Integer> intList = new ArrayList<>();
        List          objList = intList;
        objList.add("二當家的");
    }
}

@SafeVarargs#

在聲明具有模糊類型（比如：泛型）的可變參數的構造函數或方法時，Java 編譯器會報 unchecked 警告。鑒於這些情況，如果程序員斷定聲明的構造函數和方法的主體不會對其 varargs 參數執行潛在的不安全的操作，可使用 @SafeVarargs 進行標記，這樣的話，Java 編譯器就不會報 unchecked 警告。

package com.secondgod.annotation;

import java.util.List;

public class Test {
    public final void test(List<String>... stringLists) {

    }
}

在命令行啟用建議警告的編譯。

代碼稍作修改，則可以消除編譯警告。

package com.secondgod.annotation;

import java.util.List;

public class Test {
    @SafeVarargs
    public final void test(List<String>... stringLists) {

    }
}

@FunctionalInterface#

函數式接口註解，這個是 Java 1.8 版本引入的新特性。函數式編程很火，所以 Java 8 也及時添加了這個特性。
這個註解有什麼用？這個註解保證這個接口只有一個抽象方法，注意這個只能修飾接口。

沒有抽象方法的接口

package com.secondgod.annotation;

@FunctionalInterface
public interface Test {
    
}

有超過一個抽象方法的接口

package com.secondgod.annotation;

@FunctionalInterface
public interface Test {
    String test1();

    String test2();
}

只有一個抽象方法的接口

編譯通過。

package com.secondgod.annotation;

@FunctionalInterface
public interface Test {
    String test();
}

只有一個抽象方法的抽象類

package com.secondgod.annotation;

@FunctionalInterface
public abstract class Test {
    public abstract String test();
}

元註解#

我們打開 @Override 的源碼看下，會發現這個註解的定義上本身還有註解，即註解的註解，人們通常叫他們元註解。元註解是負責對其它註解進行說明的註解，自定義註解時可以使用元註解。

JDK 內置的元註解都在 java.lang.annotation 包下面。

@Target#

Target 是目標的意思，@Target 指定了註解運用的地方。

取值	註解使用範圍
TYPE	可用於類或者接口上
FIELD	可用於域 / 字段 / 屬性上
METHOD	可用於方法上
PARAMETER	可用於參數上
CONSTRUCTOR	可用於構造方法上
LOCAL_VARIABLE	可用於局部變量上
ANNOTATION_TYPE	可用於註解類型上（被 @interface 修飾的類型）
PACKAGE	用於記錄 java 文件的 package 信息
TYPE_PARAMETER	可用於類型變量的聲明語句中
TYPE_USE	可用於使用類型的任何語句中

@Documented#

用 @Documented 註解修飾的註解類會被 JavaDoc 工具提取成文檔。默認情況下，JavaDoc 是不包括註解的，但如果聲明註解時指定了 @Documented，就會被 JavaDoc 之類的工具處理，所以註解類型信息就會被包括在生成的幫助文檔中。

@Inherited#

Inherited 是繼承的意思，但是它並不是說註解本身可以繼承，而是說如果一個超類被 @Inherited 註解過的註解進行註解的話，那麼如果它的子類沒有被任何註解應用的話，那麼這個子類就繼承了超類的註解。

@Repeatable#

Repeatable 自然是可重複的意思。Java 8 新增加的，它允許在相同的程序元素中重複註解，在需要對同一種註解多次使用時，往往需要借助 @Repeatable 註解。Java 8 版本以前，同一個程序元素前最多只能有一個相同類型的註解，如果需要在同一個元素前使用多個相同類型的註解，則必須使用註解 “容器”。

@Retention#

@Retention 用於描述註解的生命週期，也就是該註解被保留的時間長短。@Retention 註解中的成員變量（value）用來設置保留策略，value 是 java.lang.annotation.RetentionPolicy 枚舉類型，RetentionPolicy 有 3 個枚舉常量，如下所示。

取值	生命週期
SOURCE	在源文件中有效（編譯器可以使用）
CLASS	在 class 文件中有效（編譯器和虛擬機可以使用）
RUNTIME	在運行時有效（編譯器，虛擬機，程序運行時都可以使用）

@Native#

使用 @Native 註解修飾成員變量，則表示這個變量可以被本地代碼引用，常常被代碼生成工具使用。他也在 java.lang.annotation 包下面，但是我認為他不算是元註解，因為他的使用目標不是註解。

自定義註解#

在 Spring，Hibernate，Mybatis 等框架下都有註解，二當家的也嘗試自定義一個註解，先看下 @Override 的源碼吧。

package java.lang;

import java.lang.annotation.*;

/**
 * Indicates that a method declaration is intended to override a
 * method declaration in a supertype. If a method is annotated with
 * this annotation type compilers are required to generate an error
 * message unless at least one of the following conditions hold:
 *
 * <ul><li>
 * The method does override or implement a method declared in a
 * supertype.
 * </li><li>
 * The method has a signature that is override-equivalent to that of
 * any public method declared in {@linkplain Object}.
 * </li></ul>
 *
 * @author  Peter von der Ah&eacute;
 * @author  Joshua Bloch
 * @jls 9.6.1.4 @Override
 * @since 1.5
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.SOURCE)
public @interface Override {
}

我們照葫蘆畫瓢也自定義一個。

package com.secondgod.annotation;

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

/**
 * 測試註解
 *
 * @author 二當家的白帽子 https://le-yi.blog.csdn.net/
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotation {
}

我們自定義的註解通常都是定義生命週期為 RUNTIME 的。生命週期為 SOURCE 的，需要編譯器的配合。生命週期為 CLASS 的，需要虛擬機的配合。只有程序運行時的行為是我們可以自定義的。

好了，去使用一下這個自定義的註解。

package com.secondgod.annotation;

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

/**
 * 測試註解
 *
 * @author 二當家的白帽子 https://le-yi.blog.csdn.net/
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
}

/**
 * 對自定義註解的測試
 *
 * @author 二當家的白帽子 https://le-yi.blog.csdn.net/
 */
public class Test {
    @MyAnnotation
    private String name;
}

有的註解還帶參數，二當家的也加上。

package com.secondgod.annotation;

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

/**
 * 測試註解
 *
 * @author 二當家的白帽子 https://le-yi.blog.csdn.net/
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    String name();
}

/**
 * 對自定義註解的測試
 *
 * @author 二當家的白帽子 https://le-yi.blog.csdn.net/
 */
public class Test {
    @MyAnnotation(name = "二當家的")
    private String name;
}

使用時賦值必須寫屬性名，像 @Target 等一些註解賦值的時候就不用寫屬性名，那是因為屬性名是 “value”，就可以不用寫。

package com.secondgod.annotation;

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

/**
 * 測試註解
 *
 * @author 二當家的白帽子 https://le-yi.blog.csdn.net/
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    String value();
}

/**
 * 對自定義註解的測試
 *
 * @author 二當家的白帽子 https://le-yi.blog.csdn.net/
 */
public class Test {
    @MyAnnotation("二當家的")
    private String name;
}

在註解裡定義了屬性後，使用的地方必須賦值。不過可以在註解裡定義默認值，使用時就可以不賦值了。

package com.secondgod.annotation;

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

/**
 * 測試註解
 *
 * @author 二當家的白帽子 https://le-yi.blog.csdn.net/
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    String value() default "二當家的";
}

/**
 * 對自定義註解的測試
 *
 * @author 二當家的白帽子 https://le-yi.blog.csdn.net/
 */
public class Test {
    @MyAnnotation
    private String name;
}

註解裡的內容非常的少，顯然他的功能並不在裡面實現。所以註解就是個標記，本身並沒有任何功能。那他的功能如何實現呢？

註解實戰#

我們用反射和內省配合註解來實現一個小工具，可以自動用環境變量初始化屬性。

package com.secondgod.annotation;

import java.beans.IntrospectionException;
import java.beans.PropertyDescriptor;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.lang.reflect.Field;
import java.lang.reflect.InvocationTargetException;

/**
 * 工具類
 *
 * @author 二當家的白帽子 https://le-yi.blog.csdn.net/
 */
public class MyUtils {
    /**
     * 私有構造，不可實例化
     */
    private MyUtils() {}

    /**
     * 用於對屬性按照環境變量默認初始化
     */
    @Target(ElementType.FIELD)
    @Retention(RetentionPolicy.RUNTIME)
    @interface EnvironmentVariables {
        /**
         * 環境變量的key
         * @return
         */
        String value();
    }

    /**
     * 取得類實例，並用環境變量初始化
     *
     * @param clazz
     * @param <T>
     * @return
     * @throws InstantiationException
     * @throws IllegalAccessException
     * @throws java.beans.IntrospectionException
     * @throws InvocationTargetException
     */
    public static <T> T getInstance(Class<T> clazz) throws InstantiationException, IllegalAccessException, IntrospectionException, InvocationTargetException {
        T obj = clazz.newInstance();
        setEnvironmentVariables(obj);
        return obj;
    }

    /**
     * 為對象屬性按照環境變量賦值
     *
     * @param o
     * @throws IllegalAccessException
     */
    public static void setEnvironmentVariables(Object o) throws IllegalAccessException, IntrospectionException, InvocationTargetException {
        for (Field f : o.getClass().getDeclaredFields()) {
            // 利用反射讀取註解
            EnvironmentVariables environmentVariables = f.getDeclaredAnnotation(EnvironmentVariables.class);
            if (environmentVariables != null) {
                // 如果註解存在就讀取環境變量
                String value = System.getProperty(environmentVariables.value());
                // 利用內省將值寫入
                PropertyDescriptor pd = new PropertyDescriptor(f.getName(), o.getClass());
                pd.getWriteMethod().invoke(o, value);
            }
        }
    }
}

我們定義一個類用來表示虛擬機的信息，並且用註解標註屬性字段。

package com.secondgod.annotation;

import java.text.MessageFormat;

/**
 * 虛擬機信息
 *
 * @author 二當家的白帽子 https://le-yi.blog.csdn.net/
 */
public class VmInfo {
    @MyUtils.EnvironmentVariables(value = "java.vm.version")
    private String version;
    @MyUtils.EnvironmentVariables(value = "java.vm.vendor")
    private String vendor;
    @MyUtils.EnvironmentVariables(value = "java.vm.name")
    private String name;
    @MyUtils.EnvironmentVariables(value = "java.vm.specification.name")
    private String specName;
    @MyUtils.EnvironmentVariables(value = "java.vm.specification.vendor")
    private String specVendor;
    @MyUtils.EnvironmentVariables(value = "java.vm.specification.version")
    private String specVersion;
    @MyUtils.EnvironmentVariables(value = "java.vm.info")
    private String info;

    public String getVersion() {
        return version;
    }

    public void setVersion(String version) {
        this.version = version;
    }

    public String getVendor() {
        return vendor;
    }

    public void setVendor(String vendor) {
        this.vendor = vendor;
    }

    public String getName() {
        return name;
    }

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

    public String getSpecName() {
        return specName;
    }

    public void setSpecName(String specName) {
        this.specName = specName;
    }

    public String getSpecVendor() {
        return specVendor;
    }

    public void setSpecVendor(String specVendor) {
        this.specVendor = specVendor;
    }

    public String getSpecVersion() {
        return specVersion;
    }

    public void setSpecVersion(String specVersion) {
        this.specVersion = specVersion;
    }

    public String getInfo() {
        return info;
    }

    public void setInfo(String info) {
        this.info = info;
    }

    public String toString() {
        return MessageFormat.format("version={0}，vendor={1}，name={2}，specName={3}，specVendor={4}，specVersion={5}，info={6}", version, vendor, name, specName, specVendor, specVendor, info);
    }
}

好了，來測試一下我們的工具吧。

package com.secondgod.annotation;

import java.beans.IntrospectionException;
import java.lang.reflect.InvocationTargetException;

/**
 * 對自定義註解的測試
 *
 * @author 二當家的白帽子 https://le-yi.blog.csdn.net/
 */
public class Test {

    public static void main(String[] args) throws IntrospectionException, InvocationTargetException, IllegalAccessException, InstantiationException {
        VmInfo info1 = new VmInfo();
        System.out.println("普通方式實例化後：" + info1);
        VmInfo info2 = MyUtils.getInstance(VmInfo.class);
        System.out.println("使用我們的小工具實例化後：" + info2);
    }
}

內容比較多，圖沒有截全，但是很明顯可以看出我們的小工具符合我們的預期想法，很 Nice。

尾聲#

在 Spring，Hibernate，Mybatis 等框架中都有自定義註解，常常用來作為除配置文件之外的另一種配置選擇。他們各有利弊，應該根據實際情況選擇。配置文件修改重啟程序即可，而註解修改顯然只能重新編譯。但是二當家的覺得配置直接放在使用的地方非常方便，可讀性也更好，所以除非是有發布後修改的需求，否則二當家都喜歡用註解。不過用註解就會比較分散，不如配置文件集中。哎，大家仁者見仁，智者見智吧。