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

码农世界 2024-05-22 后端 55 次浏览 0个评论

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）请求体

@Data
public 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
@ControllerAdvice
public 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）请求体

@Data
public 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）请求体

@Data
public 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
@ControllerAdvice
public 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）请求体

@Data
public 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)
@Documented
public @interface Valid {
}

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

@Target({ElementType.TYPE, ElementType.METHOD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @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
      
      – 求知若饥，虚心若愚。