Java 自定義註解入門：元註解、定義規範與實戰示例

元註解：註解的註解

Java 5 提供 4 標準元註解（均在 java.lang.annotation 包）：

元註解使用示例

@Target 示例

// 僅可用於類、接口、枚舉聲明
@Target(ElementType.TYPE)
public @interface Table {
    String tableName() default "className";
}

// 僅可用於字段
@Target(ElementType.FIELD)
public @interface NoDBColumn { }

@Retention 示例

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME) // 運行時可反射讀取
public @interface Column {
    String name() default "fieldName";
    String setFuncName() default "setField";
    String getFuncName() default "getField";
    boolean defaultDBValue() default false;
}

@Documented 與 @Inherited

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented // 將出現在生成的 Javadoc 中
public @interface Column { ... }

// 父類註解可被子類繼承（需配合 RUNTIME 保留）
@Inherited
public @interface Greeting {
    String name();
    FontColor fontColor() default FontColor.GREEN;
    enum FontColor { BLUE, RED, GREEN }
}

自定義註解語法規範

public @interface AnnotationName {
    // 參數聲明：無參方法，返回值即參數類型
    // 支持類型：基本類型、String、Class、enum、Annotation、以上類型的數組
    Type paramName() default defaultValue;
}

關鍵規則

1. 修飾符僅允許 public 或默認（package-private）
2. 參數只能是基本類型、String、Class、enum、Annotation 及其數組
3. 單參數慣例命名為 value()，使用時可省略參數名：@Annotation("val")
4. 無法聲明 null 為默認值，慣用空字符串 "" 或 -1 表示「未指定」

實戰：水果註解族

1. 註解定義

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FruitName {
    String value() default "";
}

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FruitColor {
    enum Color { BLUE, RED, GREEN }
    Color fruitColor() default Color.GREEN;
}

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FruitProvider {
    int id() default -1;
    String name() default "";
    String address() default "";
}

2. 使用註解

public class Apple {
    @FruitName("Apple")
    private String appleName;

    @FruitColor(fruitColor = Color.RED)
    private String appleColor;

    @FruitProvider(id = 1, name = "果園有限公司", address = "北京市")
    private String provider;

    // getter/setter 省略
}

註解處理：賦予註解生命

定義註解只是第一步，核心價值在於註解處理器通過反射讀取註解信息並執行邏輯（如 ORM 映射、參數驗證、代碼生成）。下一步學習：AnnotationProcessor、運行時反射解析、編譯時處理（APT）。