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

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

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

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

在這篇文章中我們將闡述什么是Java注解，它們?nèi)绾喂ぷ?，怎么使用它們?/p>

我們將揭開Java注解的面紗，包括內(nèi)建注解或稱元注解，還將討論Java8中與之相關(guān)的的新特性。

最后，我們將實現(xiàn)自定義的注解，編寫一個使用注解的處理程序（消費(fèi)器），它通過java反射使用注解。

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

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

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

 

1.什么是注解？

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

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

其它因素也促成了這個決定：當(dāng)時不同類型的應(yīng)用程序使用XML作為標(biāo)準(zhǔn)的代碼配置機(jī)制，這其實并不是最佳方式，因為代碼和XML的解耦以及未來對這種解耦應(yīng)用的維護(hù)并不低廉。另外，由于非保留字的使用，例如“@deprecated”自從Java1.4便開始在Java文檔中使用。我非常確定這是一個現(xiàn)在在注解中使用“@”原因。

包含注解的設(shè)計和開發(fā)的Java規(guī)范主要有以下兩篇：

• JSR 175 A metadata facility for the Java programming Language
• JSR 250 Common Annotations for the Java Platform

2. 介紹

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

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

被注解的代碼并不會直接被注解影響。這只會向第三系統(tǒng)提供關(guān)于自己的信息以用于不同的需求。

注解會被編譯至class文件中，而且會在運(yùn)行時被處理程序提取出來用于業(yè)務(wù)邏輯。當(dāng)然，創(chuàng)建在運(yùn)行時不可用的注解也是可能的，甚至可以創(chuàng)建只在源文件中可用，在編譯時不可用的注解。

3.消費(fèi)器

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

這個問題的解釋就是我所稱的注解消費(fèi)器。它們是利用被注解代碼并根據(jù)注解信息產(chǎn)生不同行為的系統(tǒng)或者應(yīng)用程序。

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

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

4. 注解語法和元素

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

@Annotation 
public void annotatedMehod() { 
... 
 } 

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

@Annotation( 
 info = "I am an annotation", 
 counter = "55" 
) 
public void annotatedMehod() { 
... 
 } 

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

@Annotation("I am an annotation") 
public void annotatedMehod() { 
... 
 } 

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

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

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

5. 在什么地方使用

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

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

@MyAnnotation String str = "danibuiza"; 

我們將會在Java8關(guān)聯(lián)章節(jié)看到這種機(jī)制的更多細(xì)節(jié)。

6. 使用案例

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

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

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

7. 內(nèi)建注解

Java語言自帶了一系列的注解。在本章中我們將闡述最重要的一部分。這個清單只涉及了Java語言最核心的包，未包含標(biāo)準(zhǔn)JRE中所有包和庫如JAXB或Servlet規(guī)范。

以下討論到的注解中有一些被稱之為Meta注解，它們的目的注解其他注解，并且包含關(guān)于其它注解的信息。

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

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

• @Target：這個注解用于限制某個元素可以被注解的類型。例如：
  • ANNOTATION_TYPE 表示該注解可以應(yīng)用到其他注解上
  • CONSTRUCTOR 表示可以使用到構(gòu)造器上
  • FIELD 表示可以使用到域或?qū)傩陨?/li>
  • LOCAL_VARIABLE表示可以使用到局部變量上。
  • METHOD可以使用到方法級別的注解上。
  • PACKAGE可以使用到包聲明上。
  • PARAMETER可以使用到方法的參數(shù)上
  • TYPE可以使用到一個類的任何元素上。
• @Documented：被注解的元素將會作為Javadoc產(chǎn)生的文檔中的內(nèi)容。注解都默認(rèn)不會成為成為文檔中的內(nèi)容。這個注解可以對其它注解使用。
• @Inherited：在默認(rèn)情況下，注解不會被子類繼承。被此注解標(biāo)記的注解會被所有子類繼承。這個注解可以對類使用。
• @Deprecated：說明被標(biāo)記的元素不應(yīng)該再度使用。這個注解會讓編譯器產(chǎn)生警告消息?？梢允褂玫椒椒?，類和域上。相應(yīng)的解釋和原因，包括另一個可取代的方法應(yīng)該同時和這個注解使用。
• @SuppressWarnings：說明編譯器不會針對指定的一個或多個原因產(chǎn)生警告。例如：如果我們不想因為存在尚未使用的私有方法而得到警告可以這樣做：

@SuppressWarnings( "unused") 
private String myNotUsedMethod(){ 
 ... 
} 

通常,編譯器會因為沒調(diào)用該方而產(chǎn)生警告; 用了注解抑制了這種行為。該注解需要一個或多個參數(shù)來指定抑制的警告類型。

• @Override：向編譯器說明被注解元素是重寫的父類的一個元素。在重寫父類元素的時候此注解并非強(qiáng)制性的，不過可以在重寫錯誤時幫助編譯器產(chǎn)生錯誤以提醒我們。比如子類方法的參數(shù)和父類不匹配，或返回值類型不同。
• @SafeVarargs：斷言方法或者構(gòu)造器的代碼不會對參數(shù)進(jìn)行不安全的操作。在Java的后續(xù)版本中，使用這個注解時將會令編譯器產(chǎn)生一個錯誤在編譯期間防止?jié)撛诘牟话踩僮鳌?/li>

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

8. Java 8 與注解

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

@Repeatable注解，關(guān)于類型注解的聲明，函數(shù)式接口注解@FunctionalInterface（與Lambdas結(jié)合使用）。

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

看一個使用的例子。首先我們創(chuàng)造一個能容納重復(fù)的注解的容器：

/** 
 * Container for the {@link CanBeRepeated} Annotation containing a list of values 
*/ 
@Retention( RetentionPolicy.RUNTIME ) 
@Target( ElementType.TYPE_USE ) 
public @interface RepeatedValues 
{ 
 CanBeRepeated[] value(); 
} 

接著，創(chuàng)建注解本身，然后標(biāo)記@Repeatable

@Retention( RetentionPolicy.RUNTIME ) 
@Target( ElementType.TYPE_USE ) 
@Repeatable( RepeatedValues.class ) 
public @interface CanBeRepeated 
{ 
 String value(); 
} 

最后，我們可以這樣重復(fù)地使用：

@CanBeRepeated( "the color is green" ) 
@CanBeRepeated( "the color is red" ) 
@CanBeRepeated( "the color is blue" ) 
public class RepeatableAnnotated 
{ 
  
} 

如果我們嘗試去掉@Repeatable

@Retention( RetentionPolicy.RUNTIME ) 
@Target( ElementType.TYPE_USE ) 
public @interface CannotBeRepeated 
{ 
  
 String value(); 
} 
  
@CannotBeRepeated( "info" ) 
/* 
 * if we try repeat the annotation we will get an error: Duplicate annotation of non-repeatable type 
 * 
 * @CannotBeRepeated. Only annotation types marked 
 * 
 * @Repeatable can be used multiple times at one target. 
 */ 
// @CannotBeRepeated( "more info" ) 
public class RepeatableAnnotatedWrong 
{ 
  
} 

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

Duplicate annotation of non-repeatable type 

• 自Java8開始，我們可以在類型上使用注解。由于我們在任何地方都可以使用類型，包括 new操作符，casting，implements，throw等等。注解可以改善對Java代碼的分析并且保證更加健壯的類型檢查。這個例子說明了這一點：

@SuppressWarnings( "unused" ) 
public static void main( String[] args ) 
{ 
 // type def 
 @TypeAnnotated 
 String cannotBeEmpty = null; 
  
 // type 
 List<@TypeAnnotated String> myList = new ArrayList<String>(); 
  
 // values 
 String myString = new @TypeAnnotated String( "this is annotated in java 8" ); 
  
} 
 // in method params 
public void methodAnnotated( @TypeAnnotated int parameter ) 
{ 
 System.out.println( "do nothing" ); 
} 

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

• @FunctionalInterface：這個注解表示一個函數(shù)式接口元素。函數(shù)式接口是一種只有一個抽象方法（非默認(rèn)）的接口。編譯器會檢查被注解元素，如果不符，就會產(chǎn)生錯誤。例子如下：

// implementing its methods 
@SuppressWarnings( "unused" ) 
MyCustomInterface myFuncInterface = new MyCustomInterface() 
{ 
  
 @Override 
 public int doSomething( int param ) 
 { 
 return param * 10; 
 } 
}; 
  
// using lambdas 
@SuppressWarnings( "unused" ) 
 MyCustomInterface myFuncInterfaceLambdas = ( x ) -> ( x * 10 ); 
} 
  
@FunctionalInterface 
interface MyCustomInterface 
{ 
/* 
 * more abstract methods will cause the interface not to be a valid functional interface and 
 * the compiler will thrown an error:Invalid '@FunctionalInterface' annotation; 
 * FunctionalInterfaceAnnotation.MyCustomInterface is not a functional interface 
 */ 
 // boolean isFunctionalInterface(); 
  
 int doSomething( int param ); 
} 

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

@Documented 
 @Retention(value=RUNTIME) 
 @Target(value=TYPE) 
public @interface FunctionalInterface 

#p#

9. 自定義注解

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

public @interface CustomAnnotationClass 

這樣創(chuàng)建了一個新的注解類型名為 CustomAnnotationClass。關(guān)鍵字：@interface說明這是一個自定義注解的定義。

之后，你需要為此注解定義一對強(qiáng)制性的屬性，保留策略和目標(biāo)。還有一些其他屬性可以定義，不過這兩個是最基本和重要的。它們在第8章，描述注解的注解時討論過，它們同樣也是Java內(nèi)建的注解。

所以，我們?yōu)樽远x的注解設(shè)置屬性：

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

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

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

@Retention( RetentionPolicy.RUNTIME ) 
@Target( ElementType.TYPE ) 
public @interface CustomAnnotationClass 
{ 
  
 public String author() default "danibuiza"; 
  
 public String date(); 
  
} 

以上我們僅定義了默認(rèn)值為“danibuiza”的 author 屬性和沒有默認(rèn)值的date屬性。我們應(yīng)強(qiáng)調(diào)所有的方法聲明都不能有參數(shù)和throw子句。這個返回值的類型被限制為之前提過的字符串，類，枚舉，注解和存儲這些類型的數(shù)組。

現(xiàn)在我們可以像這樣使用剛創(chuàng)建的自定義注解：

@CustomAnnotationClass( date = "2014-05-05" ) 
public class AnnotatedClass 
{ 
... 
} 

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

@Retention( RetentionPolicy.RUNTIME ) 
@Target( ElementType.METHOD ) 
public @interface CustomAnnotationMethod 
{ 
  
 public String author() default "danibuiza"; 
  
 public String date(); 
  
 public String description(); 
  
} 

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

@CustomAnnotationMethod( date = "2014-06-05", description = "annotated method" ) 
public String annotatedMethod() 
 { 
 return "nothing niente"; 
} 
  
@CustomAnnotationMethod( author = "friend of mine", date = "2014-06-05", description = "annotated method" ) 
public String annotatedMethodFromAFriend() 
{ 
 return "nothing niente"; 
} 

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

10. 獲取注解

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

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

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

現(xiàn)在，我們將看一個怎么讀取注解的例子：

我們寫一個程序，從一個類和它的方法中讀取所有的存在的注解：

public static void main( String[] args ) throws Exception 
{ 
  
 Class<AnnotatedClass> object = AnnotatedClass.class; 
 // Retrieve all annotations from the class 
 Annotation[] annotations = object.getAnnotations(); 
 for( Annotation annotation : annotations ) 
 { 
 System.out.println( annotation ); 
 } 
  
 // Checks if an annotation is present 
 if( object.isAnnotationPresent( CustomAnnotationClass.class ) ) 
 { 
  
 // Gets the desired annotation 
 Annotation annotation = object.getAnnotation( CustomAnnotationClass.class ); 
  
 System.out.println( annotation ); 
  
 } 
 // the same for all methods of the class 
 for( Method method : object.getDeclaredMethods() ) 
 { 
  
 if( method.isAnnotationPresent( CustomAnnotationMethod.class ) ) 
 { 
  
 Annotation annotation = method.getAnnotation( CustomAnnotationMethod.class ); 
  
 System.out.println( annotation ); 
  
 } 
  
 } 
} 

輸出如下：

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

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

11. 注解中的繼承

注解在Java中可以使用繼承。這種繼承和普通的面向?qū)ο罄^承幾乎沒有共同點。

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

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

@Inherited 
@Retention(RetentionPolicy.RUNTIME) 
@Target(ElementType.TYPE) 
public @interface InheritedAnnotation 
{ 
  
} 

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

@InheritedAnnotation 
public class AnnotatedSuperClass 
{ 
  
 public void oneMethod() 
 { 
  
 } 
  
} 

一個子類繼承父類：

@InheritedAnnotation 
public class AnnotatedSuperClass 
{ 
  
 public void oneMethod() 
 { 
  
 } 
  
} 

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

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

輸出如下：

is true: true 
is true: true 

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

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

@InheritedAnnotation 
public interface AnnotatedInterface 
{ 
  
 public void oneMethod(); 
  
} 

一個實現(xiàn)了該接口的類：

public class AnnotatedImplementedClass implements AnnotatedInterface 
{ 
  
 @Override 
 public void oneMethod() 
 { 
  
 } 
  
} 

經(jīng)過 isAnnotationPresent() 方法測試：

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

結(jié)果如下：

is true: true 
is true: false 

這個結(jié)果說明繼承注解和接口在一起使用時，接口中的注解在實現(xiàn)類中：僅僅被忽略。實現(xiàn)類并不繼承接口的注解；接口繼承僅僅適用于類繼承。正如 AnnotatedSubClass。
@Inheriated注解僅在存在繼承關(guān)系的類上產(chǎn)生效果，在接口和實現(xiàn)類上并不工作。這條同樣也適用在方法，變量，包等等。只有類才和這個注解連用。

一條關(guān)于@Inheriated注解的很好的解釋在Javadoc中：http://docs.oracle.com/javase/7/docs/api/java/lang/annotation/Inherited.html.

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

Annotation type declaration cannot have explicit superinterfaces 

#p#

12. 使用注解的知名類庫

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

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

12.1. Junit

這個框架用于完成Java中的單元測試。自JUnit4開始，注解被廣泛應(yīng)用，成為Junit的設(shè)計的主干之一。

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

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

@Test：這個注解向JUnit說明這個被注解的方法一定是一個可執(zhí)行的測試方法。這個注解只能標(biāo)識在方法上，并且被JVM保留至運(yùn)行時。

@Test 
public void testMe() 
{ 
 //test assertions 
 assertEquals(1,1); 
} 

從這個例子可以看到我們?nèi)绾卧贘Unit中使用這類注解。

@Before：這個注解用來向JUnit說明被標(biāo)記的方法應(yīng)該在所有測試方法之前被執(zhí)行。這對于在測試之前設(shè)置測試環(huán)境和初始化非常有用。同樣只適用于方法上：

@Before 
public void setUp() 
 { 
 // initializing variables 
 count = 0; 
 init(); 
} 

@After：這個注解用來向JUnit說明被注解的方法應(yīng)該在所有單元測試之后執(zhí)行。這個注解通常用來銷毀資源，關(guān)閉，釋放資源或者清理，重置等工作。

@After 
public void destroy() 
{ 
 // closing input stream 
 stream.close(); 
} 

@Ignore：這個方法用來向JUnit說明被注解的方法應(yīng)該不被當(dāng)作測試單元執(zhí)行。即使它被注解成為一個測試方法，也只能被忽略。

@Ignore 
@Test 
public void donotTestMe() 
{ 
 count = -22; 
 System.out.println( "donotTestMe(): " + count ); 
} 

這個方法可能在在開發(fā)調(diào)試階段使用，但一旦開始進(jìn)入發(fā)布階段變需要將被忽略的代碼去掉。

@FixMethodOrder：指定執(zhí)行的順序，正常情況下Junit處理程序負(fù)責(zé)它按照完全隨機(jī)的無法預(yù)知的順序執(zhí)行。當(dāng)所有的測試方法都相互獨立的時候，不推薦使用這個注解。但是，當(dāng)測試的場景需要測試方法按照一定規(guī)則的時候，這個注解就派上用場了。

<span style="color: #888888;">還有一些測試套件和類庫使用了注解，例如Mockito和JMock，使用注解來創(chuàng)建測試對象和預(yù)期值。 查看JUnit中所有注解請參考：<span style="color: #888888;"><a href="https://github.com/junit-team/junit/wiki/Getting-started">https://github.com/junit-team/junit/wiki/Getting-started</a></span></span> 

12.2. Hibernate ORM

Hibernate可能是一個用得最廣泛的對象關(guān)系映射類庫。它提供了對象模型和關(guān)系型數(shù)據(jù)庫的映射框架。使用注解作為設(shè)計的一部分。

在本章我們將討論一兩個由Hibernate提供的注解并解釋它的處理程序如何處理它們。

下面的代碼段使用了@Entity和@Table。這兩個是用來向消費(fèi)器（Hibernate處理程序）說明被注解的類是一個實體類，以及它映射的SQL表名。實際上，這個注解僅僅是指明了主表，還可以有說明字表的注解。

@Entity 
@Table( name = "hibernate_annotated" ) 
public class HibernateAnnotated 

接下來的代碼段展示了如何向Hibernate處理程序說明被標(biāo)記的元素是表的主鍵，并映射名為“id”的列，并且主鍵是自動生成的。

@Id 
@GeneratedValue 
@Column( name = "id" ) 
private int id; 

為了指定標(biāo)準(zhǔn)的SQL表列名，我們可以寫如下注解：

@Column( name = "description" ) 
private String description; 

這說明被標(biāo)記的元素映射的是這個類所對應(yīng)的表中名為“description”的一列。

這些注解都來自 http://docs.oracle.com/javaee/6/api/javax/persistence/package-summary.html 企業(yè)級Java的包。它們幾乎涵蓋了所有 Hibernate 所有可用的注解。

12.3. Spring MVC

Spring是個被廣泛使用的Java企業(yè)級應(yīng)用框架。其一項重要的特性就是在Java程序使用依賴注入。

Spring使用注解作為XML（Spring的早期版本使用的基于XML配置）的一種替代方式?，F(xiàn)在兩者都是可行的。你可以使用XML文件或者注解配置你的項目。在我看來兩者都各有優(yōu)勢。

我們將在下例中展示兩個可用注解：

@Component 
public class DependencyInjectionAnnotation 
{ 
  
 private String description; 
  
 public String getDescription() 
 { 
 return description; 
 } 
  
 @Autowired 
 public void setDescription( String description ) 
 { 
 this.description = description; 
 } 
  
} 

在次代碼片段中我們可以找到兩個使用在了類和方法上的注解。

• @Component：說明被標(biāo)記的元素，在本例中是一個類，是一個自動檢測的目標(biāo)。這意味著被注解的類，將會被Spring容器實例化并管理。
• @Autowired：Spring容器將會嘗試通過類型（這是一種元素匹配機(jī)制）使用這個set方法來自動裝配。此注解也可以使用在構(gòu)造器和屬性上，Spring也會根據(jù)注解的地方不同采取不同的操作。

更多關(guān)于依賴注入和Spring框架的細(xì)節(jié)請參考：http://projects.spring.io/spring-framework/.

12.4. Findbugs

這是一個用來測量代碼質(zhì)量，并提供一系列可能提高它的工具。它會根據(jù)預(yù)定義（或者自定義）的違反規(guī)則來檢查代碼。Findbugs提供一系列注解來允許開發(fā)者來改變默認(rèn)行為。

它主要使用反射讀取代碼（和包含的注解）并決定基于它們，應(yīng)該采取什么行為。

一個列子是 edu.umd.cs.findbugs.annotations.SuppressFBWarnings 注解期待一種違反規(guī)定的鍵值并把它當(dāng)作參數(shù)。這非常像 java.lang.SuppressWarnings。被用來向 Findbugs 說明當(dāng)執(zhí)行代碼分析的時候，忽略指定的違反規(guī)則。

這是一個例子：

@SuppressFBWarnings( "HE_EQUALS_USE_HASHCODE" ) 
public class FindBugsAnnotated 
{ 
  
 @Override 
 public boolean equals( Object arg0 ) 
 { 
 return super.equals( arg0 ); 
 } 
  
} 

這個類已經(jīng)重現(xiàn)了 Object 的 equals 方法，但是并沒有重寫 hashCode 方法。這通常會導(dǎo)致問題，因為 hashCode 和 equals 兩者應(yīng)該被同時重寫，否則在使用這個對象作為 HashMap 的key值的時候會導(dǎo)致錯誤。所以，F(xiàn)indbugs會在違反規(guī)則報告中創(chuàng)造一個錯誤條目。

如果注解 @SuppressFBWarnings 設(shè)置了 HE_EQUALS_USE_HASHCODE 值以后，處理程序就不會在拋出這類型的錯誤了。

Bug: com.danibuiza.javacodegeeks.findbugsannotations.FindBugsAnnotated defines equals and uses Object.hashCode() 
Bug: com.danibuiza.javacodegeeks.findbugsannotations.FindBugsAnnotated defines equals and uses Object.hashCode() 

這個類重寫了 equals 方法，但是沒有重寫 hashCode 方法，繼承自 java.lang.Object 的 hashCode 方法（返回每個對象被JVM賦予的特定值）。因此，這個類幾乎違反了相同的對象必須 hashcode 相同的一致性。

如果你認(rèn)為這個類的實例不會插入到哈希表，推薦的做法是像這樣實現(xiàn) hashCode 方法：

public int hashCode() { 
 assert false : "hashCode not designed"; 
 return 42; // any arbitrary constant will do 
 } 
  
Rank: Troubling (14), confidence: High 
Pattern: HE_EQUALS_USE_HASHCODE 
Type: HE, Category: BAD_PRACTICE (Bad practice) 

這個錯誤包含了該問題的一種解釋并且提示如何處理它。在這種情況下，解決方案應(yīng)該是實現(xiàn) hashCode 方法。

想知道FindBugs在 SuppressFBWarnings 注解所有可用的違反規(guī)則設(shè)置，請參考：http://findbugs.sourceforge.net/bugDescriptions.html.

12.5. JAXB

JAXB是一個用來相互轉(zhuǎn)換和映射XML文件與Java對象的類庫。實際上，這個類庫與標(biāo)準(zhǔn)JRE一起提供，不需要任何額外的下載和配置?？梢灾苯油ㄟ^引入 java.xml.bind.annotation 包下的類直接使用。

JAXB使用注解來告知處理程序（或者是JVM）XML文件與代碼的相互轉(zhuǎn)化。例如，注解可以用來在代碼上標(biāo)記XML節(jié)點，XMl屬性，值等等。我們將看到一個例子：

首先，我們聲明一個類說明它應(yīng)該是XML文件中的一個節(jié)點：

import javax.xml.bind.annotation.XmlRootElement; 
import javax.xml.bind.annotation.XmlType; 
@XmlType( propOrder = { "brand", "model", "year", "km" } ) 
@XmlRootElement( name = "Car" ) 
class Car 
... 

使用注解@XmlType，@XmlRoootElement。它們用來告知 JAXB 處理程序 Car 這個類在轉(zhuǎn)換后，將會轉(zhuǎn)換成為XML中的一個節(jié)點。這個@XmlType說明了屬性在XML中的順序。JAXB將會基于這些注解執(zhí)行合適的操作。

除了分離的 getter 和 setter 屬性，再也不需要向這個類中添加其它東西來完成轉(zhuǎn)換?，F(xiàn)在我們需要一個消費(fèi)器程序來執(zhí)行轉(zhuǎn)換成XML：

Car car = new Car(); 
car.setBrand( "Mercedes" ); 
car.setModel( "SLK" ); 
car.setYear( 2011 ); 
car.setKm( 15000 ); 
  
Car carVW = new Car(); 
carVW.setBrand( "VW" ); 
carVW.setModel( "Touran" ); 
carVW.setYear( 2005 ); 
carVW.setKm( 150000 ); 
  
/* init jaxb marshaler */ 
JAXBContext jaxbContext = JAXBContext.newInstance( Car.class ); 
Marshaller jaxbMarshaller = jaxbContext.createMarshaller(); 
  
/* set this flag to true to format the output */ 
jaxbMarshaller.setProperty( Marshaller.JAXB_FORMATTED_OUTPUT, true ); 
  
/* marshaling of java objects in xml (output to standard output) */ 
jaxbMarshaller.marshal( car, System.out ); 
jaxbMarshaller.marshal( carVW, System.out ); 

程序產(chǎn)生的輸入如下：

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
02 
<Car> 
 <brand>Mercedes</brand> 
 <model>SLK</model> 
 <year>2011</year> 
 <km>15000</km> 
</Car> 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
<Car> 
 <brand>VW</brand> 
 <model>Touran</model> 
 <year>2005</year> 
 <km>150000</km> 
</Car> 

更多關(guān)于JAXB XML和Java 的轉(zhuǎn)換信息請參考：https://jaxb.java.net/

13. 總結(jié)

在這篇文檔中，我們解釋了Java注解是Java1.5開始一個非常重要的特性。基本上，注解都是作為包含代碼信息的元數(shù)據(jù)而被標(biāo)記到代碼中。它們不會改變或者影響代碼的任何意義，而是被第三方稱為消費(fèi)器的程序通過反射的方式使用。

我們列出了Java默認(rèn)的內(nèi)建注解，一些稱為元注解例如：@Target或者 @Retention，又有@Override，@SuppressWarnings，還有一些Java8相關(guān)的注解，比如：@Repeatable，@FunctionalInterface和類型注解。我們還展現(xiàn)了一兩個結(jié)合使用反射的例子，并描述了一些使用注解的類庫例如Spring， Junit，Hibernate。

注解是Java中一種分析元數(shù)據(jù)的強(qiáng)大機(jī)制，可以在不同的程序中擔(dān)任不同的作用，例如校驗，依賴注入，單元測試。

14. 下載

這是一個java注解的教程。

你可以從這里下載本教程所有代碼: customAnnotations

15. 資料

這是一些非常有用的關(guān)于Java注解的資料：

官方Java注解地址：http://docs.oracle.com/javase/tutorial/java/annotations/
維基百科中關(guān)于Java注解的解釋：http://en.wikipedia.org/wiki/Java_annotation
Java規(guī)范請求250：http://en.wikipedia.org/wiki/JSR_250
Oracle 注解白皮書：http://www.oracle.com/technetwork/articles/hunter-meta-096020.html
注解API：http://docs.oracle.com/javase/7/docs/api/java/lang/annotation/package-summary.html

原文鏈接：http://ifeve.com/java-annotations-tutorial/

原文作者：Dani Buiza 譯者：Toien Liu