SpringBoot参数校验@Valid 和 @Validated注解使用详解

JSR-303 是 JAVA EE 6 中的一项子规范，叫做 Bean Validation，官方参考实现是Hibernate Validator。

注意：JSR-303实现与 Hibernate ORM 没有任何关系。 JSR 303 用于对 Java Bean 中的字段的值进行验证。

Spring MVC 3.x 之中也大力支持 JSR-303，可以在控制器中对表单提交的数据方便地验证。

一、@Valid注解使用

1、使用步骤

在Controller中使用 @Valid+BindingResult做参数校验非常好用。一般步骤如下：

（1）引入pom依赖

                    org.springframework.boot            spring-boot-starter-validation                            com.fasterxml.jackson.core            jackson-annotations        

(2）在入参bean类中需要校验的参数上使用校验注解

• 在bean类中的字段加上校验注解，比如：@NotBlank(message = “ID 不能为空”)
• 每个字段可以加上多个校验注解。
• 如果 bean需要交给Spring容器管理，可以加上 @Conmponent注解。

  （3）编写Controller层代码

  • 在入参的请求体前加@Valid注解
  • 请求体后加 BindingResult bindingResult 此类为bean校验捕获到的异常储存。
  • 对于 BindingResult信息，我们业务做统一校验信息处理。

    注意：

    （1）@Valid与 BindingResult要配套使用。

    （2）@Valid使用

    • 可以用在方法、构造函数、方法参数和成员属性（field）上；
    • 可以进行嵌套校验，但是，需要在嵌套的字段上面加上@Valid注解；
    • 不能进行分组校验；

      2、示例1使用

      （1）请求体

      @Datapublic class AaSaveRequest extends BaseRequest {    private static final long serialVersionUID = -7895168538160321157L;    @NotEmpty(message = "用户名不能为空")    private String username;    @NotNull(message = "createTime不能为空")    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")    private Date createTime;    private Boolean delFlag;    }

      （2）controller请求方法

          @PostMapping("/save")    public WebResult save(@RequestBody @Valid AaSaveRequest saveRequest, BindingResult bindingResult) {        if (bindingResult.hasErrors()) {            //如果有校验错误，返回第一个校验信息            String defaultMessage = bindingResult.getFieldErrors().get(0).getDefaultMessage();            //将错误信息返回或者抛异常全局处理。            WebResult webResult = new WebResult();            webResult.setSuccess(false);            webResult.setMessage(defaultMessage);            return webResult;        }        BaseOperateResult operateResult = aaService.save(saveRequest);        if (!operateResult.isSuccess()) {            WebResult.error().message(operateResult.getErrorCode().getMessage());        }        return WebResult.ok();    }

      bindingResult.hasErrors() 判断是否校验通过，未通过bindingResult.getFieldError().getDefaultMessage()获取在TestEntity的属性设置的自定义message，如果没有设置，则返回默认值"javax.validation.constraints.XXX.message"。

      （3）测试访问

      3、示例2使用

      我们将实示例1中 controller请求方法对于 校验错误采用全局异常捕获的方式处理。

      （1）自定义异常类

      自定义异常，或者捕获 MethodArgumentNotValidException异常。

      /** * 参数校验异常类 */public class ParameterCheckException extends RuntimeException {    private static final long serialVersionUID = -4163815498400849756L;    public ParameterCheckException(String message) {        super(message);    }}

      （2）全局异常处理

      /** * 全局异常处理类 */@Slf4j@ResponseBody@ControllerAdvicepublic class GlobalExceptionHandler {        @ExceptionHandler(value = ParameterCheckException.class)    private WebResult handlerParameterCheckException(ParameterCheckException e) {        //log.error("ParameterCheckException 异常 -> error = {}", e);        WebResult webResult = new WebResult();        webResult.setSuccess(false);        webResult.setCode(WebHttpCode.SERVICE_ERROR);        webResult.setMessage(e.getMessage());        return webResult;    }}

      (3）controller请求方法改造

          @PostMapping("/save")    public WebResult save(@RequestBody @Valid AaSaveRequest saveRequest, BindingResult bindingResult) {        if (bindingResult.hasErrors()) {            //如果有校验错误，返回第一个校验信息            String defaultMessage = bindingResult.getFieldErrors().get(0).getDefaultMessage();            //将错误信息返回或者抛异常全局处理。            throw new ParameterCheckException(defaultMessage);        }        BaseOperateResult operateResult = aaService.save(saveRequest);        if (!operateResult.isSuccess()) {            WebResult.error().message(operateResult.getErrorCode().getMessage());        }        return WebResult.ok();    }

      测试访问校验ok

      4、嵌套使用

      嵌套使用，比如：A类中引用B类，且A、B二类都有内部校验，为了使B类也生效，在A类中引用B类时，在B类变量上加@Valid注解，如果B类不能为空时还需要再加@NotNull。

      注意：嵌套验证时必须使用 @Valid注解。

      （1）请求体

      @Datapublic class AaSave2Request extends BaseRequest {    private static final long serialVersionUID = -7895168538160321157L;    @NotEmpty(message = "用户名不能为空")    private String username;    @NotNull(message = "createTime不能为空")    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")    private Date createTime;    private Boolean delFlag;    /**     * 嵌套验证时必须使用 @Valid注解     */    @Valid    @NotNull(message = "文件不能为空")    private AaSaveFileRequest aaSaveFileRequest;    }

      （2）controller请求方法

          @PostMapping("/save2")    public WebResult save2(@RequestBody @Valid AaSave2Request save2Request, BindingResult bindingResult) {        if (bindingResult.hasErrors()) {            //如果有校验错误，返回第一个校验信息            String defaultMessage = bindingResult.getFieldErrors().get(0).getDefaultMessage();            //将错误信息返回或者抛异常全局处理。            throw new ParameterCheckException(defaultMessage);        }        BaseOperateResult operateResult = aaService.save2(save2Request);        if (!operateResult.isSuccess()) {            WebResult.error().message(operateResult.getErrorCode().getMessage());        }        return WebResult.ok();    }

      （3）测试访问

      二、@Validated注解使用

      1、示例1使用

      （1）请求体

      @Datapublic class AaUpdateRequest extends BaseRequest {    private static final long serialVersionUID = -8386003857309634939L;    @NotNull(message = "id不能为空")    private Long id;    @NotEmpty(message = "username不能为空")    private String username;    @NotNull(message = "createTime不能为空")    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")    private Date createTime;    private Boolean delFlag;}

      （2）controller请求方法

          @PostMapping("/update")    public WebResult update(@RequestBody @Validated AaUpdateRequest updateRequest, BindingResult bindingResult) {        if (bindingResult.hasErrors()) {            //如果有校验错误，返回第一个校验信息            String defaultMessage = bindingResult.getFieldErrors().get(0).getDefaultMessage();            throw new ParameterCheckException(defaultMessage);        }        BaseOperateResult operateResult = aaService.update(updateRequest);        if (!operateResult.isSuccess()) {            WebResult.error().message(operateResult.getErrorCode().getMessage());        }        return WebResult.ok();    }

      3）测试访问

      2、示例2使用

      我们将实示例1中 controller请求方法对于 校验错误采用全局异常捕获的方式处理。

      （1）全局异常处理，捕获 MethodArgumentNotValidException异常

      /** * 全局异常处理类 */@Slf4j@ResponseBody@ControllerAdvicepublic class GlobalExceptionHandler {        /**     * 处理 @Valid和 @Validated注解参数校验失败异常     */    @ExceptionHandler(MethodArgumentNotValidException.class)    public WebResult exceptionHandler(MethodArgumentNotValidException exception) {        WebResult webResult = new WebResult();        webResult.setSuccess(false);        webResult.setCode(WebHttpCode.SERVICE_ERROR);        BindingResult bindingResult = exception.getBindingResult();        if (bindingResult.hasErrors()) {            //如果有校验错误，返回第一个校验信息            String defaultMessage = bindingResult.getFieldErrors().get(0).getDefaultMessage();            webResult.setMessage(defaultMessage);        }        return webResult;    }}

      （2）controller请求方法改造

      这里单独使用 @Validated注解。

          @PostMapping("/update2")    public WebResult update2(@RequestBody @Validated AaUpdateRequest updateRequest) {        BaseOperateResult operateResult = aaService.update(updateRequest);        if (!operateResult.isSuccess()) {            WebResult.error().message(operateResult.getErrorCode().getMessage());        }        return WebResult.ok();    }

      测试访问校验ok

      3、嵌套使用

      @Validated无法单独提供嵌套验证功能。不能用在成员属性上，能配合嵌套验证注解@Valid进行嵌套验证。

      （1）请求体

      @Datapublic class AaUpdate3Request extends BaseRequest {    private static final long serialVersionUID = 2976273808489796719L;    @NotNull(message = "id不能为空")    private Long id;    @NotEmpty(message = "username不能为空")    private String username;    @NotNull(message = "createTime不能为空")    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")    private Date createTime;    private Boolean delFlag;        /**     * 嵌套验证时必须使用 @Valid注解     */    @Valid    @NotNull(message = "文件不能为空")    private List fileRequestList;}

      （2）controller请求方法

          @PostMapping("/update3")    public WebResult update3(@RequestBody @Validated AaUpdate3Request update3Request) {        BaseOperateResult operateResult = aaService.update3(update3Request);        if (!operateResult.isSuccess()) {            WebResult.error().message(operateResult.getErrorCode().getMessage());        }        return WebResult.ok();    }

      （3）测试访问

      如果想了解 @Validated注解分组校验请查看参考文章。

      s三、@Valid 和 @Validated 区别

      先看下两者的源码：

      @Valid 包位置：javax.validation

      @Target({ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})@Retention(RetentionPolicy.RUNTIME)@Documentedpublic @interface Valid {}

      @Validated 包位置 org.springframework.validation.annotation，是 Spring 做得一个自定义注解，增强了分组功能（对 @Valid的封装）；只在 Spring Validator 校验机制使用。

      @Target({ElementType.TYPE, ElementType.METHOD, ElementType.PARAMETER})@Retention(RetentionPolicy.RUNTIME)@Documentedpublic @interface Validated {    Class[] value() default {};}

      相同点：

      • @Valid 和 @Validated 两者都可以对数据进行校验，在校验字段上加上规则注解（@NotNull, @NotEmpty等）都可以对 @Valid 和 @Validated 生效。
      • @Valid 和 @Validated 两者都可以与 BindingResult bindingResult配对出现，并且形参顺序是固定的（一前一后），controller对 BindingResult处理返回校验提示。
      • @Valid 和 @Validated 两者也可以单独使用，单独使用当校验不通过时会抛出 BindException异常。这时需要再写一个全局校验异常捕获处理类，然后返回校验提示。

        不同点：

        • @Valid可以用在方法、构造函数、方法参数和成员属性（field）上；
        • @Valid可以进行嵌套校验，但是，需要在嵌套的字段上面加上@Valid注解；
        • @Valid不支持分组。
        • @Validated可以用在方法、构造函数、方法参数；但是不能用在成员属性（字段）上；
        • @Validated不支持嵌套校验，因为不能用在成员属性（字段）上；
        • @Validated支持分组验证，以在入参验证时，根据不同的分组采用不同的验证机制；

          项目中使用 @Valid和@Validated都可以。如果涉及分组校验时，使用 @Validated注解。

          • @Valid无法单独提供嵌套验证功能。能够用在成员属性上，能配合嵌套验证注解@Valid进行嵌套验证。
          • @Validated无法单独提供嵌套验证功能。不能用在成员属性上，能配合嵌套验证注解@Valid进行嵌套验证。

            参考文章：

            • Java代码瘦身，巧用 @Valid，@Validated 的分组校验和嵌套检验，实现高阶参数校验操作：https://blog.csdn.net/weixin_44259720/article/details/127965610

              – 求知若饥，虚心若愚。