快捷導(dǎo)航

全面解析Java中的注解與注釋

更新時(shí)間：2016年05月05日 08:59:11 作者：oscar999

這篇文章主要介紹了Java中的注解與注釋,簡單來說注解以@符號開頭而注釋被包含在/***/符號中,各自具體的作用則來看本文詳解,需要的朋友可以參考下

注解
一、什么是 Annotation？（注解 or 注釋）
Annotation, 準(zhǔn)確的翻譯應(yīng)該是 -- 注解。和注釋的作用完全不一樣。
Annotation 是JDK5.0及以后版本引入的一個(gè)特性。與類、接口、枚舉是在同一個(gè)層次，可以成為java 的一個(gè)類型。
語法是以@ 開頭
簡單來說，
注釋是程序員對源代碼的類，方法，屬性等做的一些記憶或提示性描述(比如這個(gè)方法是做什么用的)，是給人來看的。
注解則是Java 編譯器可以理解的部分，是給編譯器看的。
舉個(gè)簡單的例子來看一下注解的使用和作用。
@Override 是比較常見的Java 內(nèi)置注解，它的作用就是在編譯代碼的時(shí)候檢查子類中定義的方法是否正確。

package annotation; 
 
public abstract class Animal { 
 
  public abstract void eat(); 
} 

package annotation; 
 
public class Cat extends Animal{ 
 
  @Override 
  public void eat(String food) {  
  } 
}

這里在子類Cat中 eat 方法被注解為覆寫父類的方法，但是卻比父類方法多出一個(gè)參數(shù)。
如果是在Eclipse 在編輯的話，直接就會有紅色叉叉提示。(代碼編譯會通不過)。
如果去掉@Override的注解的話，編譯沒問題，但是Cat 中eat方法就是這個(gè)類的一個(gè)新的方法了，而不是從父類繼承的了。

二、常見的Java 內(nèi)置注解
包含@Override ，還有哪些常見的Java內(nèi)置注解？
1. @Deprecated
注解為不建議使用，可以用在方法和類上。
基本上這種方法和類都是因?yàn)樯壔蛐阅苌厦娴囊恍┰驈U棄不建議使用，但是為了兼容或其他原因，還必須保留。
所以就打上這個(gè)注解。
在Java 本身的API中就有很多這樣的例子，方法打上了這個(gè)注解，進(jìn)到Source code 會看到替代的新的方法是哪個(gè)。
在eclipse 中編寫code時(shí)，添加此注解的方法在聲明和調(diào)用的地方都會加上刪除線。

2.@Override

3.@SuppressWarnings
忽略警告。
如果你的code在轉(zhuǎn)型或其他的部分有一些警告的話，但是你又想忽略這些警告，就可以使用這個(gè)注解了。
1)deprecation 使用了不贊成使用的類或方法時(shí)的警告

2)unchecked 執(zhí)行了未檢查的轉(zhuǎn)換時(shí)警告

3)fallthrough 當(dāng)使用switch操作時(shí)case后未加入break操作，而導(dǎo)致程序繼續(xù)執(zhí)行其他case語句時(shí)出現(xiàn)的警告

4)path 當(dāng)設(shè)置一個(gè)錯(cuò)誤的類路徑、源文件路徑時(shí)出現(xiàn)的警告

5)serial 當(dāng)在可序列化的類上缺少serialVersionUID定義時(shí)的警告

6)fianally 任何finally子句不能正常完成時(shí)警告

7)all 關(guān)于以上所有情況的警告

三、自定義注解
除了Java本身提供的內(nèi)置注解， Java 還提供了定制自定義注解的功能。
定義的方式就是使用注解定義注解，用來定義注解的注解稱為元注解。
主要的元注解有以下四個(gè)：@Target ；@Retention；@Documented；@Inherited
1. @Target 表示該注解用于什么地方，使用在類上，方法上，或是屬性等
可能的 ElemenetType 參數(shù)包括：
ElemenetType.CONSTRUCTOR 構(gòu)造器聲明
ElemenetType.FIELD 域聲明（包括 enum 實(shí)例）
ElemenetType.LOCAL_VARIABLE 局部變量聲明
ElemenetType.METHOD 方法聲明
ElemenetType.PACKAGE 包聲明
ElemenetType.PARAMETER 參數(shù)聲明
ElemenetType.TYPE 類，接口（包括注解類型）或enum聲明
2. @Retention 表示在什么級別保存該注解信息
可選的 RetentionPolicy 參數(shù)包括：
RetentionPolicy.SOURCE 注解將被編譯器丟棄
RetentionPolicy.CLASS 注解在class文件中可用，但會被VM丟棄
RetentionPolicy.RUNTIME VM將在運(yùn)行期也保留注釋，因此可以通過反射機(jī)制讀取注解的信息。
3. @Documented ，產(chǎn)生doc時(shí)，是否包含此注解
將此注解包含在 javadoc 中
4. @Inherited
允許子類繼承父類中的注解
看一些簡單定義的例子：

package annotation; 
 
import java.lang.annotation.Documented; 
import java.lang.annotation.ElementType; 
import java.lang.annotation.Inherited; 
import java.lang.annotation.Retention; 
import java.lang.annotation.RetentionPolicy; 
import java.lang.annotation.Target; 
 
@Target(ElementType.METHOD) 
public @interface MyAnnotation { 
  String value(); 
} 
 
@Retention(RetentionPolicy.SOURCE)  
@interface MyAnnotation1 { }  
 
@Retention(RetentionPolicy.CLASS)  
@interface MyAnnotation2 {}  
 
@Retention(RetentionPolicy.RUNTIME)  
@interface MyAnnotation3 {} 
 
 
@Documented 
@interface MyAnnotation4 {} 
       
@Inherited 
@interface MyAnnotation5 { }

四、使用例子：

package annotation; 
 
import java.lang.annotation.Annotation; 
 
@MyAnnotation3 
public class TestAnnotation { 
  public static void main(String[] args) { 
    // TODO Auto-generated method stub 
    Annotation annotation = TestAnnotation.class.getAnnotation(MyAnnotation3.class); 
    System.out.println(annotation.toString()); 
  } 
 
}

打印出結(jié)果： @annotation.MyAnnotation3()
以上例子如果替換使用 MyAnnotation1 和 MyAnnotation2 的話，則取到的annotation的值為空，這就是RetentionPolicy 不同的差別。

五、Annotation的作用

介紹到此，可以總結(jié)一下Annotation的作用了。
基礎(chǔ)的大致可以分為三類:
1. 編寫文檔
2. 代碼分析
3. 編譯檢查
但是，開源框架對其賦予了更多的作用
比如：
Hibernate,注解配置，

@Column("aa") 
private String xx;

這個(gè)類似于XML配置，簡化程序中的配置
相對與把一部分元數(shù)據(jù)從XML文件移到了代碼本身之中，在一個(gè)地方管理和維護(hù)。
內(nèi)部如何實(shí)現(xiàn)的？ -- java 反射機(jī)制，類似與以上例子。

注釋
雖然注解、注釋只相差一個(gè)字，但是用法就差異很大。
還是那句話，注解給編譯器看，注釋是給人看的。
基于此的話，對于一個(gè)方法來說：
1. 把這個(gè)方法的作用，輸入，輸出描述清楚就可以了，更多的可以加上一些作者呀，版本呀這樣一些信息
2. 注釋編排的美觀一些
做到這兩點(diǎn)應(yīng)該就可以了。舉個(gè)例子：

/******************************************************************************* 
* NAME:     usage 
* DESCRIPTION: XXX 
* ARGUMENTS:  N/A 
* RETURN:    
* AUTHOR:    oscar999 
* VERSION:   V0.1 
*******************************************************************************/

看上去這是一個(gè)不錯(cuò)的注釋^^.

但是對于Java 語言來說，注釋被賦予了更多的功能。就是你可以使用javadoc 這個(gè)功能把代碼中的注釋導(dǎo)出到 html 的文件中。
如果你的代碼是共用性很高的代碼的話，這份文檔就是一份API的參考文檔，類似Java API.
所以，要產(chǎn)生出這樣的文檔，就要遵循java 定義的一些注釋規(guī)范，才能產(chǎn)生出規(guī)范的文檔出來。

一、Java 類方法的標(biāo)準(zhǔn)注釋
還是從類的方法的注釋說起。

  /** 
   * Read a line of text. A line is considered to be terminated by any one 
   * of a line feed ('\n'), a carriage return ('\r'), or a carriage return 
   * followed immediately by a linefeed. 
   * 
   * @param   ignoreLF1 If true, the next '\n' will be skipped 
<pre code_snippet_id="74911" snippet_file_name="blog_20131120_2_8365599" name="code" class="java">   * @param   ignoreLF2 If true, the next '\n' will be skipped</pre>   *   * @return   A String containing the contents of the line, not including   *       any line-termination characters, or null if the end of the   *       stream has been reached   *   * @see    java.io.LineNumberReader#readLine()   *   * @exception IOException If an I/O error occurs   */

（不去關(guān)注以上注釋的意義，只關(guān)注其定義的樣式）
1. 首先看最上面的 “Read a line of text. A line .. ” 這一段是對這個(gè)方法的一些描述。

20165585332304.png (769×180)

第一個(gè)句號前面的部分，也就是 “Read a line of text.” 會出現(xiàn)在 “方法摘要” 中

20165585353857.png (915×339)

2. @param 定義的是方法的輸入?yún)?shù)，（可以添加多個(gè)）出現(xiàn)在“ 方法詳細(xì)信息” 中。（參數(shù)和參數(shù)描述之間使用空格隔開，在產(chǎn)生的文檔中轉(zhuǎn)成了 -）

20165585411819.png (757×333)

3. @return 返回值的描述
4. @see 參考的描述
5. @exception 異常拋出的描述
美觀考慮，不同類的標(biāo)簽可以換一行顯示，比如 @param 和 @return 直接空一行。

二、Java 類標(biāo)準(zhǔn)注釋
類的注釋和方法注釋的格式基本相同。區(qū)別的地方：
1. 放置的位置不同。類的注釋放在類定義的上面，方法的注釋放在方法定義的上面。
2. 類的注釋比較會使用 @version @author @since 這樣的標(biāo)簽。
看模板

/** will buffer the input from the specified file. Without buffering, each 
* invocation of read() or readLine() could cause bytes to be read from the 
* file, converted into characters, and then returned, which can be very 
* inefficient. 
* 
* 
* Test Description 
* 
* <p> Programs that use DataInputStreams for textual input can be localized by 
* replacing each DataInputStream with an appropriate BufferedReader. 
* 
* @see FileReader 
* @see InputStreamReader 
* 
* @version 0.1, 11/20/13 
* @author  oscar999 
* @since  JDK1.5 
*/

doc 中顯示的效果是：
同樣，描述的第一句出現(xiàn)在“類概要”中。

20165585453559.png (624×78)