SpringBoot：如何优雅地进行响应数据封装、异常处理？

Myth丶恋晨 2023-10-01 23:16 29阅读 0赞

### 背景 ###

越来越多的项目开始基于前后端分离的模式进行开发，这对后端接口的报文格式便有了一定的要求。通常，我们会采用JSON格式作为前后端交换数据格式，从而减少沟通成本等。

这篇文章，就带大家了解一下基于SpringBoot框架来封装返回报文以及统一异常处理。

### 报文基本格式 ###

一般报文格式通常会包含状态码、状态描述（或错误提示信息）、业务数据等信息。在此基础上，不同的架构师、项目搭建者可能会有所调整。但从整体上来说，基本上都是大同小异。

在SpringBoot项目中，通常接口返回的报文中至少包含三个属性：

*  code：请求接口的返回码，成功或者异常等返回编码，例如定义请求成功。
 *  message：请求接口的描述，也就是对返回编码的描述。
 *  data：请求接口成功，返回的业务数据。

示例报文如下：

{
      "code":200,
      "message":"SUCCESS",
      "data":{
        "info":"测试成功"
      }
    }
    复制代码

在上述报文格式中，不同的设计者是会有一些分歧的，特别是code值的定义。如果完全基于RESTful API设计的话，code字段可能就不需要存在了，而是通过HTTP协议中提供的GET、POST、PUT、DELETE操作等来完成资源的访问。

但在实践中，不论是出于目前国内大多数程序员的习惯，还是受限于HTTP协议提供的操作方法的局限性，很少完全遵照RESTful API方式进行设计。通常都是通过自定义Code值的形式来赋予它业务意义或业务错误编码。

虽然可以不用完全遵守RESTful API风格来定义Code，在Code值的自定义中，也存在两种形式：遵循HTTP状态码和自主定义。

像上面的示例，用200表示返回成功，这就是遵循HTTP响应状态码的形式来返回，比如还有其他的400、401、404、500等。当然，还有完全自主定义的，比如用0表示成功，1表示失败，然后再跟进通用编码、业务分类编码等进行定义。

在此，笔者暂不评论每种形式的好坏，只列举了常规的几种形式，大家了解对应的情况，做到心中有数，有所选择即可。

### 响应参数封装实践 ###

创建一个SpringBoot项目，并引入Lombok依赖（精简代码），对应的核心依赖如下：

<dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-web</artifactId>
            </dependency>
            <dependency>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
            </dependency>
        </dependencies>
    复制代码

创建枚举类，用于定义返回的错误码：

@Getter
    @AllArgsConstructor
    public enum ResponseCodeEnums {
    
      SUCCESS(200, "success"),
      FAIL(500, "failed"),
    
      HTTP_STATUS_200(200, "ok"),
      HTTP_STATUS_400(400, "request error"),
      HTTP_STATUS_401(401, "no authentication"),
      HTTP_STATUS_403(403, "no authorities"),
      HTTP_STATUS_500(500, "server error");
    
      private final int code;
    
      private final String message;
    }
    复制代码

这里只定义了一些通用的、基于的HTTP响应状态码，业务相关的编码可根据业务需求进行定义。

定义统一返回结果实体类：

@Data
    public class ResponseInfo<T> {
    
      /**
       * 状态码
       */
      protected int code;
    
      /**
       * 响应信息
       */
      protected String message;
    
      /**
       * 返回数据
       */
      private T data;
    
      public static <T> ResponseInfo<T> success() {
        return new ResponseInfo<>();
      }
    
      public static <T> ResponseInfo<T> success(T data) {
        return new ResponseInfo<>(data);
      }
    
      public static <T> ResponseInfo<T> fail(String message) {
        return new ResponseInfo<>(ResponseCodeEnums.FAIL.getCode(), message);
      }
    
      public ResponseInfo() {
        this.code = ResponseCodeEnums.SUCCESS.getCode();
        this.message = ResponseCodeEnums.SUCCESS.getMessage();
      }
    
      public ResponseInfo(ResponseCodeEnums statusEnums) {
        this.code = statusEnums.getCode();
        this.message = statusEnums.getMessage();
      }
    
      /**
       * 若没有数据返回，可以人为指定状态码和提示信息
       */
      public ResponseInfo(int code, String msg) {
        this.code = code;
        this.message = msg;
      }
    
      /**
       * 有数据返回时，状态码为200，默认提示信息为“操作成功！”
       */
      public ResponseInfo(T data) {
        this.data = data;
        this.code = ResponseCodeEnums.SUCCESS.getCode();
        this.message = ResponseCodeEnums.SUCCESS.getMessage();
      }
    
      /**
       * 有数据返回，状态码为 200，人为指定提示信息
       */
      public ResponseInfo(T data, String msg) {
        this.data = data;
        this.code = ResponseCodeEnums.SUCCESS.getCode();
        this.message = msg;
      }
    }
    复制代码

在ResponseInfo中运用了泛型和公共方法、构造方法的封装，方便在业务中使用。示例中只提供了部分方法的封装，根据自身业务场景和需要可进一步封装。

统一报文封装在接口中的使用：

@Slf4j
    @RestController
    public class TestController {
    
      @RequestMapping("/calc")
      public ResponseInfo<String> calc(Integer id) {
        try {
          // 模拟异常业务代码
          int num = 1 / id;
          log.info("计算结果num={}", num);
          return ResponseInfo.success();
        } catch (Exception e) {
          return ResponseInfo.fail("系统异常，请联系管理员！");
        }
      }
    }
    复制代码

在浏览器中访问：[http://localhost:8080/calc][http_localhost_8080_calc]，返回结果如下：

{
        "code": 500,
        "message": "系统异常，请联系管理员！",
        "data": null
    }
    复制代码

这是因为没传递id参数，导致业务抛异常，走异常报文返回。

在浏览器中访问：[http://localhost:8080/calc?id=1][http_localhost_8080_calc_id_1]，返回结果如下：

{
        "code": 200,
        "message": "success",
        "data": null
    }
    复制代码

正常返回结果。

### 统一异常处理 ###

在上述实例中，我们通过try...catch的形式捕获异常，并进行处理。在SpringBoot中，我们可以通过RestControllerAdvice注解来定义全局异常处理，这样就无需每处都try...catch了。

@Slf4j
    @RestControllerAdvice
    public class ExceptionHandlerAdvice {
    
      /**
       * 参数格式异常处理
       */
      @ExceptionHandler({IllegalArgumentException.class})
      @ResponseStatus(HttpStatus.BAD_REQUEST)
      public ResponseInfo<String> badRequestException(IllegalArgumentException ex) {
        log.error("参数格式不合法：{}", ex.getMessage());
        return new ResponseInfo<>(HttpStatus.BAD_REQUEST.value() + "", "参数格式不符！");
      }
    
      /**
       * 权限不足异常处理
       */
      @ExceptionHandler({AccessDeniedException.class})
      @ResponseStatus(HttpStatus.FORBIDDEN)
      public ResponseInfo<String> badRequestException(AccessDeniedException ex) {
        return new ResponseInfo<>(HttpStatus.FORBIDDEN.value() + "", ex.getMessage());
      }
    
      /**
       * 参数缺失异常处理
       */
      @ExceptionHandler({MissingServletRequestParameterException.class})
      @ResponseStatus(HttpStatus.BAD_REQUEST)
      public ResponseInfo<String> badRequestException(Exception ex) {
        return new ResponseInfo<>(HttpStatus.BAD_REQUEST.value() + "", "缺少必填参数！");
      }
    
      /**
       * 空指针异常
       */
      @ExceptionHandler(NullPointerException.class)
      @ResponseStatus(value = HttpStatus.INTERNAL_SERVER_ERROR)
      public ResponseInfo<String> handleTypeMismatchException(NullPointerException ex) {
        log.error("空指针异常，{}", ex.getMessage());
        return ResponseInfo.fail("空指针异常");
      }
    
      @ExceptionHandler(Exception.class)
      @ResponseStatus(value = HttpStatus.INTERNAL_SERVER_ERROR)
      public ResponseInfo<String> handleUnexpectedServer(Exception ex) {
        log.error("系统异常：", ex);
        return ResponseInfo.fail("系统发生异常，请联系管理员");
      }
    
      /**
       * 系统异常处理
       */
      @ExceptionHandler(Throwable.class)
      @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
      public ResponseInfo<String> exception(Throwable throwable) {
        log.error("系统异常", throwable);
        return new ResponseInfo<>(HttpStatus.INTERNAL_SERVER_ERROR.value() + "系统异常，请联系管理员！");
      }
    }
    复制代码

在上述方法中，对一些常见的异常进行了统一处理。通常情况下，根据业务需要还会定义业务异常，并对业务异常进行处理，大家可以根据自己项目中异常的使用情况进行拓展。

关于@RestControllerAdvice的几点说明：

*  @RestControllerAdvice注解包含了@Component注解，会把被注解的类作为组件交给Spring来管理。
 *  @RestControllerAdvice注解包含了@ResponseBody注解，异常处理完之后给调用方输出一个JSON格式的封装数据。
 *  @RestControllerAdvice注解有一个basePackages属性，该属性用来拦截哪个包中的异常信息，一般不指定，拦截项目工程中的所有异常。
 *  在方法上通过@ExceptionHandler注解来指定具体的异常，在方法中处理该异常信息，最后将结果通过统一的JSON结构体返回给调用者。

重新定义一个接口：

@RequestMapping("/calc1")
      public ResponseInfo<String> calc1(Integer id) {
        // 模拟异常业务代码
        int num = 1 / id;
        log.info("计算结果num={}", num);
        return ResponseInfo.success();
      }
    复制代码

在请求的时候，不传递id值，即在浏览器中访问：

{
        "code": 500,
        "message": "空指针异常",
        "data": null
    }
    复制代码

可以看到统一异常处理对空指针异常进行了拦截处理，并返回了ExceptionHandlerAdvice中定义的统一报文格式。

### 小结 ###

在使用SpringBoot或其他项目中，统一的报文格式和统一的异常处理都是必须的。本篇文章介绍了基于SpringBoot的实现，如果你的项目中采用了其他的技术栈，则可考虑对应的处理方式。同时，日常中很多类似的功能都可以统一进行处理，避免大量无效的硬编码。

![ef57bb727ef944d2a207dbe4e31c0fc5.jpeg][]

[http_localhost_8080_calc]: https://link.juejin.cn?target=http%3A%2F%2Flocalhost%3A8080%2Fcalc
[http_localhost_8080_calc_id_1]: https://link.juejin.cn?target=http%3A%2F%2Flocalhost%3A8080%2Fcalc%3Fid%3D1
[ef57bb727ef944d2a207dbe4e31c0fc5.jpeg]: https://img-blog.csdnimg.cn/ef57bb727ef944d2a207dbe4e31c0fc5.jpeg