3. Spring返回统一结果包

PangHu大约 5 分钟

1. 前言🔥

现如今是前后端分离的时代，如果没有统一的返回格式，给前端的结果各式各样，估计前端小伙伴就要骂街了。我们想对自定义异常抛出指定的状态码排查错误，对系统的不可预知的异常抛出友好一点的异常信息。我们想让接口统一返回一些额外的数据，例如接口执行的时间等等。

所以嘛，不管是日常和前端小伙伴对接，还是和其他部门进行接口对接，都应该返回固定的格式。本文给出一个简单通用的返回格式，小伙伴们有需求，可以基于此版本根据自己的业务需求丰富返回格式。

统一结果的返回数据格式如下，有兴趣的小伙伴们可以继续往下看SpringBoot是怎么来实现的。演示如下：

json复制代码{
  "code": 200,
  "msg": "成功",
  "serverTime": 1686726816292,
  "data": [
    {
      "id": 1,
      "name": "刘亦菲",
      "age": 70,
      "sex": "女",
      "address": "上海闵行",
      "describes": "这是db1的用户",
      "image": "bug菌.jpg"
    }
  ],
  "success": true
}

那么，具体如何封装包装呢？

2. 环境说明🔥

本地的开发环境：
开发工具：IDEA 2021.3
JDK版本： JDK 1.8
Spring Boot版本：2.3.1 RELEASE
Maven版本：3.8.2

3. 正文🔥

看了如下格式演示，想必有的小伙伴就很好奇，这到底是如何实现的？很简单，接下来我就带着大家手把手教学。

3.1 定义统一返回格式类

首先我们先定义好一个统一的返回格式类，代码如下：

/**
 * 接口返回结果，不带对象的
 */
@ApiModel(value = "基础返回信息", description = "基础返回信息")
public class BaseResponse implements Serializable {

    private static final long serialVersionUID = -7671756385477179547L;

    /**
     * api返回码
     */
    @ApiModelProperty("返回编码")
    protected Integer code = ResultEnum.SUCCESS.getKey();
    /**
     * api返回消息
     */
    @ApiModelProperty("返回信息")
    protected String msg = ResultEnum.SUCCESS.getValue();

    /**
     * 服务器时间
     */
    @ApiModelProperty("系统时间")
    protected long serverTime = System.currentTimeMillis();

    public BaseResponse() {

    }

    public BaseResponse(IEnum iEnum) {
        this.code = iEnum.getKey();
        this.msg = iEnum.getValue();
    }

    public BaseResponse(String msg) {
        this.msg = msg;
    }

    public Integer getCode() {
        return code;
    }

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

    public String getMsg() {
        return msg;
    }

    public void setMsg(String msg) {
        this.msg = msg;
    }

    public long getServerTime() {
        return serverTime;
    }

    public void setServerTime(long serverTime) {
        this.serverTime = serverTime;
    }

    /**
     * 是否成功
     */
    @ApiModelProperty("是否成功")
    public boolean isSuccess() {
        return ResultEnum.SUCCESS.getKey().equals(code);
    }
}

如上我们是定义了一个不带对象返回的同一类，如果我们要返回具体的数据对象呢？那我们再创建一个带对象返回的类即可。代码如下：

/**
 * 接口返回结果，带对象
 */
@ApiModel(value = "带内容的返回信息",description = "带内容的返回信息")
public class ResultResponse<T> extends BaseResponse {

	@ApiModelProperty("返回内容")
	private T data;

	public T getData() {
		return data;
	}

	public void setData(T data) {
		this.data = data;
	}

	public ResultResponse() {

	}

	public ResultResponse(T data) {
		this.data = data;
	}

	public ResultResponse(IEnum iEnum) {
		super(iEnum);
	}
}

3.2 定义一个Controller

接下来我们来演示下如何使用它。我们其实只需要将ResultResponse作为返回类，然后在该方法中我们通过new ResultResponse<>(result）即可。代码如下：

/**
 * 不分页查询db1所有用户信息
 */
@GetMapping("/get-users1")
@ApiOperation(value = "不分页查询db1所有用户信息", notes = "不分页查询db1所有用户信息")
public ResultResponse<List<UserEntity>> getUserList1() {
    return new ResultResponse<>(userService.getUsers1());
}

3.3 Swagger测试

我们通过Swagger来请求一下，我们可以看到。

这样我们就生成了统一的返回包装，是不是看起来就优雅多了。

我们再来测试一下，如果返回报错，又该是如何？

我们还是定义一个请求，我们直接通过抛出异常试试。

@GetMapping("/get-users1")
public ResultResponse<List<UserEntity>> getUserList1() {
    return new ResultResponse<>(ErrorCodeEnum.SYSTEM_ERROR);
}

我们请求Swagger来查阅下结果。

结果依旧如此，未曾有改变，证明无论是正常返回还是异常抛出，皆不会影响。

但是，你们有没有发现，这样的代码入侵性强，所有的返回结果都要处理。那有没有办法能一劳永逸的，每次的请求都会自动将其包装类修饰后返回呢？答案肯定是有的，spring拥有各种切面的支持，让我们看看如何代码无侵入的实现这个功能。

3.4 切面处理，代码无侵入

我们来创建一个配置类，添加@RestControllerAdvice注解，代码如下：

less复制代码import com.alibaba.fastjson.JSON;
import com.example.demo.vo.ResultResponse;
import lombok.extern.slf4j.Slf4j;
import org.springframework.core.MethodParameter;
import org.springframework.http.MediaType;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.http.server.ServerHttpRequest;
import org.springframework.http.server.ServerHttpResponse;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;

import javax.validation.constraints.NotNull;

@Slf4j
@RestControllerAdvice
public class RestResponseAdvice implements ResponseBodyAdvice<Object> {

    @Override
    public boolean supports(@NotNull MethodParameter returnType,
                            @NotNull Class<? extends HttpMessageConverter<?>> converterType) {
        return true;
    }

    /**
     * 返回结果包装统一返回格式
     *
     * @return 包装后的返回结果
     */
    @Override
    public Object beforeBodyWrite(Object body,
                                  @NotNull MethodParameter returnType,
                                  @NotNull MediaType selectedContentType,
                                  @NotNull Class<? extends HttpMessageConverter<?>> selectedConverterType,
                                  @NotNull ServerHttpRequest request,
                                  ServerHttpResponse response) {
        // 指定返回的结果为application/json格式
        // 不指定，String类型转json后返回Content-Type是text/plain;charset=UTF-8
        response.getHeaders().setContentType(MediaType.APPLICATION_JSON);
        ResultResponse result = new ResultResponse(body);
        // 若返回类型是ResultJson，则不进行修改
        if (body == null) {
            if (returnType.getParameterType().isAssignableFrom(String.class)) {
                return JSON.toJSONString(result);
            }
        } else if (body instanceof ResultResponse) {
            return body;
        } else if (body instanceof String) {
            return JSON.toJSONString(result);
        }
        return result;
    }
}

接下来，我们来测试一下，直接定义一个不带ResultResponse类包装的请求。

3.5 定义一个不带返回格式的Controller

Controller代码如下：

less复制代码    /**
     * 根据id查询区分性别返回不同结构体内容
     */
    @GetMapping("/get-user-for-id")
    @ApiOperation(value = "根据id查询区分性别返回不同结构体内容", notes = "根据id查询区分性别返回不同结构体内容")
    public List<UserEntity> getUserInfo(@RequestParam Integer id) {
        return userMapper.getUserByIdFor(id);
    }

如上明显我是直接返回了，不带 ResultResponse类包装，我们来期待一下，切面是否生效。

3.6 Swagger测试请求

我们访问Swagger地址：http://localhost:8080/doc.html，找到我们定义的请求。

很明显，切面完全是设置上了，被统一返回体封装。这样统一返回格式就完成了，对代码没有的侵入，原来的代码该怎么写还是怎么写，是不是很nice很棒呢。

3.7 @RestControllerAdvice

使用@RestControllerAdvice，常做的两个功能的实现有如下。

返回统一格式的结果。
异常统一处理。

如上场景功能我上期也做了定义GlobalExceptionHandler全局异常处理器，同样是使用了@RestControllerAdvice注解进行功能点实现，这里我就不详细介绍了，有想法的小伙伴可以前去观摩一下。