Java學習_註解

2020 年 12 月 29 日
筆記
JAVA

使用註解
- 註解是放在Java源碼的類、方法、欄位、參數前的一種特殊「注釋」。　
```
 1 // this is a component:
 2 @Resource("hello")
 3 public class Hello {
 4     @Inject
 5     int n;
 6 
 7     @PostConstruct
 8     public void hello(@Param String name) {
 9         System.out.println(name);
10     }
11 
12     @Override
13     public String toString() {
14         return "Hello";
15     }
16 }
```
  注釋會被編譯器直接忽略，註解則可以被編譯器打包進入class文件，因此，註解是一種用作標註的「元數據」。
- 從JVM的角度看，註解本身對程式碼邏輯沒有任何影響，如何使用註解完全由工具決定。
- Java的註解可以分為三類：
  - 第一類是由編譯器使用的註解，這類註解不會被編譯進入.class文件，它們在編譯後就被編譯器扔掉了。
    - @Override：讓編譯器檢查該方法是否正確地實現了覆寫；
    - @SuppressWarnings：告訴編譯器忽略此處程式碼產生的警告。
  - 第二類是由工具處理.class文件使用的註解，比如有些工具會在載入class的時候，對class做動態修改，實現一些特殊的功能。這類註解會被編譯進入.class文件，但載入結束後並不會存在於記憶體中。這類註解只被一些底層庫使用，一般我們不必自己處理。
  - 第三類是在程式運行期能夠讀取的註解，它們在載入後一直存在於JVM中，這也是最常用的註解。例如，一個配置了@PostConstruct的方法會在調用構造方法後自動被調用（這是Java程式碼讀取該註解實現的功能，JVM並不會識別該註解）。
- 定義一個註解時，還可以定義配置參數。配置參數可以包括：
  - 所有基本類型；
  - String；
  - 枚舉類型；
  - 基本類型、String、Class以及枚舉的數組。
- 因為配置參數必須是常量，所以，上述限制保證了註解在定義時就已經確定了每個參數的值。
- 註解的配置參數可以有默認值，缺少某個配置參數時將使用默認值。此外，大部分註解會有一個名為value的配置參數，對此參數賦值，可以只寫常量，相當於省略了value參數。如果只寫註解，相當於全部使用默認值。
```
public class Hello {
    @Check(min=0, max=100, value=55)
    public int n;

    @Check(value=99)
    public int p;

    @Check(99) // @Check(value=99)
    public int x;

    @Check
    public int y;
}
```
定義註解
- Java語言使用@interface語法來定義註解（Annotation），它的格式為：
```
public @interface Report {
    int type() default 0;
    String level() default "info";
    String value() default "";
}
```
  註解的參數類似無參數方法，可以用default設定一個默認值（強烈推薦）。最常用的參數應當命名為value。
- 有一些註解可以修飾其他註解，這些註解就稱為元註解（meta annotation）。Java標準庫已經定義了一些元註解，我們只需要使用元註解，通常不需要自己去編寫元註解。
- 最常用的元註解是@Target。使用@Target可以定義Annotation能夠被應用於源碼的哪些位置。
  - 類或介面：ElementType.TYPE；
  - 欄位：ElementType.FIELD；
  - 方法：ElementType.METHOD；
  - 構造方法：ElementType.CONSTRUCTOR；
  - 方法參數：ElementType.PARAMETER。
- 例如，定義註解@Report可用在方法上，我們必須添加一個@Target(ElementType.METHOD)。定義註解@Report可用在方法或欄位上，可以把@Target註解參數變為數組{ ElementType.METHOD, ElementType.FIELD }
```
@Target(ElementType.METHOD)
public @interface Report {
    int type() default 0;
    String level() default "info";
    String value() default "";
}
```
```
@Target({
    ElementType.METHOD,
    ElementType.FIELD
})
public @interface Report {
    ...
}
```
  實際上@Target定義的value是ElementType[]數組，只有一個元素時，可以省略數組的寫法。
- 另一個重要的元註解@Retention定義了Annotation的生命周期。
  - 僅編譯期：RetentionPolicy.SOURCE；
  - 僅class文件：RetentionPolicy.CLASS；
  - 運行期：RetentionPolicy.RUNTIME。

如果@Retention不存在，則該Annotation默認為CLASS。因為通常我們自定義的Annotation都是RUNTIME，所以，務必要加上@Retention(RetentionPolicy.RUNTIME)這個元註解。

@Repeatable這個元註解可以定義Annotation是否可重複。　　

@Repeatable(Reports.class)
@Target(ElementType.TYPE)
public @interface Report {
    int type() default 0;
    String level() default "info";
    String value() default "";
}

@Target(ElementType.TYPE)
public @interface Reports {
    Report[] value();
}

經過@Repeatable修飾後，在某個類型聲明處，就可以添加多個@Report註解：

@Report(type=1, level="debug")
@Report(type=2, level="warning")
public class Hello {
}

使用@Inherited定義子類是否可繼承父類定義的Annotation。@Inherited僅針對@Target(ElementType.TYPE)類型的annotation有效，並且僅針對class的繼承，對interface的繼承無效。

@Inherited
@Target(ElementType.TYPE)
public @interface Report {
    int type() default 0;
    String level() default "info";
    String value() default "";
}
在使用的時候，如果一個類用到了@Report：

@Report(type=1)
public class Person {
}
則它的子類默認也定義了該註解：

public class Student extends Person {
}

如何定義Annotation

 1 //第一步，用@interface定義註解：
 2 
 3 public @interface Report {
 4 }
 5 
 6 //第二步，添加參數、默認值：
 7 
 8 public @interface Report {
 9     int type() default 0;
10     String level() default "info";
11     String value() default "";
12 }
13 //把最常用的參數定義為value()，推薦所有參數都盡量設置默認值。
14 
15 //第三步，用元註解配置註解：
16 
17 @Target(ElementType.TYPE)
18 @Retention(RetentionPolicy.RUNTIME)
19 public @interface Report {
20     int type() default 0;
21     String level() default "info";
22     String value() default "";
23 }

其中，必須設置@Target和@Retention，@Retention一般設置為RUNTIME，因為我們自定義的註解通常要求在運行期讀取。一般情況下，不必寫@Inherited和@Repeatable。

處理註解
- SOURCE類型的註解主要由編譯器使用，因此我們一般只使用，不編寫。CLASS類型的註解主要由底層工具庫使用，涉及到class的載入，一般我們很少用到。只有RUNTIME類型的註解不但要使用，還經常需要編寫。
- Java提供的使用反射API讀取Annotation的方法包括：
  
  判斷某個註解是否存在於Class、Field、Method或Constructor：
  - Class.isAnnotationPresent(Class)
  - Field.isAnnotationPresent(Class)
  - Method.isAnnotationPresent(Class)
  - Constructor.isAnnotationPresent(Class)
```
// 判斷@Report是否存在於Person類:
Person.class.isAnnotationPresent(Report.class);    
```

　　　　　使用反射API讀取Annotation：

Class.getAnnotation(Class)
Field.getAnnotation(Class)
Method.getAnnotation(Class)

Constructor.getAnnotation(Class)

// 獲取Person定義的@Report註解:
Report report = Person.class.getAnnotation(Report.class);
int type = report.type();
String level = report.level();

使用反射API讀取Annotation有兩種方法。方法一是先判斷Annotation是否存在，如果存在，就直接讀取。　

Class cls = Person.class;
if (cls.isAnnotationPresent(Report.class)) {
    Report report = cls.getAnnotation(Report.class);
    ...
}

第二種方法是直接讀取Annotation，如果Annotation不存在，將返回null。

Class cls = Person.class;
Report report = cls.getAnnotation(Report.class);
if (report != null) {
   ...
}

讀取方法、欄位和構造方法的Annotation和Class類似。但要讀取方法參數的Annotation就比較麻煩一點，因為方法參數本身可以看成一個數組，而每個參數又可以定義多個註解，所以，一次獲取方法參數的所有註解就必須用一個二維數組來表示。例如，對於以下方法定義的註解。

public void hello(@NotNull @Range(max=5) String name, @NotNull String prefix) {
}

要讀取方法參數的註解，我們先用反射獲取Method實例，然後讀取方法參數的所有註解。

// 獲取Method實例:
Method m = ...
// 獲取所有參數的Annotation:
Annotation[][] annos = m.getParameterAnnotations();
// 第一個參數（索引為0）的所有Annotation:
Annotation[] annosOfName = annos[0];
for (Annotation anno : annosOfName) {
    if (anno instanceof Range) { // @Range註解
        Range r = (Range) anno;
    }
    if (anno instanceof NotNull) { // @NotNull註解
        NotNull n = (NotNull) anno;
    }
}

使用註解

註解如何使用，完全由程式自己決定。例如，JUnit是一個測試框架，它會自動運行所有標記為@Test的方法。

來看一個@Range註解，我們希望用它來定義一個String欄位的規則：欄位長度滿足@Range的參數定義。

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface Range {
    int min() default 0;
    int max() default 255;
}

在某個JavaBean中，我們可以使用該註解：

public class Person {
    @Range(min=1, max=20)
    public String name;

    @Range(max=10)
    public String city;
}

但是，定義了註解，本身對程式邏輯沒有任何影響。我們必須自己編寫程式碼來使用註解。這裡，我們編寫一個Person實例的檢查方法，它可以檢查Person實例的String欄位長度是否滿足@Range的定義：

void check(Person person) throws IllegalArgumentException, ReflectiveOperationException {
    // 遍歷所有Field:
    for (Field field : person.getClass().getFields()) {
        // 獲取Field定義的@Range:
        Range range = field.getAnnotation(Range.class);
        // 如果@Range存在:
        if (range != null) {
            // 獲取Field的值:
            Object value = field.get(person);
            // 如果值是String:
            if (value instanceof String) {
                String s = (String) value;
                // 判斷值是否滿足@Range的min/max:
                if (s.length() < range.min() || s.length() > range.max()) {
                    throw new IllegalArgumentException("Invalid field: " + field.getName());
                }
            }
        }
    }
}

這樣一來，我們通過@Range註解，配合check()方法，就可以完成Person實例的檢查。注意檢查邏輯完全是我們自己編寫的，JVM不會自動給註解添加任何額外的邏輯。

Tags: JAVA