Spring注解之@RestControllerAdvice

前言

    前段時間部門搭建新系統，需要出異常后統一接口的返回格式，於是用到了Spring的注解@RestControllerAdvice。現在把此注解的用法總結一下。

用法

    首先定義返回對象ResponseDto

package com.staff.points.common;

import lombok.Data;

import java.io.Serializable;

@Data
public class ResponseDto<T> implements Serializable {
    private static final long serialVersionUID = -284719732991678911L;

    private String code;

    private String message;

    private T data;

    public static <T> ResponseDto<T> assemblingSuccessResponse(T data) {
        ResponseDto<T> responseDto = new ResponseDto<>();
        responseDto.setCode(ResponseCodeEnum.SUCCESS.getCode());
        responseDto.setMessage(ResponseCodeEnum.SUCCESS.getMessage());
        responseDto.setData(data);
        return responseDto;
    }

    public static <T> ResponseDto<T> assemblingSuccessResponse() {
        ResponseDto<T> responseDto = new ResponseDto<>();
        responseDto.setCode(ResponseCodeEnum.SUCCESS.getCode());
        responseDto.setMessage(ResponseCodeEnum.SUCCESS.getMessage());
        responseDto.setData(null);
        return responseDto;
    }

    public static <T> ResponseDto<T> assemblingFailureResponse(ResponseCodeEnum data) {
        ResponseDto<T> responseDto = new ResponseDto<>();
        responseDto.setCode(data.FAILURE.getCode());
        responseDto.setMessage(data.FAILURE.getMessage());
        return responseDto;
    }

    public static <T> ResponseDto<T> assemblingFailureResponse() {
        ResponseDto<T> responseDto = new ResponseDto<>();
        responseDto.setCode(ResponseCodeEnum.FAILURE.getCode());
        responseDto.setMessage(ResponseCodeEnum.FAILURE.getMessage());
        return responseDto;
    }
}

    然后定義返回碼的枚舉類，此處只定義了兩種，有需要可以往下添加很多。

package com.staff.points.common;

import lombok.AllArgsConstructor;
import lombok.Getter;

@AllArgsConstructor
@Getter
public enum ResponseCodeEnum {
    SUCCESS("00", "成功"),
    FAILURE("01", "系統異常");


    private String code;
    private String message;
}

    下面是自定義的異常類

package com.staff.points.common;

import lombok.Data;

@Data
public class StaffPointsException extends RuntimeException{
    private String code;
    private String message;
    public StaffPointsException () {}

    public StaffPointsException (Exception e) {
        super(e);
    }

    public StaffPointsException (String code, String message) {
        super(message);
        this.code = code;
        this.message = message;
    }

    public StaffPointsException (ResponseCodeEnum codeEnum) {
        super(codeEnum.getMessage());
        this.code = codeEnum.getCode();
        this.message = codeEnum.getMessage();
    }
}

    然后是關鍵的@RestControllerAdvice修飾的類

package com.staff.points.exception;

import com.staff.points.common.ResponseCodeEnum;
import com.staff.points.common.ResponseDto;
import com.staff.points.common.StaffPointsException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
@Component
public class UnifyExceptionHandler {
    private Logger logger = LoggerFactory.getLogger(UnifyExceptionHandler.class);

    @ExceptionHandler(Exception.class)
    public ResponseDto handlerCommonException (Exception e) {
        ResponseDto responseDto = new ResponseDto<>();
        responseDto.setCode(ResponseCodeEnum.FAILURE.getCode());
        responseDto.setMessage(ResponseCodeEnum.FAILURE.getMessage());
        logger.info("UnifyExceptionHandler.handlerCommonException exception:" + e);
        return responseDto;
    }
    // 報StaffPointException時，對其進行攔截並處理的方法
    @ExceptionHandler(StaffPointsException.class)
    public ResponseDto handlerCustomizeException (StaffPointsException e) {
        ResponseDto responseDto = new ResponseDto<>();
        responseDto.setCode(e.getCode());
        responseDto.setMessage(e.getMessage());
        logger.info("UnifyExceptionHandler.handlerCustomizeException StaffPointsException:" + e);
        return responseDto;
    }
}

    運行代碼時，如果出現了StaffPointException，那么就會被攔截進入第27行的方法（就是說可以自由的在業務代碼里往外throw自定義異常了）；如果出現了其他的異常，則進入18行的方法，統一返回。

驗證一下，在代碼里造一個NPE異常時，返回結果：

{
  "code": "01",
  "message": "系統異常",
  "data": null
}

    造一個StaffPointsException異常時，返回結果：

{
  "code": "99",
  "message": "自定義業務異常",
  "data": null
}

    它的作用原理，大體是先在spring初始化時將類掃描進容器，出異常后，在DispatcherServlet類的doDispatch方法中調用了對異常的攔截處理。

小結

    看@RestControllerAdvice源碼可以知道，它就是@ControllerAdvice和@ResponseBody的合並。此注解通過對異常的攔截實現的統一異常返回處理，如果大家在項目中有類似的需求，不妨試一下，好用又方便。