Spring Boot 自定义响应工具类

在开发 RESTful API 时，为了保持响应结构的一致性，公司内部一般都有标准化的响应格式。这不仅可以提高代码的可维护性，还可以帮助前端开发者更容易地处理和解析 API 响应。将展示如何在 Spring Boot 中创建一个自定义响应参数工具类，然后使用它进行返参给前端。

设计响应模型

在前后端分离项目中，前端和后端一般都是以 JSON 格式进行数据交互。而在数据格式设计上，每个公司基本大同小异，小哈习惯这样设计，如下：

接口执行成功返参格式

{
	"success": true,
	"data": null
}

• success : 是否请求成功，布尔型，true 表示接口请求成功，false 表示执行失败；
• data : 服务端响应数据，对象类型；

接口执行异常返参格式

{
	"success": false,
	"errorCode": "10000"
	"message": "用户名不能为空"
}

• message: 服务端响应消息，字符串类型，当 success 为 false 时，此字段才会不为空，用于后端返回失败的原因，方便前端弹出提示消息；
• errorCode: 异常码，字符串类型，微服务中用的比较多，通常格式为服务的唯一标识 + 异常码进行返回，如 QMS100000, 这样做的好处是，当发生问题时，用于快速锁定是链路上的哪个服务出现了问题。因为本项目是单体项目，其实用处不大，小伙伴们知道有这样的规范就行;

创建响应参数工具类

确定了格式以后，我们开始着手写响应参数工具类。在 xx-module-common 公共通用模块下新建 utils 包，然后创建 Response 工具类：

代码如下：

package com.yanxiaosheng.xx.common.utils;

import lombok.Data;

import java.io.Serializable;

/**
 * @author: 闫小生
 * @date: 2023-08-11 19:50
 * @description: 响应参数工具类
 **/
@Data
public class Response<T> implements Serializable {

    // 是否成功，默认为 true
    private boolean success = true;
    // 响应消息
    private String message;
    // 异常码
    private String errorCode;
    // 响应数据
    private T data;

    // =================================== 成功响应 ===================================
    public static <T> Response<T> success() {
        Response<T> response = new Response<>();
        return response;
    }

    public static <T> Response<T> success(T data) {
        Response<T> response = new Response<>();
        response.setData(data);
        return response;
    }

    // =================================== 失败响应 ===================================
    public static <T> Response<T> fail() {
        Response<T> response = new Response<>();
        response.setSuccess(false);
        return response;
    }

    public static <T> Response<T> fail(String errorMessage) {
        Response<T> response = new Response<>();
        response.setSuccess(false);
        response.setMessage(errorMessage);
        return response;
    }

    public static <T> Response<T> fail(String errorCode, String errorMessage) {
        Response<T> response = new Response<>();
        response.setSuccess(false);
        response.setErrorCode(errorCode);
        response.setMessage(errorMessage);
        return response;
    }
}

按照之前定义好的 JSON 格式，我们定义了 4 个字段，并添加了 success() 和 fail() 方法，分别用于快速生成执行成功的响应参数，和执行失败的响应参数，重载了的多个方法，用于适配不同场景。

在控制器中使用

有了 Response 工具类，再配合 Spring Boot 的 @RestController 或者 @ResponseBody 注解， 就可以快速生成 JSON 格式的响应数据了。重写前面小节中 TestController 中 /test 接口的返参：

	@PostMapping("/test")
    @ApiOperationLog(description = "测试接口")
    public Response test(@RequestBody @Validated User user, BindingResult bindingResult) {
        // 是否存在校验错误
        if (bindingResult.hasErrors()) {
            // 获取校验不通过字段的提示信息
            String errorMsg = bindingResult.getFieldErrors()
                    .stream()
                    .map(FieldError::getDefaultMessage)
                    .collect(Collectors.joining(", "));

            return Response.fail(errorMsg);
        }

        // 返参
        return Response.success();
    }

扩展响应工具类

上面的工具类功能相对基础。随着后续功能的增加，我们还需要添加更多的辅助方法，例如支持传入异常枚举、分页数据等。这些功能，等后面小节中我们再一一实现它们。本小节暂时不做讲解。

测试看下效果

重启项目，通过 Apifox 工具对 /test 进行 Post 请求，看下现在的接口是否是以 JSON 格式数据进行返回了。

接口响应失败

接口响应成功