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

Java 註解全解析：從內置到自定義，掌握元數據編程精髓

編輯：Java 相關知識

前言

Java 1.5 引入註解機制，將元數據直接嵌入源碼，並通過編譯器保留至字節碼，配合反射實現運行時檢測，極大豐富了框架開發與代碼檢查能力。本文系統梳理內置註解、元註解、自定義註解定義與解析全流程。

一、內置註解：語言級別的標準語義

1.1 作用於代碼的標準註解

註解	作用	版本
`@Override`	檢查方法是否正確覆寫父類/接口方法，否則編譯報錯	1.5
`@Deprecated`	標記棄用 API，使用時編譯器發出警告	1.5
`@SuppressWarnings`	抑制特定編譯器警告	1.5
`@SafeVarargs`	抑制泛型可變參數堆污染警告	1.7
`@FunctionalInterface`	標記函數式接口，編譯器驗證只有一個抽象方法	1.8

1.2 元註解：註解的註解

元註解用於定義自定義註解的行為特徵：

@Retention：指定保留策略
- SOURCE：僅源碼保留，編譯丟棄
- CLASS（默認）：編譯進 class，類加載時忽略
- RUNTIME：運行時可通過反射獲取
@Documented：將註解信息包含進 Javadoc 文檔
@Target：限定註解作用範圍（TYPE、FIELD、METHOD、PARAMETER、CONSTRUCTOR、LOCAL_VARIABLE、ANNOTATION_TYPE、PACKAGE、MODULE、TYPE_PARAMETER、TYPE_USE）
@Inherited：允許子類繼承父類上的該註解（僅針對 TYPE 類型）
@Repeatable：允許同一註解多次作用於同一目標（1.8+）

二、自定義註解：構建領域專屬元數據

2.1 定義語法

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Documented
public @interface ClassInfo {
    String author() default "Wang";
    String date();
    String comments();
}

關鍵規則：

使用 @interface 關鮮字，隱式繼承 java.lang.annotation.Annotation
不可繼承其他註解或接口
方法即參數：無參數、無拋出異常、返回類型受限（8種基本類型、String、Class、enum、Annotation、以上類型數組）
可用 default 指定默認值

2.2 多維度註解示例

// 作用於方法
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface MethodInfo {
    String description() default "No Description";
    String date();
}

// 作用於字段
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface FieldInfo {
    String type();
    String name();
}

2.3 註解使用

@ClassInfo(author = "wang", date = "2024/01/15", comments = "示例類")
public class AnnotationDemo {
    @FieldInfo(type = "public", name = "firstField")
    public int firstField;

    @FieldInfo(type = "private", name = "secondField")
    private String secondField;

    @MethodInfo(description = "核心業務方法", date = "2024/01/15")
    public void firstMethod(String value) { /* ... */ }

    @MethodInfo(description = "輔助方法", date = "2024/01/15")
    private void secondMethod() { /* ... */ }
}

注意：無默認值的參數必須顯式賦值，否則編譯報錯。

三、運行時解析註解：反射 API 實戰

前提：註解需標註 @Retention(RetentionPolicy.RUNTIME)。

public class AnnotationParser {
    public static void parse(Class clazz) {
        // 1. 類級註解
        if (clazz.isAnnotationPresent(ClassInfo.class)) {
            ClassInfo ci = clazz.getAnnotation(ClassInfo.class);
            System.out.printf("類註解：%s %s %s%n", ci.author(), ci.date(), ci.comments());
        }

        // 2. 字段級註解
        for (Field field : clazz.getDeclaredFields()) {
            if (field.isAnnotationPresent(FieldInfo.class)) {
                FieldInfo fi = field.getAnnotation(FieldInfo.class);
                System.out.printf("字段 %s：%s %s%n", field.getName(), fi.type(), fi.name());
            }
        }

        // 3. 方法級註解
        for (Method method : clazz.getDeclaredMethods()) {
            if (method.isAnnotationPresent(MethodInfo.class)) {
                MethodInfo mi = method.getAnnotation(MethodInfo.class);
                System.out.printf("方法 %s：%s %s%n", method.getName(), mi.description(), mi.date());
            }
        }
    }
}