Java 自定義註解的魅力

註解是什麼?

①、引用自維基百科的內容:
Java註解又稱Java標註,是JDK5.0版本開始支持加入源代碼的特殊語法 元數據 。

Java語言中的類、方法、變量、參數和包等都可以被標註。和Javadoc不同,Java標註可以通過反射獲取標註內容。在編譯器生成類文件時,標註可以被嵌入到字節碼中。Java虛擬機可以保留標註內容,在運行時可以獲取到標註內容。 當然它也支持自定義Java標註。

②、引用自網絡的內容:
Java 註解是在 JDK5 時引入的新特性,註解(也被稱為 元數據 )為我們在代碼中添加信息提供瞭一種形式化的方法,使我們可以在稍後某個時刻非常方便地使用這些數據。

元註解是什麼?

元註解 的作用就是負責註解其他註解。Java5.0定義瞭4個標準的meta-annotation(元註解)類型,它們被用來提供對其它 annotation類型作說明。

標準的元註解:

@Target
@Retention
@Documented
@Inherited
在詳細說這四個元數據的含義之前,先來看一個在工作中會經常使用到的 @Autowired 註解,進入這個註解裡面瞧瞧: 此註解中使用到瞭@Target、@Retention、@Documented 這三個元註解 。

@Target({ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.PARAMETER, ElementType.FIELD, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Autowired {
    boolean required() default true;
}

@Target元註解:

@Target註解,是專門用來限定某個自定義註解能夠被應用在哪些Java元素上面的,標明作用范圍;取值在java.lang.annotation.ElementType 進行定義的。

public enum ElementType {
    /** 類,接口(包括註解類型)或枚舉的聲明 */
    TYPE,

    /** 屬性的聲明 */
    FIELD,

    /** 方法的聲明 */
    METHOD,

    /** 方法形式參數聲明 */
    PARAMETER,

    /** 構造方法的聲明 */
    CONSTRUCTOR,

    /** 局部變量聲明 */
    LOCAL_VARIABLE,

    /** 註解類型聲明 */
    ANNOTATION_TYPE,

    /** 包的聲明 */
    PACKAGE
}

根據此處可以知道 @Autowired 註解的作用范圍:

// 可以作用在 構造方法、方法、方法形參、屬性、註解類型 上
@Target({ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.PARAMETER, ElementType.FIELD, ElementType.ANNOTATION_TYPE})

@Retention元註解:

@Retention註解,翻譯為持久力、保持力。即用來修飾自定義註解的生命周期。

註解的生命周期有三個階段:

  • Java源文件階段;
  • 編譯到class文件階段;
  • 運行期階段;

同樣使用瞭RetentionPolicy 枚舉類型對這三個階段進行瞭定義:

public enum RetentionPolicy {
    /**
     * Annotations are to be discarded by the compiler.
     * (註解將被編譯器忽略掉)
     */
    SOURCE,

    /**
     * Annotations are to be recorded in the class file by the compiler
     * but need not be retained by the VM at run time.  This is the default
     * behavior.
     * (註解將被編譯器記錄在class文件中,但在運行時不會被虛擬機保留,這是一個默認的行為)
     */
    CLASS,

    /**
     * Annotations are to be recorded in the class file by the compiler and
     * retained by the VM at run time, so they may be read reflectively.
     * (註解將被編譯器記錄在class文件中,而且在運行時會被虛擬機保留,因此它們能通過反射被讀取到)
     * @see java.lang.reflect.AnnotatedElement
     */
    RUNTIME
}

再詳細描述下這三個階段:

①、如果被定義為 RetentionPolicy.SOURCE,則它將被限定在Java源文件中,那麼這個註解即不會參與編譯也不會在運行期起任何作用,這個註解就和一個註釋是一樣的效果,隻能被閱讀Java文件的人看到;

②、如果被定義為 RetentionPolicy.CLASS,則它將被編譯到Class文件中,那麼編譯器可以在編譯時根據註解做一些處理動作,但是運行時JVM(Java虛擬機)會忽略它,並且在運行期也不能讀取到;

③、如果被定義為 RetentionPolicy.RUNTIME,那麼這個註解可以在運行期的加載階段被加載到Class對象中。那麼在程序運行階段,可以通過反射得到這個註解,並通過判斷是否有這個註解或這個註解中屬性的值,從而執行不同的程序代碼段。

註意:實際開發中的自定義註解幾乎都是使用的 RetentionPolicy.RUNTIME 。

@Documented元註解:

@Documented註解,是被用來指定自定義註解是否能隨著被定義的java文件生成到JavaDoc文檔當中。

@Inherited元註解:

@Inherited註解,是指定某個自定義註解如果寫在瞭父類的聲明部分,那麼子類的聲明部分也能自動擁有該註解。

@Inherited註解隻對那些@Target被定義為 ElementType.TYPE 的自定義註解起作用。

自定義註解實現:

在瞭解瞭上面的內容後,我們來嘗試實現一個自定義註解:

根據上面自定義註解中使用到的元註解得知:

①、此註解的作用范圍,可以使用在類(接口、枚舉)、方法上;

②、此註解的生命周期,被編譯器保存在class文件中,而且在運行時會被JVM保留,可以通過反射讀取;

自定義註解的簡單使用:

上面已經創建瞭一個自定義的註解,那該怎麼使用呢?下面首先描述下它簡單的用法,後面將會使用其結合攔截器和AOP切面編程進行實戰應用;

應用場景實現

在瞭解瞭上面註解的知識後,我們乘勝追擊,看看它的實際應用場景是腫麼樣的,以此加深下我們的理解;

實現的 Demo 項目是以 SpringBoot 實現的,項目工程結構圖如下:

場景一:自定義註解 + 攔截器 = 實現接口響應的包裝

使用自定義註解 結合 攔截器 優雅的實現對API接口響應的包裝。

在介紹自定義實現的方式之前,先簡單介紹下普遍的實現方式,通過兩者的對比,才能更加明顯的發現誰最優雅。

普通的接口響應包裝方式:
現在項目絕大部分都采用的前後端分離方式,所以需要前端和後端通過接口進行交互;目前在接口交互中使用最多的數據格式是 json,然後後端返回給前端的最為常見的響應格式如下:

{
    #返回狀態碼
    code:integer,       
    #返回信息描述
    message:string,
    #返回數據值
    data:object
}

項目中經常使用枚舉類定義狀態碼和消息,代碼如下:

/**
 * @author 【 木子雷 】 公眾號
 * @Title: ResponseCode
 * @Description: 使用枚舉類封裝好的響應狀態碼及對應的響應消息
 * @date: 2019年8月23日 下午7:12:50
 */
public enum ResponseCode {

    SUCCESS(1200, "請求成功"),

    ERROR(1400, "請求失敗");


    private Integer code;

    private String message;

    private ResponseCode(Integer code, String message) {
        this.code = code;
        this.message = message;
    }

    public Integer code() {
        return this.code;
    }

    public String message() {
        return this.message;
    }

}

同時項目中也會設計一個返回響應包裝類,代碼如下:

import com.alibaba.fastjson.JSONObject;
import java.io.Serializable;

/**
 * @author 【 木子雷 】 公眾號
 * @Title: Response
 * @Description: 封裝的統一的響應返回類
 * @date: 2019年8月23日 下午7:07:13
 */
@SuppressWarnings("serial")
public class Response<T> implements Serializable {

    /**
     * 響應數據
     */
    private T date;

    /**
     * 響應狀態碼
     */
    private Integer code;

    /**
     * 響應描述信息
     */
    private String message;

    public Response(T date, Integer code, String message) {
        super();
        this.date = date;
        this.code = code;
        this.message = message;
    }


    public T getDate() {
        return date;
    }

    public void setDate(T date) {
        this.date = date;
    }

    public Integer getCode() {
        return code;
    }

    public void setCode(Integer code) {
        this.code = code;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }


    @Override
    public String toString() {
        return JSONObject.toJSONString(this);
    }
}

最後就是使用響應包裝類和狀態碼枚舉類 來實現返回響應的包裝瞭:

@GetMapping("/user/findAllUser")
public Response<List<User>> findAllUser() {
    logger.info("開始查詢所有數據...");

    List<User> findAllUser = new ArrayList<>();
    findAllUser.add(new User("木子雷", 26));
    findAllUser.add(new User("公眾號", 28));

    // 返回響應進行包裝
    Response response = new Response(findAllUser, ResponseCode.SUCCESS.code(), ResponseCode.SUCCESS.message());

    logger.info("response: {} \n", response.toString());
    return response;
}

在瀏覽器中輸入網址: http://127.0.0.1:8080/v1/api/user/findAllUser 然後點擊回車,得到如下數據:

{
    "code": 1200,
    "date": [
        {
            "age": 26,
            "name": "木子雷"
        },
        {
            "age": 28,
            "name": "公眾號"
        }
    ],
    "message": "請求成功"
}

通過看這中實現響應包裝的方式,我們能發現什麼問題嗎?

答:代碼很冗餘,需要在每個接口方法中都進行響應的包裝;使得接口方法包含瞭很多非業務邏輯代碼;

有沒有版本進行優化下呢? en en 思考中。。。。。 啊,自定義註解 + 攔截器可以實現呀!

自定義註解實現接口響應包裝:
①、首先創建一個進行響應包裝的自定義註解:

/**
 * @author 【 木子雷 】 公眾號
 * @PACKAGE_NAME: com.lyl.annotation
 * @ClassName: ResponseResult
 * @Description: 標記方法返回值需要進行包裝的 自定義註解
 * @Date: 2020-11-10 10:38
 **/
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface ResponseResult {

}

②、創建一個攔截器,實現對請求的攔截,看看請求的方法或類上是否使用瞭自定義的註解:

/**
 * @author 【 木子雷 】 公眾號
 * @PACKAGE_NAME: com.lyl.interceptor
 * @ClassName: ResponseResultInterceptor
 * @Description: 攔截器:攔截請求,判斷請求的方法或類上是否使用瞭自定義的@ResponseResult註解,
 *               並在請求內設置是否使用瞭自定義註解的標志位屬性;
 * @Date: 2020-11-10 10:50
 **/
@Component
public class ResponseResultInterceptor implements HandlerInterceptor {

    /**
     * 標記位,標記請求的controller類或方法上使用瞭到瞭自定義註解,返回數據需要被包裝
     */
    public static final String RESPONSE_ANNOTATION = "RESPONSE_ANNOTATION";

    /**
     * 請求預處理,判斷是否使用瞭自定義註解
     */
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler)
            throws Exception {
        // 請求的接口方法
        if (handler instanceof HandlerMethod) {
            final HandlerMethod handlerMethod = (HandlerMethod) handler;
            final Class<?> clazz = handlerMethod.getBeanType();
            final Method method = handlerMethod.getMethod();
            // 判斷是否在類對象上加瞭註解
            if (clazz.isAnnotationPresent(ResponseResult.class)) {
                // 在請求中設置需要進行響應包裝的屬性標志,在下面的ResponseBodyAdvice增強中進行處理
                request.setAttribute(RESPONSE_ANNOTATION, clazz.getAnnotation(ResponseResult.class));
            } else if (method.isAnnotationPresent(ResponseResult.class)) {
                // 在請求中設置需要進行響應包裝的屬性標志,在下面的ResponseBodyAdvice增強中進行處理
                request.setAttribute(RESPONSE_ANNOTATION, method.getAnnotation(ResponseResult.class));
            }
        }
        return true;
    }
}

③、創建一個增強Controller,實現對返回響應進行包裝的增強處理:

/**
 * @author 【 木子雷 】 公眾號
 * @PACKAGE_NAME: com.lyl.interceptor
 * @ClassName: ResponseResultHandler
 * @Description: 對 返回響應 進行包裝 的增強處理
 * @Date: 2020-11-10 13:49
 **/
@ControllerAdvice
public class ResponseResultHandler implements ResponseBodyAdvice<Object> {

    private final Logger logger = LoggerFactory.getLogger(this.getClass());

    /**
     * 標記位,標記請求的controller類或方法上使用瞭到瞭自定義註解,返回數據需要被包裝
     */
    public static final String RESPONSE_ANNOTATION = "RESPONSE_ANNOTATION";

    /**
     * 請求中是否包含瞭 響應需要被包裝的標記,如果沒有,則直接返回,不需要重寫返回體
     *
     * @param methodParameter
     * @param aClass
     * @return
     */
    @Override
    public boolean supports(MethodParameter methodParameter, Class<? extends HttpMessageConverter<?>> aClass) {
        ServletRequestAttributes ra = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
        HttpServletRequest sr = (HttpServletRequest) ra.getRequest();
        // 查詢是否需要進行響應包裝的標志
        ResponseResult responseResult = (ResponseResult) sr.getAttribute(RESPONSE_ANNOTATION);
        return responseResult == null ? false : true;
    }


    /**
     * 對 響應體 進行包裝; 除此之外還可以對響應體進行統一的加密、簽名等
     *
     * @param responseBody  請求的接口方法執行後得到返回值(返回響應)
     */
    @Override
    public Object beforeBodyWrite(Object responseBody, MethodParameter methodParameter, MediaType mediaType, Class<? extends HttpMessageConverter<?>> aClass, ServerHttpRequest serverHttpRequest, ServerHttpResponse serverHttpResponse) {
        logger.info("返回響應 包裝進行中。。。");
        Response response;
        // boolean類型時判斷一些數據庫新增、更新、刪除的操作是否成功
        if (responseBody instanceof Boolean) {
            if ((Boolean) responseBody) {
                response = new Response(responseBody, ResponseCode.SUCCESS.code(), ResponseCode.SUCCESS.message());
            } else {
                response = new Response(responseBody, ResponseCode.ERROR.code(), ResponseCode.ERROR.message());
            }
        } else {
            // 判斷像查詢一些返回數據的情況,查詢不到數據返回 null;
            if (null != responseBody) {
                response = new Response(responseBody, ResponseCode.SUCCESS.code(), ResponseCode.SUCCESS.message());
            } else {
                response = new Response(responseBody, ResponseCode.ERROR.code(), ResponseCode.ERROR.message());
            }
        }
        return response;
    }
}

④、最後在 Controller 中使用上我們的自定義註解;在 Controller 類上或者 方法上使用@ResponseResult自定義註解即可; 在瀏覽器中輸入網址: http://127.0.0.1:8080/v1/api/user/findAllUserByAnnotation 進行查看:

// 自定義註解用在瞭方法上
@ResponseResult
@GetMapping("/user/findAllUserByAnnotation")
public List<User> findAllUserByAnnotation() {
    logger.info("開始查詢所有數據...");

    List<User> findAllUser = new ArrayList<>();
    findAllUser.add(new User("木子雷", 26));
    findAllUser.add(new User("公眾號", 28));

    logger.info("使用 @ResponseResult 自定義註解進行響應的包裝,使controller代碼更加簡介");
    return findAllUser;
}

至此我們的接口返回響應包裝自定義註解實現設計完成,看看代碼是不是又簡潔,又優雅呢。

總結:本文針對此方案隻是進行瞭簡單的實現,如果有興趣的朋友可以進行更好的優化。

場景二:自定義註解 + AOP = 實現優雅的使用分佈式鎖

分佈式鎖的最常見的使用流程:

先看看最為常見的分佈式鎖使用方式的實現,然後再聊聊自定義註解怎麼優雅的實現分佈式鎖的使用。

普通的分佈式鎖使用方式:

通過上面的代碼可以得到一個信息:如果有很多方法中需要使用分佈式鎖,那麼每個方法中都必須有獲取分佈式鎖和釋放分佈式鎖的代碼,這樣一來就會出現代碼冗餘;

那有什麼好的解決方案嗎? 自定義註解使代碼變得更加簡潔、優雅;

自定義註解優雅的使用分佈式鎖:
①、首先實現一個標記分佈式鎖使用的自定義註解:

/**
 * @author 【 木子雷 】 公眾號
 * @PACKAGE_NAME: com.lyl.annotation
 * @ClassName: GetDistributedLock
 * @Description: 獲取redis分佈式鎖 註解
 * @Date: 2020-11-10 16:24
 **/
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface GetDistributedLock {

    // 分佈式鎖 key
    String lockKey();

    // 分佈式鎖 value,默認為 lockValue
    String lockValue() default "lockValue";

    // 過期時間,默認為 300秒
    int expireTime() default 300;

}

②、定義一個切面,在切面中對使用瞭 @GetDistributedLock 自定義註解的方法進行環繞增強通知:

/**
 * @author: 【 木子雷 】 公眾號
 * @PACKAGE_NAME: com.lyl.aop
 * @ClassName: DistributedLockAspect
 * @Description: 自定義註解結合AOP切面編程優雅的使用分佈式鎖
 * @Date: 2020-11-10 16:52
 **/
@Component
@Aspect
public class DistributedLockAspect {

    private final Logger logger = LoggerFactory.getLogger(this.getClass());

    @Autowired
    RedisService redisService;


    /**
     * Around 環繞增強通知
     *
     * @param joinPoint 連接點,所有方法都屬於連接點;但是當某些方法上使用瞭@GetDistributedLock自定義註解時,
     *                  則其將連接點變為瞭切點;然後在切點上織入額外的增強處理;切點和其相應的增強處理構成瞭切面Aspect 。
     */
    @Around(value = "@annotation(com.lyl.annotation.GetDistributedLock)")
    public Boolean handlerDistributedLock(ProceedingJoinPoint joinPoint) {
        // 通過反射獲取自定義註解對象
        GetDistributedLock getDistributedLock = ((MethodSignature) joinPoint.getSignature())
                .getMethod().getAnnotation(GetDistributedLock.class);

        // 獲取自定義註解對象中的屬性值
        String lockKey = getDistributedLock.lockKey();
        String LockValue = getDistributedLock.lockValue();
        int expireTime = getDistributedLock.expireTime();

        if (redisService.tryGetDistributedLock(lockKey, LockValue, expireTime)) {
            // 獲取分佈式鎖成功後,繼續執行業務邏輯
            try {
                return (boolean) joinPoint.proceed();
            } catch (Throwable throwable) {
                logger.error("業務邏輯執行失敗。", throwable);
            } finally {
                // 最終保證分佈式鎖的釋放
                redisService.releaseDistributedLock(lockKey, LockValue);
            }
        }
        return false;
    }

}

③、最後,在 Controller 中的方法上使用 @GetDistributedLock 自定義註解即可;當某個方法上使用瞭 自定義註解,那麼這個方法就相當於一個切點,那麼就會對這個方法做環繞(方法執行前和方法執行後)增強處理;

在瀏覽器中輸入網址: http://127.0.0.1:8080/v1/api/user/getDistributedLock 回車後觸發方法執行:

// 自定義註解的使用
@GetDistributedLock(lockKey = "userLock")
@GetMapping("/user/getDistributedLock")
public boolean getUserDistributedLock() {
    logger.info("獲取分佈式鎖...");
    // 寫具體的業務邏輯

    return true;
}

通過自定義註解的方式,可以看到代碼變得更加簡潔、優雅。

場景三:自定義註解 + AOP = 實現日志的打印

先看看最為常見的日志打印的方式,然後再聊聊自定義註解怎麼優雅的實現日志的打印。

普通日志的打印方式:

通過看上面的代碼可以知道,如果每個方法都需要打印下日志,那將會存在大量的冗餘代碼;

自定義註解實現日志打印:
①、首先創建一個標記日志打印的自定義註解:

/**
 * @Author: 【 木子雷 】 公眾號
 * @PACKAGE_NAME: com.lyl.annotation
 * @ClassName: PrintLog
 * @Description: 自定義註解實現日志打印
 * @Date: 2020-11-10 18:05
 **/
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface PrintLog {

}

②、定義一個切面,在切面中對使用瞭 @PrintLog 自定義註解的方法進行環繞增強通知:

/**
 * @author: 【 木子雷 】 公眾號
 * @PACKAGE_NAME: com.lyl.aop
 * @ClassName: PrintLogAspect
 * @Description: 自定義註解結合AOP切面編程優雅的實現日志打印
 * @Date: 2020-11-10 18:11
 **/
@Component
@Aspect
public class PrintLogAspect {

    private final Logger logger = LoggerFactory.getLogger(this.getClass());

    /**
     *  Around 環繞增強通知
     *
     * @param joinPoint 連接點,所有方法都屬於連接點;但是當某些方法上使用瞭@PrintLog自定義註解時,
     *                  則其將連接點變為瞭切點;然後在切點上織入額外的增強處理;切點和其相應的增強處理構成瞭切面Aspect 。
     */
    @Around(value = "@annotation(com.lyl.annotation.PrintLog)")
    public Object handlerPrintLog(ProceedingJoinPoint joinPoint) {
        // 獲取方法的名稱
        String methodName = joinPoint.getSignature().getName();
        // 獲取方法入參
        Object[] param = joinPoint.getArgs();

        StringBuilder sb = new StringBuilder();
        for (Object o : param) {
            sb.append(o + "; ");
        }
        logger.info("進入《{}》方法, 參數為: {}", methodName, sb.toString());

        Object object = null;
        // 繼續執行方法
        try {
            object = joinPoint.proceed();

        } catch (Throwable throwable) {
            logger.error("打印日志處理error。。", throwable);
        }
        logger.info("{} 方法執行結束。。", methodName);
        return object;
    }

}

③、最後,在 Controller 中的方法上使用 @PrintLog 自定義註解即可;當某個方法上使用瞭 自定義註解,那麼這個方法就相當於一個切點,那麼就會對這個方法做環繞(方法執行前和方法執行後)增強處理;

@PrintLog
@GetMapping(value = "/user/findUserNameById/{id}", produces = "application/json;charset=utf-8")
public String findUserNameById(@PathVariable("id") int id) {
    // 模擬根據id查詢用戶名
    String userName = "木子雷 公眾號";
    return userName;
}

④、在瀏覽器中輸入網址: http://127.0.0.1:8080/v1/api/user/findUserNameById/66 回車後觸發方法執行,發現控制臺打印瞭日志:

進入《findUserNameById》方法, 參數為: 66; 
findUserNameById 方法執行結束。。

使用自定義註解實現是多優雅,代碼看起來簡介幹凈,越瞅越喜歡;趕快去你的項目中使用吧, 嘿嘿。。。

以上就是Java 自定義註解的魅力的詳細內容,更多關於Java 自定義註解的資料請關註WalkonNet其它相關文章!