Java 註解 (Annotation) 入門：元資料價值與三大內建註解詳解

元資料 = 關於資料的資料。Java 程式設計近年趨勢廣泛採用元資料：產生文件、追蹤代碼依賴、編譯期檢查。早期工具如 XDoclet 以 Javadoc 標籤實現，但 Javadoc 缺陷明顯：僅能產出 HTML 文件，缺乏標準化方式供其他工具消費。

J2SE 5.0 (Tiger) 引入註解 將通用元資料工具整合進核心語言。註解可套用於套件宣告、類型宣告、建構子、方法、欄位、參數、區域變數。本文概述元資料價值並介紹三大內建註解，第二部分將探討自訂註解。

元資料三大價值

1. 文件編制：標示方法相依性、完整度、類別引用關係等。但 Javadoc 已做得好，非引入註解主因
2. 編譯器檢查：核心價值。編譯器利用元資料執行基本編譯期檢查。例：@Override 確保方法確實覆寫父類方法，捕捉參數拼寫錯誤導致「以為覆寫實則多載」的經典 Bug
3. 程式碼分析：最強功能。工具利用額外資料分析程式碼。反射雖能內省型別，但實際常不準 (如參數宣告 Object 實際只用 Integer)。元資料可精確指示真實需求型別。複雜場景如 EJB 多介面同步、依賴管理，XDoclet 等工具已驗證元資料威力

註解基礎語法

• 形式：@AnnotationName (at 標記 + 註解名)
• 資料傳遞：name=value 對，多值用陣列 {v1, v2}
• 一段程式碼可有多個註解，多個註解可屬同一類型

三種基本註解類型

陣列值範例

@TODOItems({
    @TODO(severity=TODO.CRITICAL, item="Add mean calculation", assignedTo="Brett"),
    @TODO(severity=TODO.IMPORTANT, item="Print usage message", assignedTo="Brett"),
    @TODO(severity=TODO.LOW, item="Roll new website page", assignedTo="Jason")
})

TODOItems 為單一值註解 (值為陣列)，陣列元素為完整註解 @TODO。逗號分隔陣列元素與成員值。

三大內建註解詳解

1. @Override — 確保方法覆寫

僅適用於方法。指示該方法覆寫父類方法。編譯器驗證：若父類無同簽名方法 → 編譯錯誤。

public class OverrideTester {
    @Override public String toString() { return super.toString() + " [Override Tester]"; }
    @Override public int hashCode() { return toString().hashCode(); }
}

實戰價值：深夜編碼拼寫錯誤 (如 hashCode 寫成 hasCode) 會被編譯器即時攔截：

@Override public int hasCode() { ... }  // 編譯錯誤：父類無 hasCode 方法可覆寫

2. @Deprecated — 標記不建議使用

標記註解，建議與方法宣告同行：

@Deprecated public void doSomething() { /* ... */ }
public void doSomethingElse() { /* 更好的實作 */ }

單獨編譯無反應。但**調用/覆寫**被標記方法時，編譯器發出警告 (需啟用 -deprecated 或 -Xlint:deprecated)：

3. @SuppressWarnings — 壓制特定編譯警告

含成員變數，值為警告類型陣列。解決泛型等新特性對舊代碼產生的大量無關警告。

public void nonGenericsMethod() {
    List wordList = new ArrayList(); // 無類型資訊
    wordList.add("foo"); // 產生 unchecked 警告
}

加上註解消除：

@SuppressWarnings(value={"unchecked"})
public void nonGenericsMethod() { /* ... */ }

可一次壓制多種警告：@SuppressWarnings(value={"unchecked", "fallthrough"})。極大簡化遷舊代碼/混合版本開發的警告噪音。

總結

註解語法雖新但極簡單。三大內建註解雖簡單卻威力巨大：@Override 捕捉覆寫錯誤、@Deprecated 管理 API 演進、@SuppressWarnings 靈活控制警告噪音。元資料正成為不可或缺的開發利器。第二部分將深入自訂註解類型定義、編譯器識別機制、以及「對註解的註解」元註解世界。

1. 上一篇文章： Java 註解 (Annotation) 進階：自訂註解類型、成員預設值與元註解完整指南
2. 下一篇文章： Windows Server 2003 下 Tomcat 控制台輸出卡住問題：快速編輯模式導致線程阻塞

Java 相關知識

NetBeans IDE 開發 Web 應用入門：從項目創建到部署運行完整指南

本教程基於 NetBeans IDE 6.5/6.7，演示創

Java 獲取 HTTPS 證書並調用 WebService 完整指南：InstallCert 實戰

調用 HTTPS WebService 時，若服務端證書不在

使用 Java Persistence API 與 JavaServer Faces 開發 Web 應用程式

前言 當應用程式需要資料持久化支援時，Java Persis

Spring AOP 配置錯誤：Eclipse 無法識別 tx:advice 標籤解決方案

Spring XML 配置中使用 <tx:advice