01、背景介绍

熟悉 web 系统开发的同学可能比较熟悉，目前绝大多数的互联网软件平台基本都是前后端分离的开发模式，为了加快前后端接口对接速度，一套完善且规范的接口标准格式是非常有必要的，不仅能够提升开发效率，也会让代码看起来更加简洁、好维护。

今天这篇文章，我们一起来学习一下如何在 Spring Boot 中统一接口的返回数据格式。

02、定义数据返回格式

最常见的一种做法是封装一个工具类，在类中定义需要返回的字段信息，比如状态码、结果描述、结果数据集等，然后在接口中返回给客户端。

例如如下示例。

2.1、定义返回对象

public class ResultMsg<T> {

    /**状态码**/
    private int code;

    /**结果描述**/
    private String message;

    /**结果集**/
    private T data;

    /**时间戳**/
    private long timestamp;

    // set、get方法等...

    public ResultMsg() {
        timestamp = System.currentTimeMillis();
    }

    public static <T> ResultMsg<T> success() {
        return success(null);
    }

    public static <T> ResultMsg<T> success(T data) {
        ResultMsg<T> resultMsg = new ResultMsg<>();
        resultMsg.setCode(ReturnCode.RC200.getCode());
        resultMsg.setMessage(ReturnCode.RC200.getMessage());
        resultMsg.setData(data);
        return resultMsg;
    }

    public static <T> ResultMsg<T> fail(String message) {
        return fail(ReturnCode.RC500.getCode(), message);
    }

    public static <T> ResultMsg<T> fail(ReturnCode returnCode) {
        return fail(returnCode.getCode(), returnCode.getMessage());
    }

    public static <T> ResultMsg<T> fail(int code, String message) {
        ResultMsg<T> resultMsg = new ResultMsg<>();
        resultMsg.setCode(code);
        resultMsg.setMessage(message);
        return resultMsg;
    }
}

2.2、定义状态码

public enum ReturnCode {

    /**操作成功**/
    RC200(200,"请求成功"),

    /**access_denied**/
    RC403(403,"无访问权限,请联系管理员授予权限"),

    /**服务异常**/
    RC500(500,"系统异常，请稍后重试");

    /**自定义状态码**/
    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;
    }
}

2.3、统一返回格式

@RestController
public class UserController {
    
    @Autowired
    private UserService userService;

    @RequestMapping(value = "/queryUser")
    public ResultMsg query(@RequestParam("userId") Long userId){
        try {
            // 业务代码...
            User user = userService.queryId(userId);
            return ResultMsg.success(user);
        } catch (Exception e){
            return ResultMsg.fail(e.getMessage());
        }
    }
}

当请求http://localhost:8080/queryUser?userId=1地址时，返回结果示例如下：

{
    "code": 200,
    "message": "请求成功",
    "data": {
        "userId": 1,
        "userName": "张三"
    },
    "timestamp": 1716540843798
}

前端根据code值来判断接口请求是否成功。

这种实现方式属于万能的一种方式，唯一的缺点就是重复编程工作很大，每个接口都要根据业务的要求进行不同程度的try..catch操作，如果有几百个接口，代码看起来会比较臃肿。

03、高级封装实现

Spring Boot 框架其实已经帮助开发者封装了很多实用的工具，比如ResponseBodyAdvice，我们可以利用来实现数据格式的统一返回。

简单的说，ResponseBodyAdvice可以对controller层中的拥有@ResponseBody注解属性的方法进行响应拦截，用户可以利用这一特性来封装数据的返回格式，也可以进行加密、签名等操作。

3.1、ResponseBodyAdvice 用法介绍

/**
 * 对controller 层中 ResponseBody 注解方法，进行增强拦截
 */
@ControllerAdvice
public class CustomerResponseAdvice implements ResponseBodyAdvice<Object> {

    /**
     * 是否开启支持功能
     */
    @Override
    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
        return true;
    }

    /**
     * 如果开启，就会对返回结果进行处理
     */
    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {
        return ResultMsg.success(body);
    }
}

3.2、调整接口返回参数

此时，在controller层无需返回ResultMsg对象类型，直接改成对应的业务对象即可，示例如下：

@RestController
public class UserController {

    @Autowired
    private UserService userService;

    @RequestMapping(value = "/queryUser")
    public User query(@RequestParam("userId") Long userId){
        // 业务代码...
        User user = userService.queryId(userId);
        return user;
    }
}

在此请求接口地址，返回结果与上文一致。

3.3、字符串类型返回问题

假如返回的接口数据对象是字符串类型，比如如下示例：

@RestController
public class HelloController {

    @GetMapping(value = "/hello")
    public String hello(){
        return "hello world";
    }
}

先猜猜结果如下？

在浏览器中请求地址http://localhost:8080/hello，结果如下：

抛出异常了！错误原因如下。

java.lang.ClassCastException: com.example.basic.core.result.ResultMsg cannot be cast to java.lang.String

发生这个现象的原因在于：当接口返回的结果是String类型时，会优先使用StringHttpMessageConverter字符串消息转换器来响应数据，其次采用对象转换器。

因此我们需要对CustomerResponseAdvice进行改造，当返回的数据类型为String时，对其单独进行处理，示例如下：

/**
 * 如果开启，就会对返回结果进行处理
 */
@Override
public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {
    // 设置响应类型为json
    response.getHeaders().setContentType(MediaType.APPLICATION_JSON_UTF8);
    if(body != null && (body instanceof ResultMsg)){
        // 如果body返回的是ResultMsg类型的对象，不进行增强处理
        return body;
    }
    if(body != null && (body instanceof String)){
        // 如果body返回的是String类型的对象，单独处理
        return toJson(body);
    }
    return ResultMsg.success(body);
}

private Object toJson(Object body) {
    try {
        return new ObjectMapper().writeValueAsString(ResultMsg.success(body));
    } catch (JsonProcessingException e) {
        throw new RuntimeException("无法转发json格式", e);
    }
}

启动服务后，再次请求地址，结果如下：

从日志上可以清晰的看到，与预期一致！

有个地方需要重点注意一下：默认String类型的数据响应给客户端的格式为text/html，为了统一响应格式，需要手动设置响应类型为json。

3.4、全局异常处理

在上文的介绍中，当遇到异常时第一时间想到的是try...catch。其实大量的try...catch，不仅编程工作量很大，而且可读性也差。

在 Spring Boot 中，其实我们不用一个一个的去写，我们可以利用@ControllerAdvice和@ExceptionHandler注解实现全局异常处理器，拦截controller层抛出的异常，具体应用示例如下：

@ControllerAdvice
public class GlobalExceptionHandler {

    /**
     * 处理全局异常
     * @param e
     * @return
     */
    @ExceptionHandler(value = Exception.class)
    @ResponseBody
    public Object exceptionHandler(Exception e){
        // 业务异常
        if(e instanceof BusinessException){
            BusinessException ex = (BusinessException) e;
            return ResultMsg.fail(e.getCode, ex.getMessage());
        }
        // 运行时异常
        if(e instanceof RuntimeException){
            RuntimeException ex = (RuntimeException) e;
            return ResultMsg.fail(500, ex.getMessage());
        }
        return ResultMsg.fail(999, e.getMessage());
    }
}

下面我们写一个异常接口来验证一下，代码如下：

@GetMapping(value = "/fail")
public String fail(){
    if(1 == 1){
        throw new RuntimeException("测试");
    }
    return "1";
}

启动服务后，在浏览器发起请求，返回结果如下：

04、小结

最后总结一下，在实际的项目开发过程中，统一响应格式通常有两种实现方式。

• 方式一：在接口层直接返回标准格式，同时通过全局异常处理器来捕捉并处理异常；
• 方式二：在接口层返回业务对象，通过实现ResponseBodyAdvice接口统一封装格式

如果不希望 Spring Boot 托管响应内容，要求编程风格统一，可以采用方式一；如果希望尽量简化业务代码的开发量，可以采用方式二。

这两种方式，项目开发中都有所应用，具体采用哪一种，通常以团队开发风格为主。

示例代码地址

https://gitee.com/pzblogs/spring-boot-example-demo