高階工程師-Java註解

高階工程師-Java註解

前言

程式碼，就是我們身為程式設計師的名片。

簡潔，優雅，統一，是我們的追求。

優秀的程式碼，會給瀏覽者一種藝術的美感。如DL大神的JUC包，感興趣的小夥伴，可以研究一下。

那麼日常中，各位看到的優秀程式碼，有著哪些特點呢？充分利用的工具類（lang3，lombok，Validation等等），完善的註解，統一的程式碼規範等等。還有的，就是Java語言的諸多高階特性（lambda，stream，io等）。

Java語言中，有三個特性，是高階工程師不可或缺的：

• 註解
• 反射
• 泛型

如果程式碼中，存在這些東西，那麼即使應用得還不夠合理，也能夠從側面證明這位程式設計師的技術追求。

這三點是初級工程師很難掌握的，因為缺乏瞭解與需求（或者說想不到對應的需求）。而高階工程師為了給出更加具有通用性，業務無侵入的程式碼，就常常需要與這些特性打交道。

在不斷積累後的今天，我覺得我可以嘗試寫一寫自己對這些特性的認識了。

今天就從註解開始，闡述我對高階工程師的一些編碼認識。

簡介

我發現很多小夥伴總是在喜歡記憶一些註解的功能，比如表示非空的@NotNull等。

這裡，我要從功能與原理角度說明兩點：

• 功能：註解是一種“增強型”的註釋。只不過相對於只能給人看的註釋，註解可以給電腦（JVM，程式等）看。
• 原理：註解的底層是Annotation介面的繼承者。只不過相對於日常使用的介面，註解需要使用@interface，但是編譯的結果依舊是介面繼承（如TestAnnotation extend Annotation）。

請大家牢記上面兩點，這是有關注解認識的絕對核心。

只要大家抓住這兩個角度去認識註解，那麼很快就可以成為註解達人。後續很多闡述都會從這兩個角度，去為大家解釋。如為什麼人們常說註解是無法繼承的，為什麼需要元註解等等。

註解的目錄結構

其實可以看到，JDK中有關注解的內容很少，非常適合作為三大特性的入門啊。因為註解的實現基礎是存在於JVM中的，JDK只是提供了對應的工具。

Annotation介面

上面提到註解的底層是介面，這裡以圖為證。

注意，仔細看這個介面的註釋。註釋中明確提出，雖然註解的本質是介面。但是直接引用Annotation介面，是無法實現註解功能的。

元註解

簡介

通俗來說，元註解就是註解的註解。

首先元註解，是Java自帶的預置註解。從這個角度，需要與@XXX修飾的自定義註解進行區分。

站在功能上來說，元註解就是專門修飾註解的“註釋”，用來告訴編譯器，虛擬機器，相關的資訊（如執行時間，目標物件）。

站在原理上來說，元註解也是註解，也是使用了@interface（底層依舊是繼承Annotation介面）。

不過註解，在底層實現已經繼承Annotation介面，那麼就無法通過繼承介面的方式（Java不支援多重繼承），來儲存元註解的資訊（尤其這個資訊往往不止一類）。那麼註解的元註解資訊是如何儲存，並交給計算機的呢？答案就是通過RuntimeVisibleAnnotations進行相關資訊的儲存的。以下就是對DynamicPropertyVerification註解反編譯的結果，重點在於反編譯結果的最後一段。

	Classfile /D:/IDEA_Project/IdeaProjects/learning/demo/target/classes/tech/jarry/learning/demo/common/anno/DynamicPropertyVerification.class
	  Last modified Apr 12, 2020; size 899 bytes
	  MD5 checksum 72657e8b89f0de070bf7085b0dd975da
	  Compiled from "DynamicPropertyVerification.java"
	public interface tech.jarry.learning.demo.common.anno.DynamicPropertyVerification extends java.lang.annotation.Annotation
	  minor version: 0
	  major version: 52
	  flags: ACC_PUBLIC, ACC_INTERFACE, ACC_ABSTRACT, ACC_ANNOTATION
	Constant pool:
	   #1 = Class              #28            // tech/jarry/learning/demo/common/anno/DynamicPropertyVerification
	   #2 = Class              #29            // java/lang/Object
	   #3 = Class              #30            // java/lang/annotation/Annotation
	   #4 = Utf8               message
	   #5 = Utf8               ()Ljava/lang/String;
	   #6 = Utf8               AnnotationDefault
	   #7 = Utf8               property verification fail
	   #8 = Utf8               groups
	   #9 = Utf8               ()[Ljava/lang/Class;
	  #10 = Utf8               Signature
	  #11 = Utf8               ()[Ljava/lang/Class<*>;
	  #12 = Utf8               payload
	  #13 = Utf8               ()[Ljava/lang/Class<+Ljavax/validation/Payload;>;
	  #14 = Utf8               SourceFile
	  #15 = Utf8               DynamicPropertyVerification.java
	  #16 = Utf8               RuntimeVisibleAnnotations
	  #17 = Utf8               Ljava/lang/annotation/Documented;
	  #18 = Utf8               Ljava/lang/annotation/Target;
	  #19 = Utf8               value
	  #20 = Utf8               Ljava/lang/annotation/ElementType;
	  #21 = Utf8               FIELD
	  #22 = Utf8               Ljava/lang/annotation/Retention;
	  #23 = Utf8               Ljava/lang/annotation/RetentionPolicy;
	  #24 = Utf8               SOURCE
	  #25 = Utf8               Ljavax/validation/Constraint;
	  #26 = Utf8               validatedBy
	  #27 = Utf8               Ltech/jarry/learning/demo/common/anno/DynamicPropertyVerificationValidator;
	  #28 = Utf8               tech/jarry/learning/demo/common/anno/DynamicPropertyVerification
	  #29 = Utf8               java/lang/Object
	  #30 = Utf8               java/lang/annotation/Annotation
	{
	  public abstract java.lang.String message();
	    descriptor: ()Ljava/lang/String;
	    flags: ACC_PUBLIC, ACC_ABSTRACT
	    AnnotationDefault:
	      default_value: s#7
	  public abstract java.lang.Class<?>[] groups();
	    descriptor: ()[Ljava/lang/Class;
	    flags: ACC_PUBLIC, ACC_ABSTRACT
	    AnnotationDefault:
	      default_value: []Signature: #11       // ()[Ljava/lang/Class<*>;
	
	  public abstract java.lang.Class<? extends javax.validation.Payload>[] payload();
	    descriptor: ()[Ljava/lang/Class;
	    flags: ACC_PUBLIC, ACC_ABSTRACT
	    AnnotationDefault:
	      default_value: []Signature: #13       // ()[Ljava/lang/Class<+Ljavax/validation/Payload;>;
	}
	SourceFile: "DynamicPropertyVerification.java"
	RuntimeVisibleAnnotations:
	  0: #17()
	  1: #18(#19=[e#20.#21])
	  2: #22(#19=e#23.#24)
	  3: #25(#26=[c#27])

最後一段，通過RuntimeVisibleAnnotations，儲存了所需要的元註解資訊。

如果對JVM底層原理有了解的小夥伴，應該對RuntimeVisibleAnnotations不陌生。不瞭解的小夥伴，可以檢視Class RuntimeVisibleAnnotations

預置註解

元註解

元註解是Java自帶的，主要分為：

• @Rentention：表示目標註解的保持策略。其value為RetentionPolicy。如果目標註解沒有使用該註解，則預設使用RetentionPolicy.CLASS
• @Target：表示目標註解的應用目標型別。其value為ElementType。如果目標註解沒有使用該註解，則目標註解可以用於除了TYPE_PARAMETER和TYPE_USE以外的任何地方（這兩個型別都是Java8新新增的）。
• @Documented：表示目標註解可以出現在JavaDoc中。
• @Repeatable：表示目標註解可以在同一位置，重複使用。
• @Inherited：表示目標註解可以隨著所修飾的類的繼承關係，被子類繼承。

@Retention

原始碼：

	@Documented
	@Retention(RetentionPolicy.RUNTIME)
	@Target(ElementType.ANNOTATION_TYPE)
	public @interface Retention {
	    /**
	     * Returns the retention policy.
	     * @return the retention policy
	     */
	    RetentionPolicy value();
	}

通過RetentionPolicy列舉表示目標註解的保持策略。

	public enum RetentionPolicy {
	    /**
	     * 目標註解會在編譯期丟失
	     */
	    SOURCE,
	
	    /**
	     * 預設行為。雖然目標註解會通過編譯，儲存至.class檔案中，但是JVM不會在執行時識別該註解。
	     */
	    CLASS,
	
	    /**
	     * 常用行為。目標註解會儲存至.class檔案中，JVM會在執行時識別，並記錄該註解。所以可以通過反射獲取對應的資訊。
	     * 詳見 java.lang.reflect.AnnotatedElement
	     */
	    RUNTIME
	}

為了便於大家理解，這裡再舉一些例子。這裡挑選一些Java自帶的，不用大家再去自己寫demo，增加認知負荷：

• @Retention（RetentionPolicy.SOURCE)：如@Override註解，由於該註解只是用於進行程式碼檢測，所以只要存在於原始碼中即可，故選擇RetentionPolicy.SOURCE。類似的還有@SuppressWarnings註解等。
• @Retention（RetentionPolicy.CLASS)：涉及註解處理器，所以例項很少。可以檢視自定義註解之編譯時註解(RetentionPolicy.CLASS)（一）。
• @Retention（RetentionPolicy.RUNTIME)：如@Deprecated，由於該註解需要在執行時提示使用者註解修飾的方法，類等已經過時，所以需要JVM中有對應“註釋”資訊，故採用RetentionPolicy.RUNTIME。類似的還有@Repeatable等。

@Target

	@Documented
	@Retention(RetentionPolicy.RUNTIME)
	@Target(ElementType.ANNOTATION_TYPE)
	public @interface Target {
	    /**
	     * Returns an array of the kinds of elements an annotation type
	     * can be applied to.
	     * @return an array of the kinds of elements an annotation type
	     * can be applied to
	     */
	    ElementType[] value();
	}

通過ElementType列舉表示目標註解的應用目標型別。

	public enum ElementType {
	    /** 類，介面（包括註解，即Annotation介面），或者列舉型別 */
	    TYPE,
	
	    /** 屬性 (包括列舉常量，列舉常量示例：Retention.SOURCE) */
	    FIELD,
	
	    /** 方法 */
	    METHOD,
	
	    /** 形參（形式引數） */
	    PARAMETER,
	
	    /** 構造器 */
	    CONSTRUCTOR,
	
	    /** 本地變數 */
	    LOCAL_VARIABLE,
	
	    /** 註解型別 */
	    ANNOTATION_TYPE,
	
	    /** 包 */
	    PACKAGE,
	
	    /**
	     * 型別引數（針對資料型別）
	     * @since 1.8
	     */
	    TYPE_PARAMETER,
	
	    /**
	     * 型別（功能域包含PARAMETER與TYPE_PARAMETER）
	     * @since 1.8
	     */
	    TYPE_USE
	}

這裡不會一一舉例，只會點出重點：

• TYPE_PARAMETER與TYPE_USE是Java8新增加的。所以使用Java7的小夥伴要注意。
• ElementType.TYPE涵蓋範圍很廣泛，在不知用哪個時，可以先用這個。

@Documented

預設情況下，註解是不出現在 javadoc 中的。通過給目標註解加上 @Documented 元註解，能使目標註解出現在 javadoc 中。

從原始碼可以看出，@Documented是一個沒有任何成員的標記註解。

@Repeatable

@Repeatable註解的使用，引用一個不錯的demo。

	package com.zejian.annotationdemo;
	import java.lang.annotation.*;/**
	* Created by zejian on 2017/5/20.
	*/
	@Target({ElementType.TYPE,ElementType.FIELD,ElementType.METHOD})
	@Retention(RetentionPolicy.RUNTIME)
	@Repeatable(FilterPaths.class)
	public @interface FilterPath {
	   String  value();
	}
	
	@Target(ElementType.TYPE)
	@Retention(RetentionPolicy.RUNTIME)
	@interface FilterPaths {
	   FilterPath[] value();
	}
	
	@FilterPath("/web/update")
	@FilterPath("/web/add")
	@FilterPath("/web/delete")

上述程式碼，其實分為兩個部分：

• 使用@Repeatable註解，使得其修飾的@FilterPath，可以在目標上重複標記（便於設定不同的成員變數）。
• 通過@FilterPaths註解（包含成員變數-FilterPath[] value ()），將@FilterPath集中到@FilterPaths中，便於後續邏輯處理。

@Inherited

@Inherited同樣是只能修飾註解的元註解，它所標註的目標註解具有繼承性。

這裡解釋一下這個繼承性，這並不是註解間的繼承。而是指目標註解可以隨著類的繼承，而被子類繼承。簡單說，就是目標註解修飾的類，其後代類也會被該註解標註（可以通過getAnnotation方法獲取）。

這裡不再贅述，感興趣的小夥伴，可以檢視Java 註解（Annotation）中的相關示例。

功能註解

Java預置的功能註解，主要分為：

• @Override：該註解修飾的目標方法，必須是重寫基類方法，或實現對應介面方法，否則編譯器會報錯。
• @Deprecated：該註解修飾的目標，表示已經過時，不推薦使用。編碼時，使用該註解的目標，會有劃線提示。
• @SuppressWarnings：該註解修飾的目標，將會忽略某些異常（由註解的value指定），從而通過編譯器編譯。
• @SafeVarargs：該註解修飾的建構函式（只能修飾建構函式），將會忽略可變引數帶來的警告。該註解於Java7引入。
• @FunctionalInterface：該註解修飾的介面，為函式式介面。如java.util.function下的Consumer介面，作為一個函式式介面，被該註解修飾（函式式介面不一定有該註解修飾，但被該註解修飾的介面，一定是函式式介面）。

自定義註解

到了這裡，大家應該對註解不再陌生了。
而在日常開發中，我們常常需要自定義開發一些註解。
自定義註解分為以下步驟：

1. [必選] 使用@interface來構建自定義註解。一般在建立自定義註解的同時，就達成了該要求。
2. [可選] 使用@Target元註解。通過該註解，確定自定義註解的作用目標型別。注意：如果目標註解沒有使用該註解，則目標註解可以用於除了TYPE_PARAMETER和TYPE_USE以外的任何地方（這兩個型別都是Java8新新增的）。
3. [可選] 使用@Retention元註解。通過該註解，明確自定義註解的生命週期，或者說自定義註解作用域。如果目標註解沒有使用該註解，則預設使用RetentionPolicy.CLASS
4. [可選] 新增成員變數。格式為“long value() default 1000L;”，與Java8的介面成員變數非常類似。注意：註解的成員變數只能採用無參方法表示。並且註解的成員變數，只能採用基本資料型別(char，boolean,byte、short、int、long、float、double)和String、Enum、Class、annotations資料型別,以及這一些型別的陣列。
5. [可選] 使用自定義註解。自定義註解的使用領域很多，主要分為兩個方向：
   • 利用已有框架，不需要自己實現相關邏輯，自定義註解多作為標記註解。如配合SpringBoot的註解，形成自己的註解（相關的邏輯由SpringBoot自己處理）
   • 利用已有框架，需要自己實現部分邏輯（不涉及反射），但需要關聯已有框架，並實現對應介面。如Validation框架的自定義校驗註解，感興趣的小夥伴，可以檢視我之前寫的Validation框架的應用。
   • 可選擇已有框架，需要自己實現諸多邏輯。如在AOP中，我們常常需要通過反射，獲取自定義註解的資訊（如引數等），或者自定義註解修飾的目標的資訊（如引數，方法名等）。這部分，我會在後續的反射部分詳細說明。

總結

簡單總結一下，本文主要描述了：

1. 註解是什麼：增強型的註釋，本質是介面
2. 元註解是什麼：註解的註解，作用是為了標識目標註解。包括@Target，@Retention，@Documented，@Repeatable,@Inherited.
3. 預置註解是什麼：JDK自帶的經典功能註解，如@Override，@Deprecated，@SuppressWarnings，@SafeVarargs，@FunctionalInterface。
4. 自定義註解如何實現：主要分為五步，但是其中必要的步驟，就一步：使用@interface來構建自定義註解。

至此，Java註解的內容就基本展現了。

最後，還是強調兩個方面：

1. 註解就是增強型的註釋（可被計算機識別的註釋），本質是介面。把握住這兩點，就非常好理解註解與它的各種規則，行為。
2. 註解本身並沒有任何功能（因為它只是註釋，本質也只是介面），需要其他程式碼支撐，它才能體現價值。

希望對大家有所幫助，還有不清楚的地方，可以檢視下列參考目錄。

願與諸君共進步。

附錄

參考

• Class RuntimeVisibleAnnotations
• 註解之註解的屬性
• Validation框架的應用
• Java 註解（Annotation）
• Android 註解系列之Annotation（二）
• 自定義註解之編譯時註解(RetentionPolicy.CLASS)（一）
• 註解