Java 注解類型 · Programiz 中文系列教程

# Java 注解類型 > 原文： [https://www.programiz.com/java-programming/annotation-types](https://www.programiz.com/java-programming/annotation-types) #### 在本教程中，我們將借助示例學習不同類型的 Java 注解。 Java 注解是程序源代碼的元數據（有關數據的數據）。 Java SE 提供了幾個預定義的注解。此外，我們還可以根據需要創建自定義注解。如果您不知道什么是注解，請訪問 [Java 注解](/java-programming/annotations "Java Annotations")教程。這些注解可以分類為： 1\. **預定義的注解** * `@Deprecated` * `@Override` * `@SuppressWarnings` * `@SafeVarargs` * `@FunctionalInterface` 2\. **自定義注解** 3\. **元注解** * `@Retention` * `@Documented` * `@Target` * `@Inherited` * `@Repeatable` * * * ## 預定義的注解類型 ### 1\. `@Deprecated` `@Deprecated`注解是標記注解，指示不贊成使用元素（類，方法，字段等），并已用較新的元素替換。其語法為： ```java @Deprecated accessModifier returnType deprecatedMethodName() { ... } ``` 當程序使用已聲明為已棄用的元素時，編譯器將生成警告。我們使用 Javadoc `@deprecated`標記來記錄已棄用的元素。 ```java /** * @deprecated * why it was deprecated */ @Deprecated accessModifier returnType deprecatedMethodName() { ... } ``` ### 示例 1：`@Deprecated`注解示例 ```java class Main { /** * @deprecated * This method is deprecated and has been replaced by newMethod() */ @Deprecated public static void deprecatedMethod() { System.out.println("Deprecated method"); } public static void main(String args[]) { deprecatedMethod(); } } ``` **輸出** ```java Deprecated method ``` * * * ### 2\. @Override `@Override`注解指定子類的方法使用相同的方法名稱，返回類型和參數列表覆蓋超類的方法。覆蓋方法時，并非必須使用`@Override`。但是，如果使用它，則在覆蓋該方法時，如果出現錯誤（例如錯誤的參數類型），則編譯器將給出錯誤。 ### 示例 2：`@Override`注解示例 ```java class Animal { // overridden method public void display(){ System.out.println("I am an animal"); } } class Dog extends Animal { // overriding method @Override public void display(){ System.out.println("I am a dog"); } public void printMessage(){ display(); } } class Main { public static void main(String[] args) { Dog dog1 = new Dog(); dog1.printMessage(); } } ``` **輸出** ```java I am a dog ``` 在此示例中，通過使`Dog`類的對象`dog1`，我們可以調用其方法`printMessage()`，該方法然后執行`display()`語句。由于在兩個類中都定義了`display()`，因此`Dog`子類的方法將覆蓋`Animal`超類的方法。因此，將調用子類的`display()`。 * * * ### 3\. @SuppressWarnings 顧名思義，`@SuppressWarnings`注解指示編譯器禁止在程序執行時生成警告。我們可以指定要取消的警告類型。可以禁止的警告是特定于編譯器的，但有兩類警告：**棄用**和**未選中**。為了禁止顯示特定類別的警告，我們使用： ```java @SuppressWarnings("warningCategory") ``` 例如， ```java @SuppressWarnings("deprecated") ``` 為了禁止顯示多類警告，我們使用： ```java @SuppressWarnings({"warningCategory1", "warningCategory2"}) ``` 例如： ```java @SuppressWarnings({"deprecated", "unchecked"}) ``` 類別`deprecated`指示編譯器在使用不推薦使用的元素時禁止顯示警告。類別`unchecked`指示編譯器在使用原始類型時禁止顯示警告。并且，未定義的警告將被忽略。例如， ```java @SuppressWarnings("someundefinedwarning") ``` ### 示例 3：`@SuppressWarnings`注解示例 ```java class Main { @Deprecated public static void deprecatedMethod() { System.out.println("Deprecated method"); } @SuppressWarnings("deprecated") public static void main(String args[]) { Main depObj = new Main(); depObj. deprecatedMethod(); } } ``` **輸出**： ```java Deprecated method ``` 在這里，`deprecatedMethod()`已被標記為已棄用，并且在使用時會發出編譯器警告。通過使用`@SuppressWarnings("deprecated")`注解，我們可以避免編譯器警告。 * * * ### 4\. `@SafeVarargs` `@SafeVarargs`注解斷言，帶注解的方法或構造器不會對其可變參數（可變數量的參數）執行不安全的操作。我們只能在不能被覆蓋的方法或構造器上使用此注解。這是因為覆蓋它們的方法可能執行不安全的操作。在 Java 9 之前，我們只能在`final`或`static`方法上使用此注解，因為它們不能被覆蓋。現在，我們也可以將此注解用于私有方法。 ### 示例 4：`@SafeVarargs`注解示例 ```java import java.util.*; class Main { private void displayList(List<String>... lists) { for (List<String> list : lists) { System.out.println(list); } } public static void main(String args[]) { Main obj = new Main(); List<String> universityList = Arrays.asList("Tribhuvan University", "Kathmandu University"); obj.displayList(universityList); List<String> programmingLanguages = Arrays.asList("Java", "C"); obj.displayList(universityList, programmingLanguages); } } ``` **警告** ```java Type safety: Potential heap pollution via varargs parameter lists Type safety: A generic array of List<String> is created for a varargs parameter ``` **輸出**： ```java Note: Main.java uses unchecked or unsafe operations. [Tribhuvan University, Kathmandu University] [Tribhuvan University, Kathmandu University] [Java, C] ``` 在這里，`List ... lists`指定類型為`List`的變長參數。這意味著方法`displayList()`可以具有零個或多個參數。上面的程序編譯沒有錯誤，但是當不使用`@SafeVarargs`注解時會發出警告。在上面的示例中使用`@SafeVarargs`注解時， ```java @SafeVarargs private void displayList(List<String>... lists) { ... } ``` 我們得到相同的輸出，但沒有任何警告。當使用此注解時，非受檢的警告也會被刪除。 * * * ### 5\. @FunctionalInterface Java 8 首先引入了此`@FunctionalInterface`注解。該注解指示使用它的類型聲明是一個函數式接口。一個函數式接口只能有一個抽象方法。 ### 示例 5：`@FunctionalInterface`注解示例 ```java @FunctionalInterface public interface MyFuncInterface{ public void firstMethod(); // this is an abstract method } ``` 如果我們添加另一個抽象方法，那么說 ```java @FunctionalInterface public interface MyFuncInterface{ public void firstMethod(); // this is an abstract method public void secondMethod(); // this throws compile error } ``` 現在，當我們運行程序時，我們將收到以下警告： ```java Unexpected @FunctionalInterface annotation @FunctionalInterface ^ MyFuncInterface is not a functional interface multiple non-overriding abstract methods found in interface MyFuncInterface ``` 使用`@FunctionalInterface`注解不是強制性的。編譯器會將滿足函數式接口定義的任何接口視為函數式接口。我們使用此注解來確保函數式接口只有一種抽象方法。但是，由于它們具有實現，因此可以具有任意數量的默認方法和靜態方法。 ```java @FunctionalInterface public interface MyFuncInterface{ public void firstMethod(); // this is an abstract method default void secondMethod() { ... } default void thirdMethod() { ... } } ``` * * * ## 自定義注解也可以創建我們自己的自定義注解。它的語法是： ```java [Access Specifier] @interface<AnnotationName> { DataType <Method Name>() [default value]; } ``` 這是您需要了解的有關自定義注解的信息： * 可以通過使用`@interface`和注解名稱來創建注解。 * 注解可以具有看起來像方法的元素，但是它們沒有實現。 * 默認值是可選的。參數不能為空值。 * 方法的返回類型可以是原始，枚舉，字符串，類名或這些類型的數組。 ### 示例 6：自定義注解示例 ```java @interface MyCustomAnnotation { String value() default "default value"; } class Main { @MyCustomAnnotation(value = "programiz") public void method1() { System.out.println("Test method 1"); } public static void main(String[] args) throws Exception { Main obj = new Main(); obj.method1(); } } ``` **輸出**： ```java Test method 1 ``` * * * ## 元注解元注解是應用于其他注解的注解。 ### 1\. `@Retention` `@Retention`注解指定注解可以使用的級別。它的語法是： ```java @Retention(RetentionPolicy) ``` 保留策略有 3 種類型： * **`RetentionPolicy.SOURCE`** - 注解僅在源級別可用，并且被編譯器忽略。 * **`RetentionPolicy.CLASS`** - 注解在編譯時可供編譯器使用，但被 Java 虛擬機（JVM）忽略。 * **`RetentionPolicy.RUNTIME`** - 注解可用于 JVM。例如： ```java @Retention(RetentionPolicy.RUNTIME) public @interface MyCustomAnnotation{ ... } ``` * * * ### 2\. `@Documented` 默認情況下，自定義注解不包含在[官方 Java 文檔](https://www.oracle.com/technetwork/articles/java/index-137868.html)中。為了將注解包含在 Javadoc 文檔中，我們使用`@Documented`注解。例如： ```java @Documented public @interface MyCustomAnnotation{ ... } ``` * * * ### 3\. `@Target` 我們可以使用`@Target`注解將注解限制為應用于特定目標。它的語法是： ```java @Target(ElementType) ``` `ElementType`可以具有以下類型之一： | 元素類型 | 目標 | | --- | --- | | `ElementType.ANNOTATION_TYPE` | 注解類型 | | `ElementType.CONSTRUCTOR` | 構造器 | | `ElementType.FIELD` | 字段 | | `ElementType.LOCAL_VARIABLE` | 局部變量 | | `ElementType.METHOD` | 方法 | | `ElementType.PACKAGE` | 包 | | `ElementType.PARAMETER` | 參數 | | `ElementType.TYPE` | 任何類元素 | 例如： ```java @Target(ElementType.METHOD) public @interface MyCustomAnnotation{ ... } ``` 在此示例中，我們僅將此注解的使用限制為方法。 **注意**：如果未定義目標類型，則注解可用于任何元素。 * * * ### 4\. `@Inherited` 默認情況下，注解類型不能從超類繼承。但是，如果需要將注解從超類繼承到子類，則可以使用`@Inherited`注解。它的語法是： ```java @Inherited ``` 例如： ```java @Inherited public @interface MyCustomAnnotation { ... } @MyCustomAnnotation public class ParentClass{ ... } public class ChildClass extends ParentClass { ... } ``` * * * ### 5\. `@Repeatable` 由`@Repeatable`標記的注解可以多次應用于同一聲明。 ```java @Repeatable(Universities.class) public @interface University { String name(); } ``` `@Repeatable`注解中定義的值是容器注解。容器注解具有上述可重復注解的數組類型的變量`value`。在此，`Universities`是包含注解的類型。 ```java public @interface Universities { University[] value(); } ``` 現在，`@University`注解可以在同一聲明中多次使用。 ```java @University(name = "TU") @University(name = "KU") private String uniName; ``` * * * 如果需要檢索注解數據，則可以使用 [Reflection API](/java-programming/reflection "Java Reflection") 。要檢索注解值，我們使用在反射 API 中定義的`getAnnotationsByType()`或`getAnnotations()`方法。