Springboot-优雅配置接口响应和统一异常处理

深藏阁楼爱情的钟 2023-10-12 17:18 15阅读 0赞

# 一、前言 #

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

java复制代码@PostMapping("/user/add")
    public ResponseInfo addUser(@RequestBody @Validated User user) {
        userService.add(user);
        return ResponseInfo.success();
    }

我们看看这个代码，有什么问题。 我们返回了统一的封装结果集ResponseInfo 但是后面所有的controller 都这么写不太友好。

1.  返回内容这么不够明确具体
2.  所有controller 这么写增加重复工作量

我们可以这么去优化：

Spirng 提供了 ResponseBodyAdvice 接口，支持在消息转换器执行转换之前，对接口的返回结果进行处理，再结合 @ControllerAdvice 注解即可轻松支持上述功能。

# 二、统一响应配置 #

**准备文件：**

ResponseCodeEnums.java 响应类型枚举类

ResponseInfo.java 响应数据封装类

ResponseResultHandler.java 响应信息增强类

**开始**

ResponseCodeEnums.java

java复制代码@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;
    }

ResponseInfo.java

java复制代码@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;
        }
    }

ResponseResultHandler.java

java复制代码@Slf4j
    @ControllerAdvice
    public class ResponseResultHandler implements ResponseBodyAdvice<Object> {
    
        @Override
        public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
            log.info("supports:{}", returnType.getDeclaringClass().getName());
            /**
             * 排除swagger-ui请求返回数据增强
             */
            return !returnType.getDeclaringClass().getName().contains("springfox");
        }
    
        @Override
        public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {
            // 如果是ResponseInfo数据类型就直接返回
            if (body instanceof ResponseInfo) {
                return body;
            }
            // 如果是空，则返回成功
            else if (body == null) {
                return ResponseInfo.success();
            } 
            // 如果是异常类型就直接返回
            else if (body instanceof Exception) {
                return body;
            } 
            // 如果是String类型则直接返回String类型
            else if (body instanceof String) {
                return body;
            } 
            // 返回封装后的数据
            else {
                return ResponseInfo.success(body);
            }
        }
    }

**测试**

java复制代码@RestController
    public class TestController {
    
        @GetMapping("/test")
        public void hello(){}
    }

**结果**

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

OK，成功地响应了结果，到此配置完成，下面开始配置统一异常处理。

# 三、全局异常配置 #

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

**示例：**

java复制代码@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结构体返回给调用者。

**测试：**

java复制代码@RestController
    public class TestController {
    
        @GetMapping("/test")
        public void hello(){
            int i = 1 / 0;
        }
    }

**结果：**

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

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

# 四、总结 #

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