详解SpringBoot 统一后端返回格式的方法

目录

• 为什么要对SpringBoot返回统一的标准格式
• 定义返回标准格式
• 定义返回对象
• 定义状态码
• 统一返回格式
• 高级实现方式
• 接口异常问题
• SpringBoot为什么需要全局异常处理器
• 如何实现全局异常处理器
• 体验效果
• 全局异常接入返回的标准格式

首先我们来看看为什么要返回统一的标准格式？

为什么要对SpringBoot返回统一的标准格式

在默认情况下，SpringBoot的返回格式常见的有三种：

第一种：返回 String

@GetMapping("/hello")
public String getStr(){
  return "hello,javadaily";
}

此时调用接口获取到的返回值是这样：

hello,javadaily

第二种：返回自定义对象

@GetMapping("/aniaml")
public Aniaml getAniaml(){
  Aniaml aniaml = new Aniaml(1,"pig");
  return aniaml;
}

此时调用接口获取到的返回值是这样：

{
  "id": 1,
  "name": "pig"
}

第三种：接口异常

@GetMapping("/error")
public int error(){
    int i = 9/0;
    return i;
}

此时调用接口获取到的返回值是这样：

{
  "timestamp": "2021-07-08T08:05:15.423+00:00",
  "status": 500,
  "error": "Internal Server Error",
  "path": "/wrong"
}

基于以上种种情况，如果你和前端开发人员联调接口她们就会很懵逼，由于我们没有给他一个统一的格式，前端人员不知道如何处理返回值。

还有甚者，有的同学比如小张喜欢对结果进行封装，他使用了Result对象，小王也喜欢对结果进行包装，但是他却使用的是Response对象，当出现这种情况时我相信前端人员一定会抓狂的。

所以我们项目中是需要定义一个统一的标准返回格式的。

定义返回标准格式

一个标准的返回格式至少包含3部分：

1. status 状态值：由后端统一定义各种返回结果的状态码
2. message 描述：本次接口调用的结果描述
3. data 数据：本次返回的数据。

{
  "status":"100",
  "message":"操作成功",
  "data":"hello,javadaily"
}

当然也可以按需加入其他扩展值，比如我们就在返回对象中添加了接口调用时间

timestamp: 接口调用时间

定义返回对象

@Data
public class ResultData {
  /** 结果状态 ,具体状态码参见ResultData.java*/
  private int status;
  private String message;
  private T data;
  private long timestamp ;
  public ResultData (){
    this.timestamp = System.currentTimeMillis();
  }
  public static  ResultData success(T data) {
    ResultData resultData = new ResultData<>();
    resultData.setStatus(ReturnCode.RC100.getCode());
    resultData.setMessage(ReturnCode.RC100.getMessage());
    resultData.setData(data);
    return resultData;
  }
  public static  ResultData fail(int code, String message) {
    ResultData resultData = new ResultData<>();
    resultData.setStatus(code);
    resultData.setMessage(message);
    return resultData;
  }
}

定义状态码

public enum ReturnCode {
    /**操作成功**/
    RC100(100,"操作成功"),
    /**操作失败**/
    RC999(999,"操作失败"),
    /**服务限流**/
    RC200(200,"服务开启限流保护,请稍后再试!"),
    /**服务降级**/
    RC201(201,"服务开启降级保护,请稍后再试!"),
    /**热点参数限流**/
    RC202(202,"热点参数限流,请稍后再试!"),
    /**系统规则不满足**/
    RC203(203,"系统规则不满足要求,请稍后再试!"),
    /**授权规则不通过**/
    RC204(204,"授权规则不通过,请稍后再试!"),
    /**access_denied**/
    RC403(403,"无访问权限,请联系管理员授予权限"),
    /**access_denied**/
    RC401(401,"匿名用户访问无权限资源时的异常"),
    /**服务异常**/
    RC500(500,"系统异常，请稍后重试"),
    INVALID_TOKEN(2001,"访问令牌不合法"),
    ACCESS_DENIED(2003,"没有权限访问该资源"),
    CLIENT_AUTHENTICATION_FAILED(1001,"客户端认证失败"),
    USERNAME_OR_PASSWORD_ERROR(1002,"用户名或密码错误"),
    UNSUPPORTED_GRANT_TYPE(1003, "不支持的认证模式");
    /**自定义状态码**/
    private final int code;
    /**自定义描述**/
    private final String message;
    ReturnCode(int code, String message){
        this.code = code;
        this.message = message;
    }
    public int getCode() {
        return code;
    }
    public String getMessage() {
        return message;
    }
}

统一返回格式

@GetMapping("/hello")
public ResultData getStr(){
 return ResultData.success("hello,javadaily");
}

此时调用接口获取到的返回值是这样：

{
  "status": 100,
  "message": "hello,javadaily",
  "data": null,
  "timestamp": 1625736481648,
  "httpStatus": 0
}

这样确实已经实现了我们想要的结果，我在很多项目中看到的都是这种写法，在Controller层通过ResultData.success()对返回结果进行包装后返回给前端。

看到这里我们不妨停下来想想，这样做有什么弊端呢？

最大的弊端就是我们后面每写一个接口都需要调用ResultData.success()这行代码对结果进行包装，重复劳动，浪费体力；

而且还很容易被其他老鸟给嘲笑。

 

所以呢我们需要对代码进行优化，目标就是不要每个接口都手工制定ResultData返回值。

高级实现方式

要优化这段代码很简单，我们只需要借助SpringBoot提供的ResponseBodyAdvice即可。

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

先来看下ResponseBodyAdvice的源码：

public interface ResponseBodyAdvice {
  /**
  * 是否支持advice功能
  * true 支持，false 不支持
  */
    boolean supports(MethodParameter var1, Class> var2);

   /**
  * 对返回的数据进行处理
  */
    @Nullable
    T beforeBodyWrite(@Nullable T var1, MethodParameter var2, MediaType var3, Class> var4, ServerHttpRequest var5, ServerHttpResponse var6);
}

我们只需要编写一个具体实现类即可

/**
 * @author jam
 * @date 2021/7/8 10:10 上午
 */
@RestControllerAdvice
public class ResponseAdvice implements ResponseBodyAdvice