Java 註解完全指南：從內建到自定義，編譯期到運行時

什麼是 Java 註解？

註解自 Java 5 引入，本質是附加在程式碼上的元資料。它們不直接改變程式邏輯，但能被編譯器、建構工具或運行時框架讀取，從而影響建構流程、代碼生成或運行行為。

註解的三大生命週期

內建標準註解

@Deprecated

標記不再推薦使用的 API，編譯器會發出警告。建議搭配 Javadoc @deprecated 說明替代方案。

@Deprecated
/** @deprecated 請改用 {@link MyNewComponent} */
public class MyComponent { }

@Override

驗證方法確實覆寫了父類/介面方法。雖非強制，但強烈建議加上：若父類方法簽名變更，編譯器會即時報錯，避免無意中斷繼承鏈。

public class Child extends Parent {
    @Override
    public void doSomething() { ... }
}

@SuppressWarnings

抑制特定編譯器警告。遵循就近原則：標註在最小範圍（方法而非類別），避免掩蓋真實問題。

@SuppressWarnings("unchecked")
public void legacyMethod() { ... }

自定義註解實戰

基本定義

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
public @interface ApiEndpoint {
    String path() default "/";
    HttpMethod method() default HttpMethod.GET;
    int version() default 1;
}

• @interface 關鍵字宣告註解類型
• 元素類似無參方法，支援基本型別、String、Class、enum、註解、一維陣列
• default 指定預設值，使用時可省略

元註解詳解

註解處理：編譯期 vs 運行時

編譯期處理（Annotation Processor）

• 實作 javax.annotation.processing.Processor
• 掃描源碼 AST，生成新原始碼/資源檔（如 Dagger、Room、Lombok）
• 優勢：零運行時開銷、編譯期報錯、適合代碼生成

運行時反射讀取

// 讀取類別註解
ApiEndpoint ann = MyClass.class.getAnnotation(ApiEndpoint.class);
if (ann != null) {
    System.out.println("Path: " + ann.path());
}

// 讀取方法註解
for (Method m : MyClass.class.getDeclaredMethods()) {
    if (m.isAnnotationPresent(ApiEndpoint.class)) {
        ApiEndpoint ep = m.getAnnotation(ApiEndpoint.class);
        // 處理路由註冊等邏輯
    }
}

注意：反射有效能開銷，高頻熱點路徑建議緩存結果或改用編譯期處理。

最佳實踐總結

1. 語義清晰：註解名稱表達業務意圖（如 @Transactional 而非 @DB）
2. 最小權限：@Target 精確限定修飾範圍
3. 生命週期對齊：框架掃描用 RUNTIME，代碼生成用 SOURCE/CLASS
4. 文檔化：加上 @Documented 讓 API 使用者可見
5. 避免濫用：能用介面/繼承表達的結構關係，別硬用註解