您现在的位置：程式碼之家 >> 編程語言 > >> Java 程式設計 >> Java 相關知識

Java 註解完整指南：內建類型、元註解與自訂實作

編輯：Java 相關知識

Java 註解（Annotation）源自「Metadata（中繼資料）」概念，即「描述資料的資料」。自 JDK 5 引入以來，已成為框架設定、程式碼檢查、文件產生的核心機制。本文系統整理註解分類、三大內建註解、四種元註解，並示範自訂註解的完整流程。

註解的三種基本形式

標記註解：無參數，僅以名稱標識。如 @Override
單一值註解：提供單一資料。如 @SuppressWarnings("unchecked")
完整註解：包含多組鍵值對。如 @MyAnno(val1="a", val2="b")

三大內建註解

註解	適用對象	用途
`@Override`	方法	編譯期驗證是否正確覆寫父類方法
`@Deprecated`	方法、類、欄位	標記不建議使用，編譯器會發出警告
`@SuppressWarnings`	類、方法、區塊	抑制特定編譯警告，如 `unchecked`、`rawtypes`

四大元註解

@Target：限定註解可標註位置（ElementType.METHOD、TYPE、FIELD 等）
@Retention：聲明生命週期
- SOURCE：僅原始碼保留，編譯捨棄
- CLASS：class 檔保留，VM 載入時捨棄（預設）
- RUNTIME：執行期保留，可透過反射讀取
@Documented：納入 Javadoc 產出
@Inherited：允許子類別繼承父類別的註解

自訂註解實作範例

// 1. 簡單標記註解
public @interface InProgress { }

// 2. 帶單一值（慣用 value）
public @interface TODO {
    String value();
}

// 3. 完整註解：含預設值、枚舉、多成員
public @interface GroupTODO {
    public enum Severity { CRITICAL, IMPORTANT, TRIVIAL, DOCUMENTATION }
    Severity severity() default Severity.IMPORTANT;
    String item();
    String assignedTo();
    String dateAssigned();
}

使用自訂註解

@InProgress
@TODO("完成利息計算邏輯")
public void calculateInterest(float amount, float rate) { }

@GroupTODO(
    item = "說明特殊演算法",
    assignedTo = "Jon",
    dateAssigned = "07/30/2004",
    severity = GroupTODO.Severity.DOCUMENTATION
)
public void complexMethod() { }