閱讀977 返回首頁    go 阿裏雲 go 技術社區[雲棲]

Java 注解指導手冊 – 終極向導

編者的話：注解是java的一個主要特性且每個java開發者都應該知道如何使用它。

我們已經在Java Code Geeks提供了豐富的教程, 如Creating Your Own Java Annotations, Java Annotations Tutorial with Custom Annotation 和 Java Annotations: Explored & Explained.

我們也有些文章是關於注解在不同類庫中的應用，包括 Make your Spring Security @Secured annotations more DRY和 Java Annotations & A Real World Spring Example.

現在，是時候匯總這些和注解相關的信息到一篇文章了，祝大家閱讀愉快。

目錄

  1. 什麼是注解
  2. 介紹
  3. 消費器
  4. 注解語法和注解元素
  5. 在什麼地方使用
  6. 使用案例
  7. 內建注解
  8. Java 8 與注解
  9. 自定義注解
  10. 提取注解
  11. 注解集成
  12. 使用注解的知名類庫
  13. 小結
  14. 下載
  15. 資料

 

在這篇文章中我們將闡述什麼是Java注解，它們如何工作，怎麼使用它們。

我們將揭開Java注解的麵紗，包括內建注解或稱元注解，還將討論Java8中與之相關的的新特性。

最後，我們將實現自定義的注解，編寫一個使用注解的處理程序（消費器），它通過java反射使用注解。

我們還會列出一些基於注解，知名且被廣泛應用的第三方類庫如：Junit，JAXB，Spring，Hibernate。

在文章的最後，會有一個壓縮文件包含了文章中的所有示例，實現這些例子使用的軟件版本如下所示：

  • Eclipse Luna 4.4
  • JRE Update 8.20
  • Junit 4
  • Hibernate 4.3.6
  • FindBugs 3.0.0

1.什麼是注解？

注解早在J2SE1.5就被引入到Java中，主要提供一種機製，這種機製允許程序員在編寫代碼的同時可以直接編寫元數據。

在引入注解之前，程序員們描述其代碼的形式尚未標準化，每個人的做法各異：transient關鍵字、注釋、接口等。這顯然不是一種優雅的方式，隨之而來的一種嶄新的記錄元數據的形式——注解被引入到Java中。

其它因素也促成了這個決定：當時不同類型的應用程序使用XML作為標準的代碼配置機製，這其實並不是最佳方式，因為代碼和XML的解耦以及未來對這種解耦應用的維護並不低廉。另外，由於非保留字的使用，例如“@deprecated”自從Java1.4便開始在Java文檔中使用。我非常確定這是一個現在在注解中使用“@”原因。

包含注解的設計和開發的Java規範主要有以下兩篇：

2. 介紹

解釋何為注解的最佳方式就是元數據這個詞：描述數據自身的數據。注解就是代碼的元數據，他們包含了代碼自身的信息。

注解可以被用在包，類，方法，變量，參數上。自Java8起，有一種注解幾乎可以被放在代碼的任何位置，叫做類型注解。我們將會在後麵談到具體用法。

被注解的代碼並不會直接被注解影響。這隻會向第三係統提供關於自己的信息以用於不同的需求。

注解會被編譯至class文件中，而且會在運行時被處理程序提取出來用於業務邏輯。當然，創建在運行時不可用的注解也是可能的，甚至可以創建隻在源文件中可用，在編譯時不可用的注解。

3.消費器

理解注解的目的以及如何使用它都會帶來困難，因為注解本身並不包含任何功能邏輯，它們也不會影響自己注解的代碼，那麼，它們到底為什麼而存在呢？

這個問題的解釋就是我所稱的注解消費器。它們是利用被注解代碼並根據注解信息產生不同行為的係統或者應用程序。

例如，在Java自帶的內建注解（元注解）中，消費器是執行被注解代碼的JVM。還有其他稍後談到的其他例子，例如JUnit，消費器是讀取，分析被注解代碼的JUnit處理程序，它還可以決定測試單元和方法執行順序。我們會在JUnit章節更深入。

消費器使用Java中的反射機製來讀取和分析被注解的源代碼。使用的主要的包有：java.lang, java.lang.reflect。我們將會在本篇指南中介紹如何用反射從頭開始創建一個自定義的消費器。

4. 注解語法和元素

聲明一個注解需要使用“@”作為前綴，這便向編譯器說明，該元素為注解。例如：

1 @Annotation
2 public void annotatedMehod() {
3 ...
4  }

上述的注解名稱為Annotation，它正在注解annotatedMethod方法。編譯器會處理它。注解可以以鍵值對的形式持有有很多元素，即注解的屬性。

1 @Annotation(
2  info = "I am an annotation",
3  counter = "55"
4 )
5 public void annotatedMehod() {
6 ...
7  }

如果注解隻包含一個元素（或者隻需要指定一個元素的值，其它則使用默認值），可以像這樣聲明：

1 @Annotation("I am an annotation")
2 public void annotatedMehod() {
3 ...
4  }

就像我們看到的一樣，如果沒有元素需要被指定，則不需要括號。多個注解可以使用在同一代碼上，例如類：

1 @ Annotation (info = "U a u O")
2 @ Annotation2
3 class AnnotatedClass { ... }

一些java本身提供的開箱即用的注解，我們稱之為內建注解。也可以定義你自己的注解，稱之為子定義注解。我們會在下一章討論。

5. 在什麼地方使用

注解基本上可以在Java程序的每一個元素上使用：類，域，方法，包，變量，等等。

自Java8，誕生了通過類型注解的理念。在此之前，注解是限於在前麵討論的元素的聲明上使用。從此，無論是類型還是聲明都可以使用注解，就像：

1 @MyAnnotation String str = "danibuiza";

我們將會在Java8關聯章節看到這種機製的更多細節。

6. 使用案例

注解可以滿足許多要求，最普遍的是：

  • 向編譯器提供信息：注解可以被編譯器用來根據不同的規則產生警告，甚至錯誤。一個例子是Java8中@FunctionalInterface注解，這個注解使得編譯器校驗被注解的類，檢查它是否是一個正確的函數式接口。
  • 文檔：注解可以被軟件應用程序計算代碼的質量例如：FindBugs，PMD或者自動生成報告，例如：用來Jenkins, Jira，Teamcity。
  • 代碼生成：注解可以使用代碼中展現的元數據信息來自動生成代碼或者XML文件，一個不錯的例子是JAXB。
  • 運行時處理：在運行時檢查的注解可以用做不同的目的，像單元測試（JUnit），依賴注入（Spring），校驗，日誌（Log4j），數據訪問（Hibernate）等等。

在這篇手冊中我們將展現幾種注解可能的用法，包括流行的Java類庫是如何使用它們的。

7. 內建注解

Java語言自帶了一係列的注解。在本章中我們將闡述最重要的一部分。這個清單隻涉及了Java語言最核心的包，未包含標準JRE中所有包和庫如JAXB或Servlet規範。

以下討論到的注解中有一些被稱之為Meta注解，它們的目的注解其他注解，並且包含關於其它注解的信息。

  • @Retention：這個注解注在其他注解上，並用來說明如何存儲已被標記的注解。這是一種元注解，用來標記注解並提供注解的信息。可能的值是：
    • SOURCE：表明這個注解會被編譯器忽略，並隻會保留在源代碼中。
    • CLASS:表明這個注解會通過編譯駐留在CLASS文件，但會被JVM在運行時忽略,正因為如此,其在運行時不可見。
    • RUNTIME：表示這個注解會被JVM獲取，並在運行時通過反射獲取。

我們會在稍後展開幾個例子。

  • @Target：這個注解用於限製某個元素可以被注解的類型。例如：
    • ANNOTATION_TYPE 表示該注解可以應用到其他注解上
    • CONSTRUCTOR 表示可以使用到構造器上
    • FIELD 表示可以使用到域或屬性上
    • LOCAL_VARIABLE表示可以使用到局部變量上。
    • METHOD可以使用到方法級別的注解上。
    • PACKAGE可以使用到包聲明上。
    • PARAMETER可以使用到方法的參數上
    • TYPE可以使用到一個類的任何元素上。
  • @Documented：被注解的元素將會作為Javadoc產生的文檔中的內容。注解都默認不會成為成為文檔中的內容。這個注解可以對其它注解使用。
  • @Inherited：在默認情況下，注解不會被子類繼承。被此注解標記的注解會被所有子類繼承。這個注解可以對類使用。
  • @Deprecated：說明被標記的元素不應該再度使用。這個注解會讓編譯器產生警告消息。可以使用到方法，類和域上。相應的解釋和原因，包括另一個可取代的方法應該同時和這個注解使用。
  • @SuppressWarnings：說明編譯器不會針對指定的一個或多個原因產生警告。例如：如果我們不想因為存在尚未使用的私有方法而得到警告可以這樣做：
1 @SuppressWarnings( "unused")
2 private String myNotUsedMethod(){
3  ...
4 }

通常,編譯器會因為沒調用該方而產生警告; 用了注解抑製了這種行為。該注解需要一個或多個參數來指定抑製的警告類型。

  • @Override：向編譯器說明被注解元素是重寫的父類的一個元素。在重寫父類元素的時候此注解並非強製性的，不過可以在重寫錯誤時幫助編譯器產生錯誤以提醒我們。比如子類方法的參數和父類不匹配，或返回值類型不同。
  • @SafeVarargs：斷言方法或者構造器的代碼不會對參數進行不安全的操作。在Java的後續版本中，使用這個注解時將會令編譯器產生一個錯誤在編譯期間防止潛在的不安全操作。

更多信息請參考：https://docs.oracle.com/javase/7/docs/api/java/lang/SafeVarargs.html

8. Java 8 與注解

Java8帶來了一些優勢，同樣注解框架的能力也得到了提升。在本章我們將會闡述，並就java8帶來的3個注解做專題說明和舉例：

@Repeatable注解，關於類型注解的聲明，函數式接口注解@FunctionalInterface（與Lambdas結合使用）。

  • @Repeatable：說明該注解標識的注解可以多次使用到同一個元素的聲明上。

看一個使用的例子。首先我們創造一個能容納重複的注解的容器：

1 /**
2  * Container for the {@link CanBeRepeated} Annotation containing a list of values
3 */
4 @Retention( RetentionPolicy.RUNTIME )
5 @Target( ElementType.TYPE_USE )
6 public @interface RepeatedValues
7 {
8  CanBeRepeated[] value();
9 }

接著，創建注解本身，然後標記@Repeatable

1 @Retention( RetentionPolicy.RUNTIME )
2 @Target( ElementType.TYPE_USE )
3 @Repeatable( RepeatedValues.class )
4 public @interface CanBeRepeated
5 {
6  
7  String value();
8 }

最後，我們可以這樣重複地使用：

1 @CanBeRepeated( "the color is green" )
2 @CanBeRepeated( "the color is red" )
3 @CanBeRepeated( "the color is blue" )
4 public class RepeatableAnnotated
5 {
6  
7 }

如果我們嚐試去掉@Repeatable

01 @Retention( RetentionPolicy.RUNTIME )
02 @Target( ElementType.TYPE_USE )
03 public @interface CannotBeRepeated
04 {
05  
06  String value();
07 }
08  
09 @CannotBeRepeated( "info" )
10 /*
11  * if we try repeat the annotation we will get an error: Duplicate annotation of non-repeatable type
12  *
13  * @CannotBeRepeated. Only annotation types marked
14  *
15  * @Repeatable can be used multiple times at one target.
16  */
17 // @CannotBeRepeated( "more info" )
18 public class RepeatableAnnotatedWrong
19 {
20  
21 }

我們會得到編譯器的錯誤信息：

1 Duplicate annotation of non-repeatable type
  • 自Java8開始，我們可以在類型上使用注解。由於我們在任何地方都可以使用類型，包括 new操作符，casting，implements，throw等等。注解可以改善對Java代碼的分析並且保證更加健壯的類型檢查。這個例子說明了這一點：
01 @SuppressWarnings( "unused" )
02 public static void main( String[] args )
03 {
04  // type def
05  @TypeAnnotated
06  String cannotBeEmpty = null;
07  
08  // type
09  List<@TypeAnnotated String> myList = new ArrayList<String>();
10  
11  // values
12  String myString = new @TypeAnnotated String( "this is annotated in java 8" );
13  
14 }
15  
16 // in method params
17 public void methodAnnotated( @TypeAnnotated int parameter )
18 {
19  System.out.println( "do nothing" );
20 }

所有的這些在Java8之前都是不可能的。

  • @FunctionalInterface：這個注解表示一個函數式接口元素。函數式接口是一種隻有一個抽象方法（非默認）的接口。編譯器會檢查被注解元素，如果不符，就會產生錯誤。例子如下：
01 // implementing its methods
02 @SuppressWarnings( "unused" )
03 MyCustomInterface myFuncInterface = new MyCustomInterface()
04 {
05  
06  @Override
07  public int doSomething( int param )
08  {
09  return param * 10;
10  }
11 };
12  
13 // using lambdas
14 @SuppressWarnings( "unused" )
15  MyCustomInterface myFuncInterfaceLambdas = ( x ) -> ( x * 10 );
16 }
17  
18 @FunctionalInterface
19 interface MyCustomInterface
20 {
21 /*
22  * more abstract methods will cause the interface not to be a valid functional interface and
23  * the compiler will thrown an error:Invalid '@FunctionalInterface' annotation;
24  * FunctionalInterfaceAnnotation.MyCustomInterface is not a functional interface
25  */
26  // boolean isFunctionalInterface();
27  
28  int doSomething( int param );
29 }

這個注解可以被使用到類，接口，枚舉和注解本身。它的被JVM保留並在runtime可見，這個是它的聲明：

1 @Documented
2  @Retention(value=RUNTIME)
3  @Target(value=TYPE)
4 public @interface FunctionalInterface

9. 自定義注解

正如我們之前多次提及的，可以定義和實現自定義注解。本章我們即將探討。
首先，定義一個注解：

1 public @interface CustomAnnotationClass

這樣創建了一個新的注解類型名為 CustomAnnotationClass。關鍵字：@interface說明這是一個自定義注解的定義。

之後，你需要為此注解定義一對強製性的屬性，保留策略和目標。還有一些其他屬性可以定義，不過這兩個是最基本和重要的。它們在第8章，描述注解的注解時討論過，它們同樣也是Java內建的注解。

所以，我們為自定義的注解設置屬性：

1 @Retention( RetentionPolicy.RUNTIME )
2 @Target( ElementType.TYPE )
3 public @interface CustomAnnotationClass implements CustomAnnotationMethod

在保留策略中 RUNTIME 告訴編譯器這個注解應該被被JVM保留，並且能通過反射在運行時分析。通過 TYPE 我們又設置該注解可以被使用到任何類的元素上。

之後，我們定義兩個注解的成員：

01 @Retention( RetentionPolicy.RUNTIME )
02 @Target( ElementType.TYPE )
03 public @interface CustomAnnotationClass
04 {
05  
06  public String author() default "danibuiza";
07  
08  public String date();
09  
10 }

以上我們僅定義了默認值為“danibuiza”的 author 屬性和沒有默認值的date屬性。我們應強調所有的方法聲明都不能有參數和throw子句。這個返回值的類型被限製為之前提過的字符串，類，枚舉，注解和存儲這些類型的數組。

現在我們可以像這樣使用剛創建的自定義注解：

1 @CustomAnnotationClass( date = "2014-05-05" )
2 public class AnnotatedClass
3 {
4 ...
5 }

在另一種類似的用法中我們可以創建一種注解方法的注解，使用Target METHOD：

01 @Retention( RetentionPolicy.RUNTIME )
02 @Target( ElementType.METHOD )
03 public @interface CustomAnnotationMethod
04 {
05  
06  public String author() default "danibuiza";
07  
08  public String date();
09  
10  public String description();
11  
12 }

這種注解可以使用在方法聲明上：

01 @CustomAnnotationMethod( date = "2014-06-05", description = "annotated method" )
02 public String annotatedMethod()
03  {
04  return "nothing niente";
05 }
06  
07 @CustomAnnotationMethod( author = "friend of mine", date = "2014-06-05", description = "annotated method" )
08 public String annotatedMethodFromAFriend()
09 {
10  return "nothing niente";
11 }

有很多其它屬性可以用在自定義注解上，但是 目標 （Target）和 保留策略（Retention Policy）是最重要的兩個。

10. 獲取注解

Java反射API包含了許多方法來在運行時從類，方法或者其它元素獲取注解。接口AnnotatedElement包含了大部分重要的方法，如下：

  • getAnnotations(): 返回該元素的所有注解，包括沒有顯式定義該元素上的注解。
  • isAnnotationPresent(annotation): 檢查傳入的注解是否存在於當前元素。
  • getAnnotation(class): 按照傳入的參數獲取指定類型的注解。返回null說明當前元素不帶有此注解。

class 通過java.lang.Class被實現，java.lang.reflect.Method 和 java.lang.reflect.Field，所以可以基本上被和任何Java元素使用。

現在，我們將看一個怎麼讀取注解的例子：
我們寫一個程序，從一個類和它的方法中讀取所有的存在的注解：

01 public static void main( String[] args ) throws Exception
02 {
03  
04  Class<AnnotatedClass> object = AnnotatedClass.class;
05  // Retrieve all annotations from the class
06  Annotation[] annotations = object.getAnnotations();
07  for( Annotation annotation : annotations )
08  {
09  System.out.println( annotation );
10  }
11  
12  // Checks if an annotation is present
13  if( object.isAnnotationPresent( CustomAnnotationClass.class ) )
14  {
15  
16  // Gets the desired annotation
17  Annotation annotation = object.getAnnotation( CustomAnnotationClass.class );
18  
19  System.out.println( annotation );
20  
21  }
22  // the same for all methods of the class
23  for( Method method : object.getDeclaredMethods() )
24  {
25  
26  if( method.isAnnotationPresent( CustomAnnotationMethod.class ) )
27  {
28  
29  Annotation annotation = method.getAnnotation( CustomAnnotationMethod.class );
30  
31  System.out.println( annotation );
32  
33  }
34  
35  }
36 }

輸出如下：

1 @com.danibuiza.javacodegeeks.customannotations.CustomAnnotationClass(getInfo=Info, author=danibuiza, date=2014-05-05)
2  
3 @com.danibuiza.javacodegeeks.customannotations.CustomAnnotationClass(getInfo=Info, author=danibuiza, date=2014-05-05)
4  
5 @com.danibuiza.javacodegeeks.customannotations.CustomAnnotationMethod(author=friend of mine, date=2014-06-05, description=annotated method)
6 @com.danibuiza.javacodegeeks.customannotations.CustomAnnotationMethod(author=danibuiza, date=2014-06-05, description=annotated method)

在這個程序中，我們可以看到 getAnnotations()方法來獲取所有某個對象（方法，類）上的所有注解的用法。展示了怎樣使用isAnnotationPresent()方法和getAnnotation()方法檢查是否存在特定的注解，和如何獲取它。

11. 注解中的繼承

注解在Java中可以使用繼承。這種繼承和普通的麵向對象繼承幾乎沒有共同點。

如果一個注解在Java中被標識成繼承，使用了保留注解@Inherited，說明它注解的這個類將自動地把這個注解傳遞到所有子類中而不用在子類中聲明。通常，一個類繼承了父類，並不繼承父類的注解。這完全和使用注解的目的一致的：提供關於被注解的代碼的信息而不修改它們的行為。

我們通過一個例子更清楚地說明。首先，我們定義一個自動繼承的自定義注解。

1 @Inherited
2 @Retention(RetentionPolicy.RUNTIME)
3 @Target(ElementType.TYPE)
4 public @interface InheritedAnnotation
5 {
6  
7 }

有一個父類名為：AnnotatedSuperClass，已經被自定義的注解給注解上了：

01 @InheritedAnnotation
02 public class AnnotatedSuperClass
03 {
04  
05  public void oneMethod()
06  {
07  
08  }
09  
10 }

一個子類繼承父類：

01 @InheritedAnnotation
02 public class AnnotatedSuperClass
03 {
04  
05  public void oneMethod()
06  {
07  
08  }
09  
10 }

子類 AnnotatedSubClass 展示了自動繼承的注解 @InheritedAnnotation。我們看到下麵的代碼通過 isAnnotationPresent() 方法測試出了當前注解。

1 <pre>System.out.println( "is true: " + AnnotatedSuperClass.class.isAnnotationPresent( InheritedAnnotation.class ) );
2  
3 System.out.println( "is true: " + AnnotatedSubClass.class.isAnnotationPresent( InheritedAnnotation.class ) );</pre>
4 <pre>

輸出如下：

1 is true: true
2 is true: true

我們可以看到子類雖然並沒有聲明注解，但還是被自動地注解上了。

如果我們嚐試注解在一個接口中：

1 @InheritedAnnotation
2 public interface AnnotatedInterface
3 {
4  
5  public void oneMethod();
6  
7 }

一個實現了該接口的類：

01 public class AnnotatedImplementedClass implements AnnotatedInterface
02 {
03  
04  @Override
05  public void oneMethod()
06  {
07  
08  }
09  
10 }

經過 isAnnotationPresent() 方法測試：

1 System.out.println( "is true: " + AnnotatedInterface.class.isAnnotationPresent( InheritedAnnotation.class ) );
2  
3 System.out.println( "is true: " + AnnotatedImplementedClass.class.isAnnotationPresent( InheritedAnnotation.class ) );

結果如下：

1 is true: true
2 is true: false

這個結果說明繼承注解和接口在一起使用時，接口中的注解在實現類中：僅僅被忽略。實現類並不繼承接口的注解；接口繼承僅僅適用於類繼承。正如 AnnotatedSubClass。
@Inheriated注解僅在存在繼承關係的類上產生效果，在接口和實現類上並不工作。這條同樣也適用在方法，變量，包等等。隻有類才和這個注解連用。

一條關於@Inheriated注解的很好的解釋在Javadoc中：https://docs.oracle.com/javase/7/docs/api/java/lang/annotation/Inherited.html.

注解不能繼承注解，如果你嚐試這麼做了，就會得到編譯器拋出的錯誤：

1 Annotation type declaration cannot have explicit superinterfaces

12. 使用注解的知名類庫

在這一章我們將展示知名類庫是如何利用注解的。一些類庫如：JAXB, Spring Framework, Findbugs, Log4j, Hibernate, Junit。它們使用注解來完成代碼質量分析，單元測試，XML解析，依賴注入和許多其它的工作。

在這篇手冊中我們將討論以下類庫的部分內容：

12.1. Junit

這個框架用於完成Java中的單元測試。自JUnit4開始，注解被廣泛應用，成為Junit的設計的主幹之一。

基本上，JUnit處理程序通過反射讀取類和測試套件，按照在方法上，類上的注解順序地執行它們。當然還有一些用來修改測試執行的注解。其它注解都用來執行測試，阻止執行，改變執行順序等等。

用到的注解相當多，但是我們將會看到最重要的幾個：