SpringBoot接口格式和规范

SpringBoot接口格式

概述：通过对接口返回格式的统一定义方便接收方统一调用和发送端处理。

通过对响应类型的枚举定义、返回格式的模板化、springboot的统一返回拦截处理和统一返回异常处理。

接口响应标准定义

{
    "code": 10001,
    "message": "XXXX",
    "data": {
        "XXX": "XXX"
    }
}

响应枚举类型

public class Enum ResultEnum{
	SUCCESS(1000,"成功"),
    SYSTEM_ERROR(5000,"系统内部异常"),
   	//追加自定义类型
    ;
    private Integer code;
    private String message;
    ResultEnum(Integer code, String message) {
        this.code = code;
        this.message = message;
    }
}

返回类型格式

@Data
public class Result<T>{
    private Integer code;
    private String  message;
    private T data;

    /**
     * 定义成功无返回值方法
     * @return
     */
    public static  Result successResult() {
        return getSuccessResult();
    }

    /**
     * 定义成功有data方法
     * @param data
     * @return
     */
    public static  Result successResult(Object data) {
        Result result =getSuccessResult();
        result.setData(data);
        return result;
    }
    private static Result getSuccessResult(){
        Result result = new Result();
        result.setCode(ResultEnum.SUCCESS.getCode());
        result.setMessage(ResultEnum.SUCCESS.getMessage());
        return result;
    }

    /**
     * 定义异常无返回值方法
     * @return
     */
    public static  Result errorResult() {
        return getErrorResult();
    }

    /**
     * 定义成异常有data方法
     * @param data
     * @return
     */
    public static  Result errorResult(Object data) {
        Result result =getErrorResult();
        result.setData(data);
        return result;
    }
    private static Result getErrorResult(){
        Result result = new Result();
        result.setCode(ResultEnum.SYSTEM_ERROR.getCode());
        result.setMessage(ResultEnum.SYSTEM_ERROR.getMessage());
        return result;
    }

    /**
     * 根据ResultEnum获取返回值信息
     * @param resultEnum
     * @param data
     * @return
     */
    public static  Result result(ResultEnum resultEnum,Object data) {
        Result result = new Result();
        result.setCode(resultEnum.getCode());
        result.setMessage(resultEnum.getMessage());
        result.setData(data);
        return result;
    }
}

全局返回值

ResponseBodyAdvice<Object>接口 源码阅读

ResponseBodyAdvice的作用：拦截Controller方法的返回值，统一处理返回值/响应体，一般用来做response的统一格式、加解密、签名等等。

public interface ResponseBodyAdvice <T> {
    //是否支持拦截
    boolean supports(org.springframework.core.MethodParameter methodParameter, java.lang.Class<? extends org.springframework.http.converter.HttpMessageConverter<?>> aClass);
	//自定义的接口处理
    @org.springframework.lang.Nullable
    T beforeBodyWrite(@org.springframework.lang.Nullable T t, org.springframework.core.MethodParameter methodParameter, org.springframework.http.MediaType mediaType, java.lang.Class<? extends org.springframework.http.converter.HttpMessageConverter<?>> aClass, org.springframework.http.server.ServerHttpRequest serverHttpRequest, org.springframework.http.server.ServerHttpResponse serverHttpResponse);
}

自定义的ResponseHandler

//全局拦截包定义
@RestControllerAdvice(basePackages = "com.xxx.controller")
public class ResponseHandler implements ResponseBodyAdvice<Object> {
    @Override
    public boolean supports(MethodParameter methodParameter, Class<? extends HttpMessageConverter<?>> aClass) {
        return true;
    }

    @Override
    public Object beforeBodyWrite(Object o, MethodParameter methodParameter, MediaType mediaType, Class<?
            extends HttpMessageConverter<?>> aClass, ServerHttpRequest serverHttpRequest,
                                  ServerHttpResponse serverHttpResponse) {
        //对返回的Object对象处理
        //String 格式是比较特殊的
        if (o instanceof String) {
            return JSONObject.toJSONString(Result.successResult(o));
        }
        return Result.successResult(o);
    }
}

异常处理接口

@RestControllerAdvice，Springboot提供的对所有的全局处理方法。

它通常用来定义@ExceptionHandler， @InitBinder以及@ModelAttribute 适用于所有方法@RequestMapping的方法。

1. 异常处理。
2. 在其执行之前初始化数据绑定器。
3. 把值绑定到Model中，使全局@RequestMapping可以获取到该值。

@RestControllerAdvice
public class GlobalExceptionAdvice {
    /**
     * 处理运行时异常
     */
    //定义返回值response的httpcode
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    @ExceptionHandler(Throwable.class)
    public Result handleThrowable(Throwable e, HttpServletRequest request) {
        //结合ErrorResult对异常及结果信息进行捕获返回
        return errorResult;
    }

    /**
     * 处理自定义异常
     */
    @ExceptionHandler(BusinessException.class)
    public Result handleBusinessException(BusinessException e, HttpServletRequest request) {
        //结合ErrorResult对异常及结果信息进行捕获返回
        return errorResult;
    }
}

自定义异常

自定义异常定义使用

参数的校验。处理，空值对象的引用（NullPointerException）、数组下标越界（ArrayIndexOutBoundException）

public class BusinessException extends RuntimeException {

    protected Integer code;

    protected String message;

    public  BusinessException(ResultEnum resultEnum){
        this.code = resultEnum.getCode();
        this.errMsg = resultEnum.getMsg();
    }

    public Integer getCode() {
        return code;
    }

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

    public String getErrMsg() {
        return errMsg;
    }

    public void setErrMsg(String errMsg) {
        this.errMsg = errMsg;
    }
}