Java註解（入門級）

2020 年 11 月 8 日
筆記
JAVA, Java基礎, Java註解

Java註解

前言

近日在閱讀開源項目，發現項目里好多奇奇怪怪的註解(@DataScope、@Log…)看得我一臉懵，不知道大家是否也有過這樣的經歷，回想了一下，發現自己對於註解的知識，好像只停留在@Override。。。異常尷尬，所以今天就補補註解這個知識，並把自己的收穫記錄在此，與大家一同交流，如有不對的地方，敬請指正！

希望本文能給讀者帶來以下收穫：

明白註解是什麼，大概有什麼用

能理解別人代碼裏面註解的作用

能使用自定義註解

什麼是註解

想要了解某個知識點，我首先推薦的都是去官網查看，下面看看Java官方對註解的解釋：

Annotations, a form of metadata, provide data about a program that is not part of the program itself. Annotations have no direct effect on the operation of the code they annotate.

註解是元數據的一種形式，它提供有關程序的數據，但這些數據不是程序本身的一部分。註解對它們注釋的代碼的操作沒有直接影響。

一堆英文讀完，一陣雲里霧裡。沒關係，這是正常操作，不過我們從翻譯中還是可以了解到註解可以提供數據，並且數據是獨立於程序的，那麼我們大致可以推斷出，註解其實是介於程序和數據之間的一種媒介，程序和數據通過註解達成了某種聯繫，即註解類似一根紅線，把數據和程序關聯在一起。

從`@Override`開始

通過對Java官方提供的註解解釋的翻譯，我們篩選推斷出了一個關鍵信息——關聯。那到底如何理解這個詞呢？別急，我們從最熟悉的陌生人@Override開始，最熟悉是因為我們知道這是方法重寫，子類覆蓋父類方法用到的註解，陌生是因為我們從來沒有點進去了解過這個註解，那接下來就進去看看吧！

import java.lang.annotation.*;
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.SOURCE)
public @interface Override {
}

短短的5行，好像除了第一行，其他啥都不知道。。。不急，我們一行一行來解讀！

註解導入了一個annotation包
註解的「套娃」行為@Target(ElementType.METHOD)、@Retention(RetentionPolicy.SOURCE)
不同於接口和類的聲明public @interface Override { }

除了對新註解不認識，我們大致可以了解到註解的定義格式，修飾符 @interface 註解名{}。（有點接口的感覺）

禁止套娃——元註解

通過對@Override的剖析，我們了解了註解的定義格式，不過我們發現註解裏面又有新的註解，本着刨根問底的好奇心，我們繼續進入@Target註解一探究竟！

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Target {
    ElementType[] value();
}

一直點擊，發現始終在@Documented、@Retention、@Target這幾個註解之間套娃，通過Java文檔我們了解到原來這些修飾註解的註解叫做元註解。元註解(meta-annotation)在java.lang.annotation包下：

@Retention

表示如何存儲被標記的註解(指定存儲級別)，有以下三個級別

RetentionPolicy.SOURCE：只保留到源碼級別，在編譯階段會被忽略，所以他們不會被寫入位元組碼。
RetentionPolicy.CLASS：（默認）編譯級別，在編譯時由編譯器保留，但被Java虛擬機(JVM)忽略。
RetentionPolicy.RUNTIME：由JVM保留，可以在運行時環境使用。

@Target

表示被標記的註解可以用於哪種java元素(類、接口、屬性、方法……)，有以下八種

作用域	解釋
ElementType.ANNOTATION_TYPE	可用於註解類型
ElementType.CONSTRUCTOR	可以用於構造函數
ElementType.FIELD	可以用於字段或者屬性
ElementType.LOCAL_VARIABLE	可以用於局部變量
ElementType.METHOD	可以用於方法級註解
ElementType.PACKAGE	可以用於包聲明
ElementType.PARAMETER	可以用於方法的參數
ElementType.TYPE	可以用於類的任何元素

@Documented

無論何時使用指定的註解，都應使用Javadoc工具記錄這些元素。（即會在生成的javadoc中加入註解說明）

@Inherited

可以從超類繼承注釋類型，僅用於類的聲明(接口不會繼承)

@Repeatable

在Java SE 8中引入的，表示標記的注釋可以多次應用於相同的聲明或類型使用。

註解的分類

通過對元註解的了解，我明白了一個註解都是由這些元註解修飾而來，而且我們也收穫了一個重要信息——註解可以修飾註解

這樣無限的套娃，就會有各種各樣的註解，那麼到底有哪些註解呢？常見的註解大致分為以下四類：

元註解

即上文提及的5個元註解

jdk註解

常見的如@Override @Deprecated @SuppressWarnings @SafeVarargs @FunctionalInterface

第三方註解

即第三方框架提供的註解，例如自動注入依賴@Autowired、@Controller等

自定義註解

即開發人員根據項目需求自定義的註解，用於一些工具在編譯、運行時進行解析和使用，起到說明、配置的功能。

實戰——定義自己的註解

看過了Java提供的註解，相信你已經對註解有個大致的了解了。那你有沒有想過，註解是如何化腐朽為神奇，加了一個簡單的@Autowired就能實現依賴注入、@Setter就能實現set方法的生成，下面通過簡單的實戰來體會一下注解的神奇之處吧！

實戰目標：

使用自定義註解，通過在實體類及其屬性上加註解，實現對實體類查詢sql語句的構造

ps:類似select * from t_user where t_name='kingwan'的形式

自定義註解的編寫規則

在開始實戰之前，我們先了解一下編寫自定義註解的規則：

註解的定義為@interface，所有的註解會自動繼承java.lang.Annotation這個接口，並且不能再去繼承別的類或者接口
參數成員只能用public或default（默認）訪問權限符修飾
參數成員只能用八大基本數據類型、String、Enum、Class、annotations等數據類型，以及這些類型的數組
要獲取類方法和字段的註解信息，必須通過java反射機制來獲取
註解也可以沒有定義成員（只起到標識作用）

了解了註解的定義規範，接下來我們開始進入正式的實戰環節。

1.自定義註解`@KingwanTable`、`KingwanColumn`

對於實體類查詢的sql語句，我們需要知道兩個信息：①查詢的表名②字段名。並且我們通常習慣將用戶表t_user對應於實體類User，那麼我們如何和把t_user和User進行關聯呢？一想到關聯，回顧我們最開始從官方文檔中提取出來的信息，沒錯，就是使用註解關聯。接下來定義兩個自定義註解：

@KingwanTable:註解實體類對應的表名

@Target(ElementType.TYPE)//作用在類/接口上
@Retention(RetentionPolicy.RUNTIME)//保留作用域：保留到運行時
public @interface KingwanTable {
    String value();//參數:表名
}

@KingwanColumn:註解實體類屬性對應的表字段名

@Target(ElementType.FIELD)//表示作用在字段上
@Retention(RetentionPolicy.RUNTIME)//保留到運行時
public @interface KingwanColumn {
    String value();//參數：字段名
}

2.實體類添加上自定義註解

有了自定義的兩個註解，那麼我們現在就可以把它們加在實體類上。

以下代碼定義了一個Student實體類，加上了@KingwanTable("t_student")映射表名，@KingwanColumn("stu_birth")映射字段名。

@Data//簡化實體類的set、get方法
@KingwanTable("t_student")
public class Student {
    @KingwanColumn("stu_name")
    private String stuName;
    @KingwanColumn("stu_age")
    private Integer stuAge;
    @KingwanColumn("stu_birth")
    private Date stuBirth;
}

以下代碼創建了一個student對象，並初始化信息

public static void main(String[] args) {
    Student student = new Student();
    //初始化信息
    init(student);
}
private static void init(Student student) {
    student.setStuName("kingwan");
    student.setStuAge(18);
    student.setStuBirth(new Date());
}

3.反射獲取註解信息

有了一個加了自定義註解的Student實體類，那麼我們想要構造SQL，就有以下思路：

獲取到註解的信息(獲取表名、字段名)=>獲取屬性的值(字段值)=>構造SQL

如何獲取呢？規則里說了，使用反射。

以下代碼通過獲取student的class對象，獲取類上的註解@KingwanTable信息。

aClass.isAnnotationPresent：判斷指定的註解是否存在

public static void main(String[] args) throws Exception {
    StringBuffer sql = new StringBuffer("");//即將拼接的SQL語句
    Student student = new Student();
    //初始化信息
    init(student);
    //反射獲取class類
    Class<? extends Student> aClass = student.getClass();
    //1. 判斷實體類上是否存在註解@KingwanTable
    boolean exist = aClass.isAnnotationPresent(KingwanTable.class);//傳入我們自定義的註解類
    String tableName = null;
    if(exist){
        //1.1 存在註解即獲取註解值---(表名)
        KingwanTable annotation = aClass.getAnnotation(KingwanTable.class);
        tableName = annotation.value();
        sql.append("select * from ").append(tableName).append(" where 1=1");//拼接SQL
    }
    System.out.println(sql);
}

此時SQL打印的結果：

獲取到了類上的註解信息，接下來我們來看看如何獲取屬性上的註解信息

//2. 獲取屬性上的註解
Field[] fields = aClass.getDeclaredFields();
for (Field field : fields) {
    //2.1 遍歷每個屬性上是否有KingwanColumn註解
    KingwanColumn column = field.getAnnotation(KingwanColumn.class);
    if( column != null){
        //2.1.1 獲取該屬性的值
        String fieldName = field.getName();//屬性名
        String methodName = "get"+fieldName.substring(0,1).toUpperCase()+fieldName.substring(1);//構造getter方法
        Method method = aClass.getMethod(methodName);
        //通過反射代理調用get方法，獲取屬性的值（name='kingwan',age=18....）
        Object invoke = method.invoke(student);
        if(invoke instanceof String){
            String value = (String) invoke;
            //sql拼接
            sql.append(" and ").append(column.value()).append("=").append("'")
                .append(value).append("'"); 
        }else{
            //想想還有哪些情況...
        }
    }
    System.out.println(sql);
}

此時SQL的結果：

當然，如果有小夥伴跟着本文敲，可能在這一步就走不下去了，這是因為我們的get方法返回的字段類型多種多樣，所以僅僅invoke instanceof String是不夠的，我們還需要考慮其他情況(Integer、Date)，限於篇幅原因，這裡不做過多介紹，大家完全可以自行補充，如果想了解我的實現思路，移步：案例源碼地址

這樣，是不是就達到了我們要的效果了，對於任意簡單實體類，我們都可以通過加上該註解實現一個簡單的查找SQL的生成

你學廢了嗎！😏😏😏

總結

註解有什麼用

相信大家看我之後可能會有疑問，註解好複雜，費一大堆功夫，還不如直接點呢！的確，我最開始也覺得註解有點雞肋，不過用久了之後，發現真香！而且註解的作用不僅僅這些，本文的目的是讓大家對註解有一個簡單的了解，當你看到別人寫的註解是多麼巧妙時，你也許就會發現，原來註解這麼好用！

在編譯時進行格式檢查。如@Override
跟蹤代碼依賴性，實現替代配置文件功能。通過處理註解信息生成代碼、XML文件。
一些注釋可以在運行時進行檢查

結尾一張圖

一張思維導圖總結一下內容，保存下來，時常複習！

Tags: JAVA Java基礎 Java註解