> 使用的太多，被忽略的理所當然；

# 一、註解基礎

註解即標註與解析，在Java的程式碼工程中，註解的使用幾乎是無處不在，甚至多到被忽視；

無論是在JDK原始碼或者框架元件，都在使用註解能力完成各種識別和解析動作；在對系統功能封裝時，也會依賴註解能力簡化各種邏輯的重複實現；

**基礎介面**

在Annotation的原始碼註釋中有說明：所有的註解型別都需要繼承該公共介面，本質上看註解是介面，但是程式碼並沒有顯式宣告繼承關係，可以直接檢視位元組碼檔案；

```java
-- 1、宣告註解
public @interface SystemLog {}

-- 2、檢視指令
javap -v SystemLog.class

-- 3、列印結果
Compiled from "SystemLog.java"
public interface com.base.test.SystemLog extends java.lang.annotation.Annotation
```

**元註解**

宣告註解時使用，用來定義註解的作用目標，保留策略等；

```java
@Documented
@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface SystemLog { String model () default "" ; }
```

- Documented：是否被javadoc或類似工具記錄在文件中；
- Inherited：標識註解是否可以被子類繼承；
- Target：作用目標，在ElementType列舉中可以看到取值包括類、方法、屬性等；
- Retention：保留策略，比如編譯階段是否丟棄，執行時保留；

此處宣告一個SystemLog註解，作用範圍是在方法上，並且在執行時保留，該註解通常用在服務執行時，結合AOP切面程式設計實現方法的日誌採集；

# 二、註解原理

先來看一個簡單的註解使用案例，再細緻的分析其中原理，案例並不複雜，就是常見的標註與解析兩個關鍵動作；

```java
public class LogInfo {
    @SystemLog(model = "日誌模組")
    public static void main(String[] args) {
        // 生成代理檔案
        System.getProperties().put("sun.misc.ProxyGenerator.saveGeneratedFiles", "true");
        // 反射機制
        Method[] methods = LogInfo.class.getMethods();
        for (Method method:methods){
            SystemLog systemLog = method.getAnnotation(SystemLog.class) ;
            if (systemLog != null){
                // 動態代理：com.sun.proxy.$Proxy2
                System.out.println(systemLog.getClass().getName());
                System.out.println(systemLog.model());
            }
        }
    }
}
```

這裡涉及到兩個核心概念：反射機制、動態代理；反射機制可以在程式執行時獲取類的完整結構資訊，代理模式給目標物件提供一個代理物件，由代理物件持有目標物件的引用；

案例中透過反射機制，在程式執行時進行註解的獲取和解析，值得關注的是systemLog物件的類名，輸出的是代理類資訊；

案例執行完畢後，會在程式碼工程的目錄下生成代理類，可以檢視`$Proxy2`檔案；

```java
public final class $Proxy2 extends Proxy implements SystemLog {
    public final String model() throws  {
        try {
            return (String)super.h.invoke(this, m3, (Object[])null);
        } catch (RuntimeException | Error var2) {
            throw var2;
        } catch (Throwable var3) {
            throw new UndeclaredThrowableException(var3);
        }
    }
}
```

在對SystemLog解析的過程中，實際上是在使用註解的代理類，`$Proxy2`繼承了Proxy類並實現了SystemLog介面，並且重寫了相關方法；有關反射和代理的邏輯，在之前的內容中有詳說，此處不贅述；

值得一看是代理類中invoke方法呼叫，具體的處理邏輯在AnnotationInvocationHandler類的invoke方法中，會對註解原生方法和自定義方法做判斷，並對原生方法提供實現；

# 三、常用註解

## 1、JDK註解

在JDK中有多個註解是經常使用的，例如Override、Deprecated、SuppressWarnings等；

- Override：判斷方法是否為重寫方法；
- Deprecated：標記過時的API，繼續使用會警告；
- FunctionalInterface：檢驗是否為函式式介面；
- SuppressWarnings：程式碼的警告會靜默處理；

這裡注意FunctionalInterface註解，從1.8開始引入，檢驗是否為函式式介面，即介面只能有一個抽象方法，否則編譯報錯；

## 2、Lombok註解

在具體的看Lombok元件之前，需要先了解一個概念：程式碼編譯；在open-jdk的描述文件中大致分為三個核心階段；

![](http://img.blog.itpub.net/blog/2022/11/14/2d2ceb7c8bf22a72.png?x-oss-process=style/bb)

第一步：讀取命令列上指定的所有原始檔，解析為語法樹，進行符號表填充；

第二步：呼叫註解處理器，如果處理器生成任何新的原始檔或類檔案，編譯會重新啟動；

第三步：分析器建立的語法樹被分析並轉換為類檔案；

更多細節說明可以參考openjdk文件中Compiler模組的內容，下面再回到Lombok元件上；

Lombok元件在程式碼工程中的使用非常頻繁，透過註解的方式極大的簡化Java中Bean物件的編寫，提高了效率並且讓原始碼顯得簡潔；

這裡用一段簡單的程式碼演示其效果，在IdKey的類中透過三個常用的Lombok註解，替代了類中很多基礎方法的顯式生成，檢視編譯後的檔案實際是存在相關方法的；

```java
@Data
@AllArgsConstructor
@NoArgsConstructor
public class IdKey {
    private Integer id ;
    private String key ;

public static void main(String[] args) {
        IdKey idKey01 = new IdKey(1,"cicada") ;
        System.out.println(idKey01);
        idKey01.setId(2);
        idKey01.setKey("smile");
        System.out.println(idKey01);
    }
}
```

這裡需要了解JDK中註解處理器的相關原始碼，AbstractProcessor作為超類，編譯器在編譯時會去檢查該類的子類，子類中最核心的是process方法；

![](http://img.blog.itpub.net/blog/2022/11/14/754c333f055c44b7.png?x-oss-process=style/bb)

```java
-- 1、Lombok處理器
@SupportedAnnotationTypes("*")
public class LombokProcessor extends AbstractProcessor {
    private JavacTransformer transformer;
    @Override
    public boolean process(Set extends TypeElement> annotations, RoundEnvironment roundEnv) {
         transformer.transform(prio, javacProcessingEnv.getContext(), cusForThisRound, cleanup);
    }
}

-- 2、AST抽象樹
public class JavacTransformer {
    public void transform(long priority, Context context, List<jctree.jccompilationunit> compilationUnits,
                          CleanupRegistry cleanup) {
        JavacAST ast = new JavacAST(messager, context, unit, cleanup);
        ast.traverse(new AnnotationVisitor(priority));
        handlers.callASTVisitors(ast, priority);
    }
}

-- 3、註解處理抽象類
public abstract class JavacAnnotationHandler<t extends="" annotation=""> {
    public abstract void handle(AnnotationValues<t> annotation, JCAnnotation ast, JavacNode annotationNode);
}

-- 4、Getter註解處理
public class HandleGetter extends JavacAnnotationHandler<getter> {
    @Override 
    public void handle(AnnotationValues<getter> annotation, JCTree.JCAnnotation ast, JavacNode annotationNode) {
        JavacNode node = annotationNode.up();
        List<jctree.jcannotation> onMethod = unboxAndRemoveAnnotationParameter(ast, "onMethod", "@Getter(onMethod", annotationNode);
        switch (node.getKind()) {
            case FIELD:
                createGetterForFields(level, fields, annotationNode, true, lazy, onMethod);
                break;
        }
    }
}
```

IdKey類從簡潔的原始碼編譯為複雜的位元組碼檔案，透過註解對結構處理時關聯一個核心概念，叫AST抽象樹，會涉及到很多語法、詞法的解析邏輯；

# 四、自定義註解

在系統開發中透過自定義註解可以處理各種麻煩的重複邏輯，其最明顯的好處就是可以大量的消除冗餘的程式碼塊；

## 1、同步控制

程式碼中可能存在很多方法是限制重複請求的，加鎖處理是很常用的手段，此時完全可以透過註解結合AOP切面程式設計簡化程式碼的複雜程度；

```java
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface SyncLock {
    String lockKey();           // 鎖的Key
    int time () default 3000 ;  // 有效時間
    int retryNum () default 3 ; // 重試次數
}
```

透過註解標記在方法上，可以極大簡化同步鎖的編碼步驟，只是在讀取KEY的時候需要設計好解析規則，結合反射原理進行獲取即可；

基於相同的原理，也適應與日誌採集、系統告警等功能，在之前的內容中都有詳細的總結；

## 2、型別引擎

在資料處理的邏輯中，經常有這樣一種場景，同一份資料要動態推送到多種資料來源中儲存，比如常見的MySQL表和ES索引雙寫模式，這就需要對實體物件做不同的解析邏輯；

![](http://img.blog.itpub.net/blog/2022/11/14/d9f67af49b9d2a0f.png?x-oss-process=style/bb)

```java
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface BizType {
    EsIndexEnum esIndexEnum () ;        // ES索引解析適配
    MySqlTableEnum mySqlTableEnum () ;  // MySQL表解析適配
    ExcelEnum excelEnum () ;            // Excel解析適配
}
```

首先宣告一個型別解析的註解，可以標記在實體物件的欄位屬性上，然後根據各種資料來源的型別列舉，去適配不同解析工廠的執行邏輯，比如常用資料型別、格式、或者完全自定義。

# 五、參考原始碼

```
程式設計文件：
https://gitee.com/cicadasmile/butte-java-note

應用倉庫：
https://gitee.com/cicadasmile/butte-flyer-parent
```</jctree.jcannotation></getter></getter></t></t></jctree.jccompilationunit>

Java註解與原理分析

相關文章