Java 註解 核心機制與實戰：從元註解到編譯期處理

註解本質：代碼上的結構化元數據

Java 5 (JDK 1.5) 引入 Annotation，將 **配置從 XML 解放出來，內嵌於代碼結構中**，實現「配置即代碼、代碼即文檔」。核心價值：

• 編譯期檢查：拼寫錯誤、類型不匹配即時報錯
• IDE 智能感知：屬性補全、跳轉定義、重構同步
• 運行期反射訪問：框架掃描驅動行為 (Spring、Hibernate、JUnit、MyBatis)
• 編譯期處理 (APT)：生成代碼、驗證約束、編譯報錯 (Lombok、MapStruct、Dagger、Error Prone)

定義註解：@interface 語法詳解

package com.demo.anno;

import java.lang.annotation.*;

@Target(ElementType.METHOD)           // 作用目標：方法
@Retention(RetentionPolicy.RUNTIME)   // 保留策略：運行期可見
@Documented                           // 納入 Javadoc
@Inherited                            // 子類繼承 (僅對 TYPE 生效)
public @interface SimpleAnnotation {
    String value() default "";        // 單一屬性慣命名 value，支援默認值
    int priority() default 0;         // 基本類型屬性
    String[] tags() default {};       // 陣列屬性
    EnumType mode() default EnumType.NORMAL; // 枚舉屬性
    Class[] groups() default {};   // Class 類型屬性
}

四大元註解決定註解行為

使用註解：語法與最佳實踐

@SimpleAnnotation(value = "核心業務", priority = 1, tags = {"交易", "核心"}, mode = EnumType.CRITICAL)
public void processCoreTransaction() { ... }

// 單一 value 屬性可省略屬性名
@SimpleAnnotation("簡單標記")
public void simpleMethod() { ... }

// 陣列單元素可省略大括號
@SimpleAnnotation(tags = "單標籤")
public void singleTag() { ... }

運行期反射訪問：AnnotatedElement API

public class AnnotationProcessor {
    public static void process(Class clazz) {
        // 1. 類級註解
        if (clazz.isAnnotationPresent(SimpleAnnotation.class)) {
            SimpleAnnotation anno = clazz.getAnnotation(SimpleAnnotation.class);
            System.out.println("類註解: " + anno.value());
        }
        
        // 2. 方法級註解
        for (Method method : clazz.getDeclaredMethods()) {
            if (method.isAnnotationPresent(SimpleAnnotation.class)) {
                SimpleAnnotation anno = method.getAnnotation(SimpleAnnotation.class);
                System.out.printf("方法 %s: value=%s, priority=%d%n", 
                    method.getName(), anno.value(), anno.priority());
                
                // 執行業務邏輯 (示例)
                try {
                    method.invoke(clazz.getDeclaredConstructor().newInstance());
                } catch (Exception e) {
                    e.printStackTrace();
                }
            }
        }
    }
}

關鍵 API 對比：

• getAnnotation(Class)：獲取指定類型註解 (含繼承，受 @Inherited 影響)
• getAnnotations()：獲取所有繼承的運行期註解
• getDeclaredAnnotations()：僅獲取聲明在本元素上的註解 (不含繼承)

標準註解三劍客：JDK 內建語義

進階實戰：組合註解與嵌套結構

// 商標註解
public @interface Trademark {
    String name();
    String owner();
}

// 授權註解：嵌套商標陣列
@Target({ElementType.TYPE, ElementType.PACKAGE})
@Retention(RetentionPolicy.RUNTIME)
public @interface License {
    String name();
    String notice();
    boolean redistributable();
    Trademark[] trademarks(); // 嵌套註解陣列
}

// 使用
@License(
    name = "Apache 2.0",
    notice = "開源協議",
    redistributable = true,
    trademarks = {
        @Trademark(name = "Mercedes", owner = "Daimler"),
        @Trademark(name = "Daewoo", owner = "GM Korea")
    }
)
public class ProductCatalog { }

編譯期註解處理 (APT)：Lombok/MapStruct 背後的魔法

處理器標準流程

1. 實現 javax.annotation.processing.Processor (或繼承 AbstractProcessor)
2. 註解 @SupportedAnnotationTypes、@SupportedSourceVersion
3. process(Set, RoundEnvironment) 中遍歷被註解元素
4. 使用 Filer 生成新源文件 (.java)、類文件 (.class)、資源文件
5. 打包為 JAR，META-INF/services/javax.annotation.processing.Processor 註冊

Lombok 原理速覽

• 註解 @Data、@Getter、@Builder 等標記目標類
• 編譯期處理器攔截 AST (抽象語法樹)，**直接修改語法樹** 注入方法/構造器/字段
• 生成的字節碼包含注入成員，源碼保持極簡

避坑指南與最佳實踐

1. RetentionPolicy 選擇：框架掃描必須 RUNTIME；純編譯期驗證/代碼生成用 SOURCE；默認 CLASS 適合字節碼分析工具。
2. Target 精準限定：防止濫用於不支持位置 (如 LOCAL_VARIABLE 註解無法反射獲取)
3. 默認值設計：盡量提供合理默認值，減少使用者樣板代碼
4. 避免循環依賴：註解定義包不應依賴使用該註解的業務模組
5. 文檔化：@Documented + 詳細 Javadoc，註解即 API 契約

結語

Java 註解從「配置外部化」走向「語義內嵌」，經歷了 **運行期反射驅動 (Spring 2.x/JPA 1.0)** → **編譯期處理代碼生成 (Lombok/MapStruct/Dagger)** → **類型註解強化類型系統 (JDK 8 @NonNull/@CheckForNull)** 三代演進。掌握 **元註解語義、反射 API 邊界、APT 處理器模型、標準註解契約**，是構建現代 Java 框架、理解主流生態運作機制的核心鑰匙。