Spring Boot - 统一数据下发接口格式

[TOC]

前言

当前主流的 Web 应用开发通常采用前后端分离模式，前端和后端各自独立开发，然后通过数据接口沟通前后端，完成项目。

因此，定义一个统一的数据下发格式，有利于提高项目开发效率，减少各端开发沟通成本。

本篇博文主要介绍下在 Spring Boot 中配置统一数据下发格式的搭建步骤。

统一数据格式

数据的类型多种多样，但是可以简单划分为以下三种类型：

• 简单数据类型：比如byte、int、double等基本数据类型。
  注：在 Java 中，String属于Object类型，但是在数据层面上，我们通常将其看作是简单数据类型。

• 对象数据类型：常见的比如说自定义 Java Bean，POJO 等数据。

• 复杂/集合数据类型：比如List、Map等集合类型。

后端下发的数据肯定会包含上述列举的三种类型数据，通常这些数据都作为响应体主要内容，用字段data进行表示，同时我们会附加code和msg字段来描述请求结果信息，如下表所示：

字段	描述
code	状态码，标志请求是否成功
msg	描述请求状态
data	返回结果

到此，统一数据下发的格式就确定了，如下代码所示：

@Getter
@AllArgsConstructor
@ToString
public class ResponseBean {
    private int code;
    private String msg;
    private T data;
}

此时，数据下发操作如下所示：

@RestController
@RequestMapping("/common")
public class CommonController {

    @GetMapping("/")
    public ResponseBean index() {
        return new ResponseBean<>(200, "操作成功", "Hello World");
    }
}

进阶配置

在上文的统一数据ResponseBean中，还可以对其再进行封装，使代码更健壮：

• 抽象code和msg：code和msg用于描述请求结果信息，直接放置再ResponseBean中，程序员可以随便设置这两个字段，请求结果一般就是成功、失败等常见的几种结果，可以将其再进行封装，提供常见的请求结果信息，缩小权限：

  @Getter
  @ToString
  public class ResponseBean {
      private int code;
      private String msg;
      private T data;
  
      public ResponseBean(ResultCode result, T data) {
          this.code = result.code;
          this.msg = result.msg;
          this.data = data;
      }
  
      public static enum ResultCode {
          SUCCESS(200, "操作成功"),
          FAILURE(400, "操作失败");
  
          ResultCode(int code, String msg) {
              this.code = code;
              this.msg = msg;
          }
  
          private int code;
          private String msg;
      }
  }
  

  这里使用enum来封装code和msg，并提供两个默认操作SUCCESS和FAILURE。此时调用方法如下：

  @GetMapping("/")
  public ResponseBean index() {
      return new ResponseBean<>(ResponseBean.ResultCode.SUCCESS, "Hello World");
  }
  

• 提供默认操作：前面的调用方法还是不太简洁，这里我们让ResponseBean直接提供相应的默认操作，方便外部调用：

  @Getter
  @ToString
  public class ResponseBean {
      private int code;
      private String msg;
      private T data;
  
      // 成功操作
      public static  ResponseBean success(E data) {
          return new ResponseBean(ResultCode.SUCCESS, data);
      }
  
      // 失败操作
      public static  ResponseBean failure(E data) {
          return new ResponseBean(ResultCode.FAILURE, data);
      }
  
      // 设置为 private
      private ResponseBean(ResultCode result, T data) {
          this.code = result.code;
          this.msg = result.msg;
          this.data = data;
      }
  
      // 设置 private
      private static enum ResultCode {
          SUCCESS(200, "操作成功"),
          FAILURE(400, "操作失败");
  
          ResultCode(int code, String msg) {
              this.code = code;
              this.msg = msg;
          }
  
          private int code;
          private String msg;
      }
  }
  

  我们提供了两个默认操作success和failure，此时调用方式如下：

  @GetMapping("/")
  public ResponseBean index() {
      return ResponseBean.success("Hello World");
  }
  

  到这里，数据下发调用方式就相对较简洁了，但是结合 Spring Boot 还能继续进行优化，参考下文。

数据下发拦截修改

Spring 框架提供了一个接口：ResponseBodyAdvice，当控制器方法被@ResponseBody注解或返回一个ResponseEntity时，该接口允许我们在HttpMessageConverter写入响应体前，拦截响应体并进行自定义修改。

因此，要拦截Controller响应数据，只需实现一个自定义ResponseBodyAdvice，并将其注册到RequestMappingHandlerAdapter和ExceptionHandlerExceptionResolver，或者直接使用@ControllerAdvice注解进行激活。如下所示：

@RestControllerAdvice
public class FormatResponseBodyAdvice implements ResponseBodyAdvice