Java 注解詳解

本文部分摘自 On Java 8

基本語法

注解是 Java 5 所引入的眾多語言變化之一，是附加在代碼中的一些元資訊，用于一些工具在編譯、運行時進行決議和使用，起到說明、配置的功能，注解不會也不能影響代碼的實際邏輯，僅僅起到輔助性的作用，包含在 java.lang.annotation 包中

注解的語法十分簡單，只要在現有語法中添加 @ 符號即可，java.lang 包提供了如下五種注解：

• @Override

  表示當前的方法定義將覆寫基類的方法，如果你不小心把方法簽名拼錯了，編譯器就會發出錯誤提示

• @Deprecated

  如果使用該注解的元素被呼叫，編譯器就會發出警告資訊，表示不鼓勵程式員使用

• @SuppressWarnings

  關閉不當的編譯器警告資訊

• @SafeVarargs

  禁止對具有泛型可變引數的方法或建構式的呼叫方發出警告

• @FunctionalInterface

  宣告介面型別為函式式介面

定義注解

注解的定義看起來和介面的定義很像，事實上它們和其他 Java 介面一樣，也會被編譯成 class 檔案

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface TestAnnotation {}

除開 @ 符號， @Test 的定義看起來更像一個空介面，注解的定義也需要一些元注解，元注解用于注解其他的注解

不包含任何元素的注解稱為標記注解，上例中的 @Test 就是標記注解，注解通常也會包含一些表示特定值的元素，當分析處理注解的時候，程式可以利用這些值，注解的元素看起來就像介面的方法，但可以為其指定默認值

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface TestAnnotation {
    int id();
    String description() default "no description";
}

....

public class TestUtils {
    // 在方法上使用注解 @TestAnnotation
    @UseCase(id = 47, description = "description")
    public void test() {
        ...
    }
}

注解元素可用的型別如下所示，如果使用了其他型別，編譯器就會報錯：

• 所有基本型別（int、float、boolean 等）
• String
• Class
• enum
• Annotation
• 以上型別的陣列

如果沒有給出 description 的值，在分析處理這個類的時候會使用該元素的默認值，元素的默認值不能有不確定的值，也就是說，元素要么有默認值，要么就在使用注解時提供元素的值

這里還有另外一個限制：任何非基本型別的元素，無論是在源代碼宣告時還是在注解介面中定義默認值時，都不能使用 null 作為值，如果我們希望表現一個元素的存在或者缺失的狀態，可以自定義一些特殊的值，比如空字串或者負數用于表達某個元素不存在

注解不支持繼承，你不能使用 extends 關鍵字來繼承 @interface

注解處理器

如果沒有用于讀取注解的工具，那么注解不會比注釋更有用，使用注解中一個很重要的作用就是創建與使用注解處理器，Java 拓展了反射機制的 API 用于幫助你創造這類工具，同時他還提供了 javac 編譯器鉤子在編譯時使用注解

下面是一個非常簡單的注解處理器，我們用它來讀取被注解的 TestUtils 類，并且使用反射機制來尋找 @TestAnnotation 標記

public class TestAnnotationTracker {
    
    public static void trackTestAnnotation(Class<?> cl) {
        for(Method m : cl.getDeclaredMethods()) {
            TestAnnotation ta = m.getAnnotation(TestAnnotation.class);
            if(ta != null) {
                System.out.println(ta.id() + "\n " + ta.description());
            }
        }
    }
    
    public static void main(String[] args) {
        trackTestAnnotation(TestUtils.class);
    }
}

這里用到了兩個反射的方法：getDeclaredMethods() 和 getAnnotation()，getAnnotation() 方法回傳指定型別的注解物件，在本例中就是 TestAnnotation，如果被注解的方法上沒有該型別的注解，回傳值就為 null，通過呼叫 id() 和 description() 方法來提取元素值

使用注解實作物件 - 資料庫映射

當有些框架需要一些額外的資訊才能與你的源代碼協同作業，這種情況下注解就會變得十分有用，自定義例如物件/關系映射工具（Hibernate 和 MyBatis）通常都需要 XML 描述檔案，而這些檔案脫離于代碼之外，除了定義 Java 類，程式員還必須重復的提供某些資訊，而例如類名和包名等資訊已經在原始類中提供過了，經常會導致代碼和描述檔案的同步問題

假設你現在想提供一些基本的物件/關系映射功能，能夠自動生成資料庫表，你可以使用 XML 描述檔案來指明類的名字、每個成員以及資料庫映射的相關資訊，但是，通過使用注解，你可以把所有資訊都保存在 JavaBean 源檔案中，為此你需要一些用于定義資料庫表名稱、資料庫列以及將 SQL 型別映射到屬性的注解

首先創建一個用來映射資料庫表的注解，用來修飾類、介面（包括注解型別）或者 enum 宣告

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface DBTable {
    String name() default "";
}

如下是修飾欄位的注解

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Constraints {
    boolean primaryKey() default false;
    boolean allowNull() default true;
    boolean unique() default false;
}

public @interface SQLString {
    int value() default 0;
    String name() default "";
    Constraints constraints() default @Constraints;
}

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface SQLInteger {
    String name() default "";
    Constraints constraints() default @Constraints;
}

@Constraints 代表了資料庫通常提供的約束的一小部分，primaryKey()，allowNull() 和 unique() 元素都提供了默認值，大多數情況下，注解的使用者都不需要輸入太多東西

另外兩個 @interface 定義的是 SQL 型別，如果希望這個框架更有價值的話，我們應該為每個 SQL 型別都定義相應的注解，不過作為示例，兩個元素足夠了，這些 SQL 型別具有 name() 元素和 constraints() 元素，后者利用了嵌套注解的功能，將資料庫列的型別約束資訊嵌入其中，注意 constraints() 元素的默認值是 @Constraints，沒有在括號中指明 @Constraints 元素的值，因此，constraints() 的默認值為所有元素都為默認值，如果要使得嵌入的 @Constraints 注解中的 unique() 元素為 true，并作為 constraints() 元素的默認值，你可以像如下定義：

public @interface Uniqueness {
    Constraints constraints() default @Constraints(unique = true);
}

下面是一個簡單的，使用了如上注解的類

@DBTable(name = "MEMBER")
public class Member {
    @SQLString(30)
    String firstName;
    @SQLString(50)
    String lastName;
    @SQLInteger
    Integer age;
    @SQLString(value = https://www.cnblogs.com/Yee-Q/archive/2020/11/26/30, constraints = @Constraints(primaryKey = true))
    String reference;
    static int memberCount;
    public String getReference() { return reference; }
    public String getFirstName() { return firstName; }
    public String getLastName() { return lastName; }
    @Override
    public String toString() { return reference; }
    public Integer getAge() { return age; }
}

類注解 @DBTable 注解給定了元素值 MEMBER，它將會作為表的名字，類的屬性 firstName 和 lastName 都被注解為 @SQLString 型別并且給了默認元素值分別為 30 和 50，并在嵌入的 @Constraint 注解中設定 primaryKey 元素的值

下面是一個注解處理器的例子，它將讀取一個類檔案，檢查上面的資料庫注解，并生成用于創建資料庫的 SQL 命令：

public class TableCreator {
    
    public static void generateSql(String[] classnames) throws Exception {
        for (String className : classnames) {
            Class<?> cl = Class.forName(className);
            DBTable dbTable = cl.getAnnotation(DBTable.class);
            String tableName = dbTable.name();
            // 如果表名為空字串，則使用類名
            if (tableName.length() < 1) {
                tableName = cl.getName().toUpperCase();
            }
            List<String> columnDefs = new ArrayList<>();
            for (Field field : cl.getDeclaredFields()) {
                String columnName = null;
                Annotation[] anns = field.getDeclaredAnnotations();
                // 該屬性不是列
                if (anns.length < 1) {
                    continue;
                }
                // 處理整數型別
                if (anns[0] instanceof SQLInteger) {
                    SQLInteger sInt = (SQLInteger) anns[0];
                    // 如果列名為空字串，則使用屬性名
                    if (sInt.name().length() < 1) {
                        columnName = field.getName().toUpperCase();
                    } else {
                        columnName = sInt.name();
                    }
                    columnDefs.add(columnName + " INT" + getConstraints(sInt.constraints()));
                }
                // 處理字串型別
                if (anns[0] instanceof SQLString) {
                    SQLString sString = (SQLString) anns[0];
                    if (sString.name().length() < 1) {
                        columnName = field.getName().toUpperCase();
                    } else {
                        columnName = sString.name();
                    }
                    columnDefs.add(columnName + " VARCHAR(" + sString.value() + ")" +
                            getConstraints(sString.constraints()));
                }
                // 構造并輸出 sql 字串
                StringBuilder createCommand = new StringBuilder("CREATE TABLE " + tableName + "(");
                for (String columnDef : columnDefs) {
                    createCommand.append("\n " + columnDef + ",");
                }
                String tableCreate = createCommand.substring(0, createCommand.length() - 1) + ");";
                System.out.println("Table Creation SQL for " + className + " is:\n" + tableCreate);
            }
        }
    }

    private static String getConstraints(Constraints con) {
        String constraints = "";
        if (!con.allowNull())
            constraints += " NOT NULL";
        if (con.primaryKey())
            constraints += " PRIMARY KEY";
        if (con.unique())
            constraints += " UNIQUE";
        return constraints;
    }
}

編譯時注解處理

當 @Retention 的 RetentionPolicy 引數被標注為 SOURCE 或 CLASS，此時你無法通過反射去獲取注解資訊，因為注解在運行期是不存在的，使用 javac 可以創建編譯時注解處理器，在編譯時掃描和處理注解，你可以自定義注解，并注冊到對應的注解處理器，注解處理器可以生成 Java 代碼，這些生成的 Java 代碼會組成新的 Java 源檔案，但不能修改已經存在的 Java 類，例如向已有的類中添加方法，如果你的注解處理器創建了新的源檔案，在新一輪處理中注解處理器會檢查源檔案本身，在檢測一輪之后持續回圈，直到不再有新的源檔案產生，然后編譯所有的源檔案

我們來撰寫一個簡單的注解處理器，如下是注解的定義

@Retention(RetentionPolicy.SOURCE)
@Target({ElementType.TYPE, ElementType.METHOD,
        ElementType.CONSTRUCTOR,
        ElementType.ANNOTATION_TYPE,
        ElementType.PACKAGE, ElementType.FIELD,
        ElementType.LOCAL_VARIABLE})
public @interface Simple {
    String value() default "-default-";
}

@Retention 的引數為 SOURCE，這意味著注解不會存留在編譯后的 class 檔案，因為這對應編譯時處理注解是沒有必要的，在這里，javac 是唯一有機會處理注解的方式

package annotations.simplest;
@Simple
public class SimpleTest {
    @Simple
    int i;
    @Simple
    public SimpleTest() {}
    @Simple
    public void foo() {
        System.out.println("SimpleTest.foo()");
    }
    @Simple
    public void bar(String s, int i, float f) {
        System.out.println("SimpleTest.bar()");
    }
    @Simple
    public static void main(String[] args) {
        @Simple
        SimpleTest st = new SimpleTest();
        st.foo();
    }
}

運行 main 方法，程式就會開始編譯，如下是一個簡單的處理器，作用就是把注解相關的資訊列印出來

package annotations.simplest;
import javax.annotation.processing.*;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.*;
import java.util.*;
@SupportedAnnotationTypes("annotations.simplest.Simple")
@SupportedSourceVersion(SourceVersion.RELEASE_8)
public class SimpleProcessor extends AbstractProcessor {
    
    @Override
    public boolean process(Set<? extends TypeElement> annotations,
    	RoundEnvironment env) {
        for(TypeElement t : annotations) {
            System.out.println(t);
        }
        for(Element el : env.getElementsAnnotatedWith(Simple.class)) {
            display(el);
        }
        return false;
    }
    
    private void display(Element el) {
        System.out.println("==== " + el + " ====");
        System.out.println(el.getKind() +	// 回傳此元素的種類，欄位，方法，或是類
                " : " + el.getModifiers() +	// 回傳此元素的修飾符
                " : " + el.getSimpleName() +	// 回傳此元素的簡單名稱
                " : " + el.asType());	// 回傳此元素定義的型別
        // 如果元素為CLASS型別，動態向下轉型為更具體的元素型別，并列印相關資訊
        if(el.getKind().equals(ElementKind.CLASS)) {
            TypeElement te = (TypeElement)el;
            System.out.println(te.getQualifiedName());
            System.out.println(te.getSuperclass());
            System.out.println(te.getEnclosedElements());
        }
        // 如果元素為METHOD型別，動態向下轉型為更具體的元素型別，并列印相關資訊
        if(el.getKind().equals(ElementKind.METHOD)) {
            ExecutableElement ex = (ExecutableElement)el;
            System.out.print(ex.getReturnType() + " ");
            System.out.print(ex.getSimpleName() + "(");
            System.out.println(ex.getParameters() + ")");
        }
    }
}

使用 @SupportedAnnotationTypes 和 @SupportedSourceVersion 注解來確定支持哪些注解以及支持的 Java 版本

注解處理器需要繼承抽象類 javax.annotation.processing.AbstractProcessor，唯一需要實作的方法就是 process()，這里是所有行為發生的地方，第一個引數獲取到此注解處理器所要處理的注解集合，第二個引數保留了剩余資訊，這里我們所做的事情只是列印了注解（只存在一個），process() 中實作的第二個操作是回圈所有被 @Simple 注解的元素，并且針對每一個元素呼叫 display() 方法，展示所有 Element 自身的基本資訊

標籤：其他

上一篇：Python做資料分析，一般的流程是怎么樣的？

下一篇：不一樣的Flink入門教程