Java 註解 完整教學：內建註解、自訂註解、屬性、保留策略、目標、反射讀取

什麼是註解

註解是加在程式碼上的**中繼資料**，不直接影響執行邏輯，供編譯器、工具、執行期反射讀取。語法：@AnnotationName。

三大內建註解

自訂註解四步驟

1. 宣告：public @interface MyAnn { }
2. 指定保留策略：@Retention(RetentionPolicy.RUNTIME)
3. 指定作用目標：@Target({ElementType.TYPE, ElementType.METHOD})
4. 定義屬性：String value() default "";

完整範例

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
public @interface MyAnnotation {
    String value();                    // 必填
    String color() default "red";      // 可選，有預設值
    WeekDay week() default WeekDay.MON; // 列舉型別
    int[] ids() default {1,2,3};       // 陣列型別
    Class clazz() default String.class; // Class 型別
    OtherAnnotation ann() default @OtherAnnotation("x"); // 註解巢狀
}

enum WeekDay { MON, TUE, WED }

@Retention(RetentionPolicy.RUNTIME)
@interface OtherAnnotation { String value(); }

// 使用
@MyAnnotation(value="demo", color="blue", week=WeekDay.WED, ids={5}, clazz=Integer.class)
public class Demo {
    @MyAnnotation("method-value")
    public void test() {}
}

反射讀取註解

// 類別層級
if (Demo.class.isAnnotationPresent(MyAnnotation.class)) {
    MyAnnotation ann = Demo.class.getAnnotation(MyAnnotation.class);
    System.out.println(ann.value());   // demo
    System.out.println(ann.color());   // blue
    System.out.println(ann.week());    // WED
    System.out.println(ann.ids().length); // 1
    System.out.println(ann.clazz());   // class java.lang.Integer
}

// 方法層級
Method m = Demo.class.getMethod("test");
MyAnnotation mAnn = m.getAnnotation(MyAnnotation.class);
System.out.println(mAnn.value()); // method-value

保留策略對照

目標類型

@Target({
    ElementType.TYPE,        // 類別/介面/列舉
    ElementType.METHOD,      // 方法
    ElementType.FIELD,       // 欄位
    ElementType.PARAMETER,   // 參數
    ElementType.CONSTRUCTOR, // 建構子
    ElementType.LOCAL_VARIABLE,
    ElementType.ANNOTATION_TYPE,
    ElementType.PACKAGE,
    ElementType.TYPE_PARAMETER,  // Java 8+
    ElementType.TYPE_USE         // Java 8+
})

最佳實務

1. 業務註解務必加 @Retention(RUNTIME)，否則反射讀不到。
2. 屬性命名慣用 value() 作為單一主要屬性，使用時可省略屬性名：@Ann("x")。
3. 陣列屬性單值時可省略大括號：ids=5 等同 ids={5}。
4. 配合 AnnotationProcessor (APT) 可在編譯期產生程式碼/檢查規範。