目錄
一 註解的定義
Java 註解是從 Java5 開始添加到 Java 的，它用於爲 Java 代碼提供元數據。作爲元數據（見補充1），註解不直接影響你的代碼執行，但也有一些類型的註解實際上可以用於這一目的。
註解即標籤：如果把代碼想象成一個具有生命的個體，註解就是給這些代碼的某些個體打的標籤。
註解API非常強大，被廣泛應用於各種Java框架，如Spring，Hibernate，JUnit，還有Android中的Dagger2、ButterKnife、Retrofit等。
二 如何自定義註解
-
註解通過 @interface關鍵字進行定義。
public @interface Test {
}
它的形式跟接口很類似，不過前面多了一個 @ 符號。上面的代碼就創建了一個名字爲 Test 的註解。 你可以簡單理解爲創建了一張名字爲 Test的標籤。
-
使用註解
@Test
public class TestAnnotation {
}
你可以簡單理解爲將 Test 這張標籤貼到 TestAnnotation這個類上面。
創建一個類 TestAnnotation,然後在類定義的地方加上 @Test就可以用 Test註解這個類了。
三 元註解
元註解是可以註解到註解上的註解，或者說元註解是一種基本註解，但是它能夠應用到其它的註解上面。
難於理解的話可以這樣說：元註解是一張特殊的標籤，可以貼在其他的標籤上，作用和目的就是給其他普通的標籤進行解釋說明。
元註解有 @Retention、@Documented、@Target、@Inherited、@Repeatable 5 種。
3.1 @Retention
Retention譯爲保留期。當 @Retention 應用到一個註解上的時候，它解釋說明了這個註解的的存活時間。
它的取值如下：
| RetentionPolicy.SOURCE | 註解只在源碼階段保留，在編譯器進行編譯時它將被丟棄忽視。 |
| RetentionPolicy.CLASS | 註解只被保留到編譯進行的時候，它並不會被加載到 JVM 中。 |
| RetentionPolicy.RUNTIME | 註解可以保留到程序運行的時候，它會被加載進入到 JVM 中，所以在程序運行時可以獲取到。 |
3.2 @Target
Target 是目標的意思，@Target 指定了註解運用的地方 你可以這樣理解，當一個註解被 @Target 註解時，這個註解就被限定了運用的場景。 類比到標籤，原本標籤是你想張貼到哪個地方就到哪個地方，但是因爲 @Target 的存在，它張貼的地方就非常具體了，比如只能張貼到方法上、類上、方法參數上等等。
@Target 有下面的取值：
| ElementType.ANNOTATION_TYPE | 可以給一個註解進行註解 |
| ElementType.CONSTRUCTOR | 可以給構造方法進行註解 |
| ElementType.FIELD | 可以給屬性進行註解 |
| ElementType.LOCAL_VARIABLE | 可以給局部變量進行註解 |
| ElementType.METHOD | 可以給方法進行註解 |
| ElementType.PACKAGE | 可以給一個包進行註解 |
| ElementType.PARAMETER | 可以給一個方法內的參數進行註解 |
3.3 @Documented
顧名思義，這個元註解肯定是和文檔有關。它的作用是能夠將註解中的元素包含到 Javadoc 中去。ElementType.TYPE 可以給一個類型進行註解，比如類、接口、枚舉。
3.4 @Inherited
Inherited 是繼承的意思，但是它並不是說註解本身可以繼承，而是說如果一個超類被 @Inherited 註解過的註解進行註解的話，那麼如果它的子類沒有被任何註解應用的話，那麼這個子類就繼承了超類的註解。
3.5 @Repeatable
Repeatable 自然是可重複的意思。@Repeatable 是 Java 1.8 才加進來的，所以算是一個新的特性。
什麼樣的註解會多次應用呢？通常是註解的值可以同時取多個。
四 Java 預置的註解
上面的知識已經可以讓我們自己定義一個註解了，但其實 Java 中本身就已經提供了一些現成的註解。
4.1 @Deprecated
這個元素是用來標記過時的元素。編譯器在編譯階段遇到這個註解時會發出提醒警告，告訴開發者正在調用一個過時的元素比如過時的方法、過時的類、過時的成員變量。
public class Stu {
@Deprecated
public void getNameOld(){
System.out.println("這個方法是不推薦的：Deprecated!");
}
public void getName(){
System.out.println("My name is Lucas");
}
在 IDE 中調用上面類的getNmaeOld方法時,可以看到getNmaeOld() 方法上面被一條直線劃掉，這其實就是編譯器識別後的提醒效果。
4.2 @Override
這個在開發者很常見了，提示子類要複寫父類中被 @Override 修飾的方法。
4.3 @SuppressWarnings
阻止警告的意思。之前說過調用被 @Deprecated 註解的方法後，編譯器會警告提醒，而有時候開發者會忽略這種警告，他們可以在調用的地方通過 @SuppressWarnings 達到目的。
@SuppressWarnings("deprecation")
public void testSupressWarnings(){
Stu stu = new Stu();
stu.getNameOld();
stu.getName();
}
4.4 @SafeVarargs
參數安全類型註解。它的目的是提醒開發者不要用參數做一些不安全的操作,它的存在會阻止編譯器產生 unchecked 這樣的警告。它是在 Java 1.7 的版本中加入的。
@SafeVarargs // Not actually safe!
static void m(List<String>... stringLists) {
Object[] array = stringLists;
List<Integer> tmpList = Arrays.asList(42);
array[0] = tmpList; // Semantically invalid, but compiles without warnings
String s = stringLists[0].get(0); // Oh no, ClassCastException at runtime!
}
上面的代碼中，編譯階段不會報錯，但是運行時會拋出 ClassCastException 這個異常，所以它雖然告訴開發者要妥善處理，但是開發者自己還是搞砸了。
4.5 @FunctionalInterface
函數式接口註解，這個是 Java 1.8 版本引入的新特性。函數式編程很火，所以 Java 8 也及時添加了這個特性。函數式接口 (Functional Interface) 就是一個具有一個方法的普通接口。比如：
@FunctionalInterface
public interface Runnable {
/**
* When an object implementing interface <code>Runnable</code> is used
* to create a thread, starting the thread causes the object's
* <code>run</code> method to be called in that separately executing
* thread.
* <p>
* The general contract of the method <code>run</code> is that it may
* take any action whatsoever.
*
* @see java.lang.Thread#run()
*/
public abstract void run();
}
我們進行線程開發中常用的 Runnable 就是一個典型的函數式接口，上面源碼可以看到它就被 @FunctionalInterface 註解。
可能有人會疑惑，函數式接口標記有什麼用，這個原因是函數式接口可以很容易轉換爲 Lambda 表達式。
五 註解的屬性
5.1 屬性的定義
註解的屬性也叫做成員變量。註解只有成員變量，沒有方法。 需要注意的是，在註解中定義屬性時它的類型必須是 8 種基本數據類型外加 類、接口、註解及它們的數組 註解中屬性可以有默認值，默認值需要用 default 關鍵值指定。
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface Test{
int id() default 1;
String msg() default "hello world";
}
上面代碼定義了 TestAnnotation 這個註解中擁有 id 和 msg 兩個屬性。在使用的時候，我們應該給它們進行賦值。 賦值的方式是在註解的括號內以 value="" 形式，多個屬性之前用 ，隔開
@Test(id=1, msg="hello annotation")
public class TestAnnotation {
}
5.2 註解的提取
註解與反射密不可分。 註解通過反射獲取。首先可以通過 Class 對象的 isAnnotationPresent() 方法判斷它是否應用了某個註解：
public boolean isAnnotationPresent(Class<? extends Annotation> annotationClass) {}
然後通過 getAnnotation() 或者是 getAnnotations() 方法來獲取 Annotation 對象，前一種方法返回指定類型的註解，後一種方法返回註解到這個元素上的所有註解：
public <A extends Annotation> A getAnnotation(Class<A> annotationClass) {}
public Annotation[] getAnnotations() {}
如果獲取到的 Annotation 如果不爲 null，則就可以調用它們的屬性方法了：
@Test()
public class TestDemo{
public static void main(String[] args) {
boolean hasAnnotation = TestDemo.class.isAnnotationPresent(Test.class);
if ( hasAnnotation ) {
TestAnnotation testAnnotation = TestDemo.class.getAnnotation(Test.class);
System.out.println("id:"+testAnnotation.id());
System.out.println("msg:"+testAnnotation.msg());
}
}
}
上面的例子中，只是檢閱出了註解在類上的註解。其實屬性、方法上的註解照樣是可以的。同樣還是要假手於反射。
@TestAnnotation(msg="hello world")
public class Test {
@Check(value="this is local value")
int tempValue;
@Perform
public void testMethod(){}
//不提示這是過時方法的ide提示
@SuppressWarnings("deprecation")
public void testSuppressWarnings(){
Stu stu = new Stu();
stu.getNameOld();
stu.getName();
}
public static void main(String[] args) {
boolean hasAnnotation = Test.class.isAnnotationPresent(TestAnnotation.class);
// 獲得註解中的屬性信息
if ( hasAnnotation ) {
TestAnnotation testAnnotation = Test.class.getAnnotation(TestAnnotation.class);
System.out.println("id:"+testAnnotation.id());
System.out.println("msg:"+testAnnotation.msg());
}
//獲取被註解的類的成員變量以及方法信息
try {
Field tempValue = Test.class.getDeclaredField("tempValue");
tempValue.setAccessible(true);
//獲取一個成員變量上的註解
Check check = tempValue.getAnnotation(Check.class);
if ( check != null ) {
System.out.println("check value:"+check.value());
}
Method testMethod = Test.class.getDeclaredMethod("testMethod");
if ( testMethod != null ) {
// 獲取方法中的註解
Annotation[] ans = testMethod.getAnnotations();
for( int i = 0;i < ans.length;i++) {
System.out.println("method testMethod annotation:"+ans[i].annotationType().getSimpleName());
}
}
} catch (NoSuchFieldException e) {
// TODO Auto-generated catch block
e.printStackTrace();
System.out.println(e.getMessage());
} catch (SecurityException e) {
// TODO Auto-generated catch block
e.printStackTrace();
System.out.println(e.getMessage());
} catch (NoSuchMethodException e) {
// TODO Auto-generated catch block
e.printStackTrace();
System.out.println(e.getMessage());
}
}
}
運行結果：
id:1
msg:hello world
check value:hi
method testMethod annotation:Perform
六 註解的使用場景
-
提供信息給編譯器： 編譯器可以利用註解來探測錯誤和警告信息
-
編譯階段時的處理： 軟件工具可以用來利用註解信息來生成代碼、Html文檔或者做其它相應處理。
-
運行時的處理： 某些註解可以在程序運行的時候接受代碼的提取 值得注意的是，註解不是代碼本身的一部分。
官方文檔的解釋上，註解主要針對的是編譯器和其它工具軟件(SoftWare tool)。當開發者使用了Annotation 修飾了類、方法、Field 等成員之後，這些 Annotation 不會自己生效，必須由開發者提供相應的代碼來提取並處理 Annotation 信息。這些處理提取和處理 Annotation 的代碼統稱爲 APT（Annotation Processing Tool)。
所以註解有什麼用？給誰用？答：給編譯器 or APT 或者 其他工具類型的軟件用的。值得注意的是，註解的提取需要 Java 的反射，而反射比較慢，所以註解使用時需要考慮時間成本的消耗。
七 註解實戰之簡易測試框架
有了註解，我們就可以在我們的代碼中，侵入性很小的進行簡單測試框架的編寫。首先定義一個需要被測試時添加的註解：
@Retention(RetentionPolicy.RUNTIME)
public @interface SimpleTest {
}
接着，在我們需要被測試的代碼段上，添加該註解，這裏以方法測試爲例：
public class BugCodeAutoTest {
@SimpleTest
public void divideZero(){
System.out.println("1 / 0 = " + 1 / 0);
}
@SimpleTest
public void normalFun(){
System.out.println("1 + 1 = " + (1 +1) );
}
}
此時就可以進行測試工具類的編寫了：
public class TestTool {
public static void main(String[] args) {
BugCodeAutoTest bugCodeAutoTest = new BugCodeAutoTest();
Class clazz = bugCodeAutoTest.getClass();
Method[] method = clazz.getDeclaredMethods();
//用來記錄測試產生的 log 信息
StringBuilder log = new StringBuilder();
// 記錄異常的次數
int errornum = 0;
for ( Method m: method ) {
// 對被 @SimlpeTest 標註過的方法進行測試
if ( m.isAnnotationPresent( SimlpeTest.class )) {
try {
m.setAccessible(true);
m.invoke(bugCodeAutoTest, null);
} catch (Exception e) {
//e.printStackTrace();
errornum++;
log.append(m.getName());
log.append(" ");
log.append("has error:");
log.append("\n\r caused by ");
//記錄測試過程中，發生的異常的名稱
log.append(e.getCause().getClass().getSimpleName());
log.append("\n\r");
//記錄測試過程中，發生的異常的具體信息
log.append(e.getCause().getMessage());
log.append("\n\r");
}
}
}
log.append(clazz.getSimpleName());
log.append(" has ");
log.append(errornum);
log.append(" error.");
// 生成測試報告
System.out.println(log.toString());
}
}
運行結果：
divideZero has error:
caused by ArithmeticException
by zero
BugCodeAutoTest has 1 error.
上述代碼中有個invoke方法，Method中invoke（Object obj,Object...args）第一個參數爲類的實例，第二個參數爲相應函數中的參數。如果函數是一個多參數的函數，可以這樣調用：method.invoke(object, new Object[][]{new Object[]{obj1, obj2}})，這樣相當於object.method(obj1, obj2)：
method2.invoke(test, new String[][]{new String[]{"a", "b"}});
補充1 ：元數據
| 術語 | 定義 |
| 元數據 | 關於數據的數據。JSR-175 的目標是在 Java 語言中提供元數據工具。 |
| 批註 | 一種特殊的 Java 結構，用來修飾類、方法、字段、參數、變量、構造器或包。它是 JSR-175 選擇用來提供元數據的工具。 |
| 批註類型 | 具有特殊實施的各種命名批註 |
| 屬性 | 由批註指定的一個特殊的元數據項目。有時可以和批註交替使用 |
例如：富士蘋果有一個屬性：它是紅色的。假定有一個 FujiApple 類，您可以使用 @Color 批註類型的一個批註來指定它的顏色。通過這麼做，您就提供了關於蘋果的元數據。
元數據從metadata一詞譯來，就是“關於數據的數據”的意思，即描述數據的結構信息。元數據的功能作用有很多，比如：你可能用過Javadoc的註釋自動生成文檔。這就是元數據功能的一種。總的來說，元數據可以用來創建文檔，跟蹤代碼的依賴性，執行編譯時格式檢查，代替已有的配置文件。
在Java中元數據以標籤的形式存在於Java代碼中，元數據標籤的存在並不影響程序代碼的編譯和執行，被用來生成其它的文件或只在運行時知道被運行代碼的描述信息。
其作用如下:
①生成文檔：這是最常見的，也是java 最早提供的註解。常用的有@param @return 等;
② 跟蹤代碼依賴性，實現替代配置文件功能。常見的是spring 2.5 開始的基於註解配置。作用就是減少配置。現在的框架基本都使用了這種配置來減少配置文件的數量。;
③在編譯時進行格式檢查。如@override 放在方法前，如果你這個方法並不是覆蓋了超類方法，則編譯時就能檢查出。
參考文章：
充分利用 Java 的元數據：https://www.oracle.com/technetwork/articles/hunter-meta-097643-zhs.html
我覺得最好的一篇註解文章：秒懂，Java 註解 （Annotation）你可以這樣學：https://blog.csdn.net/briblue/article/details/73824058
Java註解-元數據、註解分類、內置註解和自定義註解：https://juejin.im/post/5d3ac8d5e51d4577407b1e3a