當(dāng)前位置：首頁(yè) > 编程语言 > java >内容正文

java

Java 注解指导手册 – 终极向导

發(fā)布時(shí)間：2023/12/3 java 29 豆豆

生活随笔收集整理的這篇文章主要介紹了 Java 注解指导手册 – 终极向导小編覺得挺不錯(cuò)的,現(xiàn)在分享給大家,幫大家做個(gè)參考.

轉(zhuǎn)載自??Java 注解指導(dǎo)手冊(cè) – 終極向?qū)?/p>

譯文出處：?Toien Liu???原文出處：Dani Buiza

編者的話：注解是java的一個(gè)主要特性且每個(gè)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)于注解在不同類庫(kù)中的應(yīng)用，包括?Make?your?Spring?Security?@Secured?annotations?more?DRY和?Java?Annotations?&?A?Real?World?Spring?Example.

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

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

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

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

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

2. 介紹

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

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

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

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

3.消費(fèi)器

理解注解的目的以及如何使用它都會(huì)帶來(lái)困難，因?yàn)樽⒔獗旧聿⒉话魏喂δ苓壿?#xff0c;它們也不會(huì)影響自己注解的代碼，那么，它們到底為什么而存在呢？

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

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

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

4. 注解語(yǔ)法和元素

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

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

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

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

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

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

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

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

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

5. 在什么地方使用

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

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

@MyAnnotation String str = "danibuiza";

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

6. 使用案例

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

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

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

7. 內(nèi)建注解

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

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

@Retention：這個(gè)注解注在其他注解上，并用來(lái)說(shuō)明如何存儲(chǔ)已被標(biāo)記的注解。這是一種元注解，用來(lái)標(biāo)記注解并提供注解的信息。可能的值是：
- SOURCE：表明這個(gè)注解會(huì)被編譯器忽略，并只會(huì)保留在源代碼中。
- CLASS:表明這個(gè)注解會(huì)通過(guò)編譯駐留在CLASS文件，但會(huì)被JVM在運(yùn)行時(shí)忽略,正因?yàn)槿绱?其在運(yùn)行時(shí)不可見。
- RUNTIME：表示這個(gè)注解會(huì)被JVM獲取，并在運(yùn)行時(shí)通過(guò)反射獲取。

我們會(huì)在稍后展開幾個(gè)例子。

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

通常,編譯器會(huì)因?yàn)闆](méi)調(diào)用該方而產(chǎn)生警告;?用了注解抑制了這種行為。該注解需要一個(gè)或多個(gè)參數(shù)來(lái)指定抑制的警告類型。

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

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

8. Java 8 與注解

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

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

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

看一個(gè)使用的例子。首先我們創(chuàng)造一個(gè)能容納重復(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 {}

我們會(huì)得到編譯器的錯(cuò)誤信息：

Duplicate annotation of non-repeatable type

自Java8開始，我們可以在類型上使用注解。由于我們?cè)谌魏蔚胤蕉伎梢允褂妙愋?#xff0c;包括 new操作符，casting，implements，throw等等。注解可以改善對(duì)Java代碼的分析并且保證更加健壯的類型檢查。這個(gè)例子說(shuō)明了這一點(diǎn)：

@SuppressWarnings( "unused" ) public static void main( String[] args ) {// type def@TypeAnnotatedString cannotBeEmpty = null;// typeList<@TypeAnnotated String> myList = new ArrayList<String>();// valuesString 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：這個(gè)注解表示一個(gè)函數(shù)式接口元素。函數(shù)式接口是一種只有一個(gè)抽象方法（非默認(rèn)）的接口。編譯器會(huì)檢查被注解元素，如果不符，就會(huì)產(chǎn)生錯(cuò)誤。例子如下：

// implementing its methods @SuppressWarnings( "unused" ) MyCustomInterface myFuncInterface = new MyCustomInterface() {@Overridepublic 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 ); }

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

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

9. 自定義注解

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

public @interface CustomAnnotationClass

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

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

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

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

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

之后，我們定義兩個(gè)注解的成員：

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

以上我們僅定義了默認(rèn)值為“danibuiza”的 author 屬性和沒(méi)有默認(rèn)值的date屬性。我們應(yīng)強(qiáng)調(diào)所有的方法聲明都不能有參數(shù)和throw子句。這個(gè)返回值的類型被限制為之前提過(guò)的字符串，類，枚舉，注解和存儲(chǔ)這些類型的數(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）是最重要的兩個(gè)。

10. 獲取注解

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

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

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

現(xiàn)在，我們將看一個(gè)怎么讀取注解的例子：
我們寫一個(gè)程序，從一個(gè)類和它的方法中讀取所有的存在的注解：

public static void main( String[] args ) throws Exception {Class<AnnotatedClass> object = AnnotatedClass.class;// Retrieve all annotations from the classAnnotation[] annotations = object.getAnnotations();for( Annotation annotation : annotations ){System.out.println( annotation );}// Checks if an annotation is presentif( object.isAnnotationPresent( CustomAnnotationClass.class ) ){// Gets the desired annotationAnnotation annotation = object.getAnnotation( CustomAnnotationClass.class );System.out.println( annotation );}// the same for all methods of the classfor( 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)

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

11. 注解中的繼承

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

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

我們通過(guò)一個(gè)例子更清楚地說(shuō)明。首先，我們定義一個(gè)自動(dòng)繼承的自定義注解。

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

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

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

一個(gè)子類繼承父類：

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

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

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

輸出如下：

is?true:?trueis?true:?true

我們可以看到子類雖然并沒(méi)有聲明注解，但還是被自動(dòng)地注解上了。

如果我們嘗試注解在一個(gè)接口中：

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

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

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

經(jīng)過(guò) isAnnotationPresent() 方法測(cè)試：

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

結(jié)果如下：

is true:?trueis true:?false

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

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

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

Annotation type declaration cannot have explicit superinterfaces

12. 使用注解的知名類庫(kù)

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

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

12.1. Junit

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

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

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

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

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

從這個(gè)例子可以看到我們?nèi)绾卧贘Unit中使用這類注解。
@Before：這個(gè)注解用來(lái)向JUnit說(shuō)明被標(biāo)記的方法應(yīng)該在所有測(cè)試方法之前被執(zhí)行。這對(duì)于在測(cè)試之前設(shè)置測(cè)試環(huán)境和初始化非常有用。同樣只適用于方法上：

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

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

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

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

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

這個(gè)方法可能在在開發(fā)調(diào)試階段使用，但一旦開始進(jìn)入發(fā)布階段變需要將被忽略的代碼去掉。
@FixMethodOrder：指定執(zhí)行的順序，正常情況下Junit處理程序負(fù)責(zé)它按照完全隨機(jī)的無(wú)法預(yù)知的順序執(zhí)行。當(dāng)所有的測(cè)試方法都相互獨(dú)立的時(shí)候，不推薦使用這個(gè)注解。但是，當(dāng)測(cè)試的場(chǎng)景需要測(cè)試方法按照一定規(guī)則的時(shí)候，這個(gè)注解就派上用場(chǎng)了。

還有一些測(cè)試套件和類庫(kù)使用了注解，例如Mockito和JMock，使用注解來(lái)創(chuàng)建測(cè)試對(duì)象和預(yù)期值。?

查看JUnit中所有注解請(qǐng)參考：https://github.com/junit-team/junit/wiki/Getting-started

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

12.2. Hibernate ORM

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

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

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

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

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

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

<span style="color: #000000;">為了指定標(biāo)準(zhǔn)的SQL表列名，我們可以寫如下注解：</span>

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

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

12.3. Spring MVC

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

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

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

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

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

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

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

12.4. Findbugs

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

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

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

這是一個(gè)例子：

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

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

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

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

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

如果你認(rèn)為這個(gè)類的實(shí)例不會(huì)插入到哈希表，推薦的做法是像這樣實(shí)現(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)

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

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

12.5. JAXB

JAXB是一個(gè)用來(lái)相互轉(zhuǎn)換和映射XML文件與Java對(duì)象的類庫(kù)。實(shí)際上，這個(gè)類庫(kù)與標(biāo)準(zhǔn)JRE一起提供，不需要任何額外的下載和配置。可以直接通過(guò)引入 java.xml.bind.annotation 包下的類直接使用。

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

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

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。它們用來(lái)告知 JAXB 處理程序 Car 這個(gè)類在轉(zhuǎn)換后，將會(huì)轉(zhuǎn)換成為XML中的一個(gè)節(jié)點(diǎn)。這個(gè)@XmlType說(shuō)明了屬性在XML中的順序。JAXB將會(huì)基于這些注解執(zhí)行合適的操作。

除了分離的 getter 和 setter 屬性，再也不需要向這個(gè)類中添加其它東西來(lái)完成轉(zhuǎn)換。現(xiàn)在我們需要一個(gè)消費(fèi)器程序來(lá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)換信息請(qǐng)參考：https://jaxb.java.net/

13. 總結(jié)

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

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

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

14. 下載

這是一個(gè)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ī)范請(qǐng)求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

創(chuàng)作挑戰(zhàn)賽新人創(chuàng)作獎(jiǎng)勵(lì)來(lái)咯，堅(jiān)持創(chuàng)作打卡瓜分現(xiàn)金大獎(jiǎng)

總結(jié)

以上是生活随笔為你收集整理的Java 注解指导手册 – 终极向导的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。

上一篇：罗技海外推出 Zone Wireless
下一篇： java美元兑换,（Java实现）美元

生活随笔