Java 註解（Annotation）完整指南：從原理到自訂實戰

Java 5 引入註解機制，徹底改變了框架開發與元資料管理方式。本文系統梳理註解的設計動機、核心語法、內建元註解，並通過一個測試框架實例展示實戰應用。

為什麼需要註解？

• 消除樣板碼：如 JAX-RPC 需要介面/實現雙份定義，註解可自動生成。
• 取代副檔案：EJB 的 ejb-jar.xml、JavaBean 的 BeanInfo 類，皆可內嵌為註解，減少同步維護錯誤。
• 標準化元資料：transient、@Deprecated 早期即為特殊註解形式，Java 5 統一為通用機制。

註解核心特性

• 不直接影響程式語義，但影響工具/庫對程式的處理，進而影響運行行為。
• 可從原始碼、Class 檔、運行時（反射）三個層面讀取。
• 定義語法類似介面，關鍵字前加 @：@interface MyAnno { ... }。

註解類型元素規則

• 方法無參數、無 throws。
• 回傳型別限於：基本型別、String、Class、enum、註解型別、及其陣列。
• 可指定預設值：String author() default "unknown";。

三種特殊註解形式

元註解：註解的註解

• @Retention(RetentionPolicy.RUNTIME)：保留至運行時，可反射讀取。
• @Target(ElementType.METHOD)：限制作用目標（類、方法、欄位等）。
• @Documented：納入 Javadoc。
• @Inherited：允許子類繼承。

實戰：自訂測試框架

// 1. 定義 @Test 註解
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Test {}

// 2. 被測類
public class Foo {
    @Test public static void m1() {}
    public static void m2() {}
    @Test public static void m3() { throw new RuntimeException("Boom"); }
    @Test public static void m5() {}
    @Test public static void m7() { throw new RuntimeException("Crash"); }
}

// 3. 測試執行器
public class RunTests {
    public static void main(String[] args) throws Exception {
        int passed = 0, failed = 0;
        for (Method m : Class.forName(args[0]).getMethods()) {
            if (m.isAnnotationPresent(Test.class)) {
                try { m.invoke(null); passed++; }
                catch (Throwable ex) { System.out.printf("Test %s failed: %s%n", m, ex.getCause()); failed++; }
            }
        }
        System.out.printf("Passed: %d, Failed: %d%n", passed, failed);
    }
}

輸出：

Test public static void Foo.m3() failed: java.lang.RuntimeException: Boom
Test public static void Foo.m7() failed: java.lang.RuntimeException: Crash
Passed: 2, Failed: 2

此框架可輕鬆擴展支援 @Before、@After、參數化測試等進階功能。