全局异常处理及参数校验-SpringBoot 2.7.2 实战基础 （建议收藏） ...

优雅哥 SpringBoot 2.7 实战基础 - 08 - 全局异常处理及参数校验

前后端分离开发非常普遍，后端处理业务，为前端提供接口。服务中总会出现很多运行时异常和业务异常，本文主要讲解在 SpringBoot 实战中如何进行异常统一处理和请求参数的校验。
1 异常统一处理

所有异常处理相关的类，咱们都放到 com.yygnb.demo.common包中。
当后端发生异常时，需要按照一个约定的规则（结构）返回给前端，所以先定义一个发生异常时固定的结构。
1.1 错误响应结构

发生异常时的响应结构约定两个字段：code——错误编码；msg——错误消息。创建类：
com.yygnb.demo.common.domain.ErrorResult：

1. @Data
2. @Builder
3. @NoArgsConstructor
4. @AllArgsConstructor
5. public class ErrorResult implements Serializable {
7.     private static final long serialVersionUID = -8738363760223125457L;
9.     /**
10.      * 错误码
11.      */
12.     private String code;
14.     /**
15.      * 错误消息
16.      */
17.     private String msg;
18.   
19.     public static ErrorResult build(ErrorResult commonErrorResult, String msg) {
20.         return new ErrorResult(commonErrorResult.getCode(), commonErrorResult.getMsg() + " " + msg);
21.     }
22. }

复制代码

1.2 通用错误响应常量

有些异常返回的 ErrorResult 是一样的，如参数校验错误、未查询到对象、系统异常等，可以定义一些错误响应的常量：
com.yygnb.demo.common.exception.DefaultErrorResult：

1. public interface DefaultErrorResult {
3.     ErrorResult SYSTEM_ERROR = new ErrorResult("C00001", "系统异常");
4.     ErrorResult CUSTOM_ERROR = new ErrorResult("C99999", "自定义异常");
5.     ErrorResult PARAM_BIND_ERROR = new ErrorResult("C00003", "参数绑定错误：");
6.     ErrorResult PARAM_VALID_ERROR = new ErrorResult("S00004", "参数校验错误：");
7.     ErrorResult JSON_PARSE_ERROR = new ErrorResult("S00005", "JSON转换异常");
8.     ErrorResult CODE_NOT_FOUND = new ErrorResult("S00006", "根据编码没有查询到对象");
9.     ErrorResult ID_NOT_FOUND = new ErrorResult("S00007", "根据ID没有查询到对象");
10. }

复制代码

1.3 通用异常类定义

定义一个通用的异常类 CommonException，继承自 RuntimeException，当程序中捕获到编译时异常或业务异常时，就抛出这个通用异常，交给全局来处理。（随着业务复杂度的增加，可以细分自定义异常，如 AuthException、UserException、CouponException 等，让这些细分异常都继承自 CommonException。）
com.yygnb.demo.common.exception.CommonException：

1. @EqualsAndHashCode(callSuper = true)
2. @Data
3. public class CommonException extends RuntimeException {
5.     protected ErrorResult errorResult;
7.     public CommonException(String message) {
8.         super(message);
9.     }
11.     public CommonException(String message, Throwable cause) {
12.         super(message, cause);
13.     }
15.     public CommonException(Throwable cause) {
16.         super(cause);
17.     }
19.     protected CommonException(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
20.         super(message, cause, enableSuppression, writableStackTrace);
21.     }
23.     public CommonException(String code, String msg) {
24.         super(msg + "(" + code + ")");
25.         this.errorResult = new ErrorResult(code, msg);
26.     }
28.     public CommonException(ErrorResult errorResult) {
29.         super(errorResult.getMsg() + "(" + errorResult.getCode() + ")");
30.         this.errorResult = errorResult;
31.     }
32. }

复制代码

这个自定义异常类复写了父类的构造函数，同时定义了一个成员变量 ErrorResult，便于在同一异常处理时快速构造返回信息。
1.4 全局异常处理

Spring MVC 中提供了全局异常处理的注解：@ControllerAdvice 和 @RestControllerAdvice。由于前后端分离开发 RESTful 接口，我们这里就使用 @RestControllerAdvice。
com.yygnb.demo.common.exception.CommonExceptionHandler：

1. @Slf4j
2. @RestControllerAdvice
3. public class CommonExceptionHandler {
5.     /**
6.      * 通用业务异常
7.      *
8.      * @param e
9.      * @return
10.      */
11.     @ExceptionHandler(value = CommonException.class)
12.     @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
13.     public ErrorResult handleCommonException(CommonException e) {
14.         log.error("{}, {}", e.getMessage(), e);
15.         if (e.getErrorResult() != null) {
16.             return e.getErrorResult();
17.         }
18.         return new ErrorResult(DefaultErrorResult.CUSTOM_ERROR.getCode(), e.getMessage());
19.     }
21.     /**
22.      * 其他运行时异常
23.      * @param e
24.      * @return
25.      */
26.     @ExceptionHandler(value = Exception.class)
27.     @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
28.     public ErrorResult handleDefaultException(Exception e) {
29.         log.error("{}, {}", e.getMessage(), e);
30.         return DefaultErrorResult.SYSTEM_ERROR;
31.     }
32. }

复制代码

上面捕获了 CommonException 和 Exception，匹配顺序为从上往下。假设 handleDefaultException 在前面，当发生一个异常 CommonException 时，一来就会被 handleDefaultException 捕获，因为无论什么异常，都属于 Exception 的实例，不会执行 handleCommonException。所以越具体的异常处理，越要写在前面。
1.5 测试统一异常处理

在 DemoController 中抛出一个 CommonException：

1. @GetMapping("hello")
2. public String hello(String msg) {
3.     String result = "Hello Spring Boot ! " + msg;
4.     if ("demo".equals(msg)) {
5.         throw new CommonException("发生错误----这是自定义异常");
6.     }
7.     return result;
8. }

复制代码

启动服务，访问：

1. http://localhost:9099/demo/hello?msg=demo

复制代码

结果返回：

1. {
2.   "code": "C99999",
3.   "msg": "发生错误----这是自定义异常"
4. }

复制代码

可以看出全局统一异常处理已经生效了。
2 参数校验

传统参数校验方式是通过多个 if/else 来进行，代码量大，很没有意义。Spring Boot 中有个 starter spring-boot-starter-validation 可以帮助咱们很方便的实现参数校验。
2.1 添加依赖

有些文章中说 spring boot 2.3 还是多少版本以后不用手动加入这个 starter，我试了以后不行，需要手动引入该依赖才行。

1. <dependency>
2.     <groupId>org.springframework.boot</groupId>
3.     <artifactId>spring-boot-starter-validation</artifactId>
4. </dependency>

复制代码

这个 starter 定义 Validator 以及 SmartValidator 接口，提供 @Validated，支持 spring 环境，支持验证组的规范, 提供了一系列的工厂类以及适配器。底层依赖 hibernate-validator 包。
2.2 完善异常处理类

在 1.4 中只捕获了 CommonException 和 Exception，此处要完善参数绑定、校验等异常。补充后 CommonExceptionHandler 如下：

1. @Slf4j
2. @RestControllerAdvice
3. public class CommonExceptionHandler {
5.     @ExceptionHandler(value = BindException.class)
6.     @ResponseStatus(HttpStatus.BAD_REQUEST)
7.     public ErrorResult handleBindException(BindException e) {
8.         log.error("{}", e.getMessage(), e);
9.         List<String> defaultMsg = e.getBindingResult().getAllErrors()
10.                 .stream()
11.                 .map(ObjectError::getDefaultMessage)
12.                 .collect(Collectors.toList());
13.         return ErrorResult.build(DefaultErrorResult.PARAM_BIND_ERROR, defaultMsg.get(0));
14.     }
16.     @ExceptionHandler(value = MethodArgumentNotValidException.class)
17.     @ResponseStatus(HttpStatus.BAD_REQUEST)
18.     public ErrorResult handleMethodArgumentNotValidException(MethodArgumentNotValidException e) {
19.         log.error("{}", e.getMessage(), e);
20.         List<String> defaultMsg = e.getBindingResult().getFieldErrors()
21.                 .stream()
22.                 .map(fieldError -> "【" + fieldError.getField() + "】" + fieldError.getDefaultMessage())
23.                 .collect(Collectors.toList());
24.         return ErrorResult.build(DefaultErrorResult.PARAM_VALID_ERROR, defaultMsg.get(0));
25.     }
27.     @ExceptionHandler(value = MissingServletRequestParameterException.class)
28.     @ResponseStatus(HttpStatus.BAD_REQUEST)
29.     public ErrorResult handleMissingServletRequestParameterException(MissingServletRequestParameterException e) {
30.         log.error("{}", e.getMessage(), e);
31.         log.error("ParameterName: {}", e.getParameterName());
32.         log.error("ParameterType: {}", e.getParameterType());
33.         return ErrorResult.build(DefaultErrorResult.PARAM_VALID_ERROR, e.getMessage());
34.     }
36.     @ExceptionHandler(value = ConstraintViolationException.class)
37.     @ResponseStatus(HttpStatus.BAD_REQUEST)
38.     public ErrorResult handleBindGetException(ConstraintViolationException e) {
39.         log.error("{}", e.getMessage(), e);
40.         List<String> defaultMsg = e.getConstraintViolations()
41.                 .stream()
42.                 .map(ConstraintViolation::getMessage)
43.                 .collect(Collectors.toList());
44.         return ErrorResult.build(DefaultErrorResult.PARAM_VALID_ERROR, defaultMsg.get(0));
45.     }
47.     @ExceptionHandler(HttpMessageNotReadableException.class)
48.     @ResponseStatus(HttpStatus.BAD_REQUEST)
49.     public ErrorResult error(HttpMessageNotReadableException e){
50.         log.error("{}", e.getMessage(), e);
51.         return DefaultErrorResult.JSON_PARSE_ERROR;
52.     }
54.     /**
55.      * 通用业务异常
56.      *
57.      * @param e
58.      * @return
59.      */
60.     @ExceptionHandler(value = CommonException.class)
61.     @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
62.     public ErrorResult handleCommonException(CommonException e) {
63.         log.error("{}, {}", e.getMessage(), e);
64.         if (e.getErrorResult() != null) {
65.             return e.getErrorResult();
66.         }
67.         return new ErrorResult(DefaultErrorResult.CUSTOM_ERROR.getCode(), e.getMessage());
68.     }
70.     /**
71.      * 其他运行时异常
72.      * @param e
73.      * @return
74.      */
75.     @ExceptionHandler(value = Exception.class)
76.     @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
77.     public ErrorResult handleDefaultException(Exception e) {
78.         log.error("{}, {}", e.getMessage(), e);
79.         return DefaultErrorResult.SYSTEM_ERROR;
80.     }
81. }

复制代码

2.3 自定义校验注解

在 javax.validation 中提供了很多用于校验的注解，常见的如：@NotNull、@Min、@Max 等等，但可能这些注解不够，需要自定义注解。例如咱们自定义一个注解 @OneOf，该注解对应字段的值只能从 value 中选择：使用方式为：

1. @OneOf(value = {"MacOS", "Windows", "Linux"})

复制代码

首先定义一个注解
com.yygnb.demo.common.validator.OneOf：
[code]@Target(ElementType.FIELD)@Retention(RetentionPolicy.RUNTIME)@Documented@Constraint(validatedBy = OneOfValidator.class)public @interface OneOf {    String message() default "只能从备选值中选择";    Class[] groups() default {};    Class