JAVA 7 to 17 TypeAnnotations

一、前言

返回目錄

在 Java 程式語言中，註解 (Annotations) 是一種為程式碼添加元資料 (Metadata) 的機制，它能夠在編譯時期或執行時期提供關於程式碼的額外資訊。Java 5 引入了註解，主要用於類別、方法、欄位等宣告上。Java 8 擴展了註解的應用範圍，允許將註解應用於型別 (Type) 上，這被稱為「型別上的註解 (Type Annotations)」。這個新特性提供了更強大的靜態分析能力，可以讓編譯器或程式碼分析工具檢查更深層次的程式碼問題。從 Java 8 到 Java 17，雖然型別上的註解的概念沒有根本性的改變，但其使用場景和應用工具更加豐富。本文將梳理 Java 7 至 Java 17 中關於型別上的註解的新特性，以便讀者更好地理解和應用它們。

目錄

• 一、前言
  • 目錄
• 二、Java 7 及之前的註解 (Annotations)
• 三、Java 8：型別上的註解 (Type Annotations) 的引入
• 四、型別上的註解的發展與應用
• 五、型別上註解 (Type Annotations) 的應用範例
• 六、總結

二、Java 7 及之前的註解 (Annotations)

返回目錄

在 Java 7 及之前，註解主要應用於以下幾個方面：

1. 類別宣告： 使用 @ 符號加上註解名稱，標註在類別定義之前。例如： @Deprecated public class MyClass { ... } 。
2. 方法宣告： 使用 @ 符號加上註解名稱，標註在方法定義之前。例如： @Override public void myMethod() { ... } 。
3. 欄位宣告： 使用 @ 符號加上註解名稱，標註在欄位定義之前。例如： @NotNull private String name; 。
4. 參數宣告： 使用 @ 符號加上註解名稱，標註在方法參數之前。例如： public void process(@NotNull String input) { ... } 。
5. 區域變數宣告： 使用 @ 符號加上註解名稱，標註在區域變數之前。例如： @SuppressWarnings("unused") int myVariable; 。

這些註解主要用於以下目的：

• 編譯器檢查： 例如 @Override 用於檢查方法是否正確覆寫父類別的方法。
• 程式碼分析： 例如 @Deprecated 用於標記過時的程式碼，方便工具進行分析。
• 程式碼生成： 有些註解可以被程式碼生成工具使用，例如一些 ORM (Object-Relational Mapping) 框架會使用註解來生成資料庫的相關程式碼。

三、Java 8：型別上的註解 (Type Annotations) 的引入

返回目錄

Java 8 引入了型別上的註解，擴展了註解的應用範圍，允許將註解應用於以下這些地方：

1. 泛型型別參數 (Generic Type Arguments)：

   • 在泛型型別參數中使用註解。例如： List<@NonNull String> names; 。
   • 這使得你可以對泛型型別進行額外的限制或檢查。

2. 泛型型別宣告 (Generic Type Declaration)：

   • 在泛型型別宣告時使用註解。例如： class MyClass<@NotBlank T> { ... } 。
   • 這可以標記類型，例如 NotNull , NotBlank 等。

3. 陣列型別 (Array Types)：

   • 在陣列的型別上使用註解。例如： @NotBlank String[] names;
   • 注意: 這裡的註解是加在 陣列的型別 上，而不是加在 [] 前面，用以表示這個陣列的元素，都被標記為 @NotBlank 。

4. 型別轉換 (Type Casts)：

   • 在型別轉換時使用註解。例如： myObject = (@NonEmpty List) myObject 。

5. this 關鍵字：

   • 在 this 關鍵字上使用註解。例如： public void method(@NotBlank MyClass this){...} 。

6. 方法的回傳型別 (Return Type)：

   • 在方法的回傳型別使用註解。 例如: @NotBlank List<String> process() 。

型別上的註解主要用於以下目的：

• 更強大的靜態分析： 允許靜態分析工具或編譯器檢查更複雜的型別約束，例如非空性 (Nullability)、非空字串、類型別名等。
• 更好的程式碼品質： 透過型別上的註解，可以在編譯時期檢查出更多潛在的錯誤，減少執行時期的錯誤發生。
• 程式碼自我說明： 註解可以讓程式碼更具表達力，更清楚地說明程式碼的設計意圖。

四、型別上的註解的發展與應用

返回目錄

從 Java 9 到 Java 17，型別上的註解的概念本身沒有改變，但其使用場景和應用工具更加成熟和普及。

• 與 JSR 305 的整合： javax.annotation 或其他第三方框架中提供的註解可以應用於型別上，提供更精細的空值檢查功能。
• 與程式碼分析工具的整合： 越來越多的靜態分析工具 (例如：FindBugs、Checkstyle、SpotBugs) 支援型別上的註解，提供更深入的程式碼分析和檢查。
• 與程式碼生成工具的整合: 一些程式碼產生工具會使用型別上的註解來生成更多程式碼或文件資訊。
• 與框架的整合: 一些框架可能會使用型別上的註解，來提供更豐富的功能。 例如 Spring 框架可以使用 JSR 305 的 @Nullable 和 @Nonnull 。

這些變化讓型別上的註解在實務開發中更加實用，能夠在編譯時期就幫助開發者發現更多的問題，提高程式碼的可靠性。

五、型別上註解 (Type Annotations) 的應用範例

返回目錄

我們自行定義註解，Annotation Processor 編譯器插件，通過編譯時來確認型別註解的功用：

1. OnlyString.java (自訂 @OnlyString 註解)

   import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; @Target({ElementType.TYPE_USE, ElementType.FIELD, ElementType.PARAMETER}) @Retention(RetentionPolicy.SOURCE) public @interface OnlyString { }

2. OnlyStringProcessor.java (自訂 Annotation Processor 編譯器插件)

   import javax.annotation.processing.*; import javax.lang.model.SourceVersion; import javax.lang.model.element.*; import javax.lang.model.type.TypeMirror; import javax.tools.Diagnostic; import java.util.Set; @SupportedAnnotationTypes("OnlyString") @SupportedSourceVersion(SourceVersion.RELEASE_17) public class OnlyStringProcessor extends AbstractProcessor { @Override public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) { for (TypeElement annotation : annotations) { for (Element element : roundEnv.getElementsAnnotatedWith(annotation)) { TypeMirror typeMirror = element.asType(); String strTypeMirror = typeMirror.toString(); Name paramName = element.getSimpleName(); ExecutableElement method = (ExecutableElement) element.getEnclosingElement(); // if (!typeMirror.toString().equals("java.lang.String")) { if (!strTypeMirror.contains(" java.lang.String")) { processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, String.format("檢查到方法 %s 的參數 %s 為 %s 型別，只能將 @OnlyString 使用於 java.lang.String 型別。", method.getSimpleName(), paramName, strTypeMirror)); } else { processingEnv.getMessager().printMessage(Diagnostic.Kind.NOTE, String.format("檢查到 %s 為 %s 型別", paramName, strTypeMirror)); processingEnv.getMessager().printMessage(Diagnostic.Kind.NOTE, String.format("檢查到方法 %s 的參數 %s 為 %s 型別", method.getSimpleName(), paramName, strTypeMirror)); } } } return true; } }

3. TypeAnnotations17.java (使用型別註解的類別)

   public class TypeAnnotations17 { public void process3(@OnlyString String input) { // do something } public void process4(@OnlyString int input) { // do something } public static void main(String[] args) throws NoSuchMethodException { TypeAnnotations17 example = new TypeAnnotations17(); example.process3("abc"); example.process4(1); } }

輸出結果：

D:\Ethan\workspace\lab\example\text\java-newfeatures\src>javac -encoding utf-8 OnlyString.java OnlyStringProcessor.java D:\Ethan\workspace\lab\example\text\java-newfeatures\src>javac -encoding utf-8 -processor OnlyStringProcessor TypeAnnotations17.java Note: 檢查到 input 為 @OnlyString java.lang.String 型別 Note: 檢查到方法 process3 的參數 input 為 @OnlyString java.lang.String 型別 error: 檢查到方法 process4 的參數 input 為 @OnlyString int 型別，只能將 @OnlyString 使用於 java.lang.String 型別。 1 error

這些範例展示了如何將註解應用於型別，並使用它們來定義程式碼的約束條件。

六、總結

返回目錄

型別上的註解是 Java 8 的一項重要改進，它擴展了註解的應用範圍，使其可以應用於型別，而非單純只適用於類別、方法等。這項特性帶來了更強大的靜態分析能力，能夠幫助開發者在編譯時期發現更多程式碼中的問題。

型別上的註解的語法本身沒有變動，但其應用場景和周邊工具鏈都更加完善。 藉由與靜態分析工具、程式碼生成工具、或是框架的配合，型別上的註解在現代 Java 開發中扮演的角色越來越重要。 透過善用型別上的註解，可以有效地提升程式碼的品質、可讀性和可靠性。