JSR303 数据校验

1.概述

1.1什么是JSR

JSR是Java Specification Requests的缩写,意思是Java 规范提案。是指向JCP(Java Community Process)提出新增一个标准化技术规范的正式请求。任何人都可以提交JSR,以向Java平台增添新的API和服务。JSR已成为Java界的一个重要标准。

1.2JSR-303 定义的是什么标准

JSR-303 是JAVA EE 6 中的一项子规范,叫做Bean Validation,Hibernate Validator 是 Bean Validation 的参考实现 . Hibernate Validator 提供了 JSR 303 规范中所有内置 constraint 的实现,除此之外还有一些附加的 constraint。

Bean Validation 中内置的 constaint

img

在这里插入图片描述

1.3为什么需要 JSR-303

我们在编写业务代码时,常常会对用户输入的数据进行必要的参数校验,如果我们不做校验,系统很可能会产生空指针等异常,这些异常我们应当避免(是因为抛出异常代表发生了一个不可预知的危险操作,代表发生了正常业务逻辑以外的事,如果继续执行下去,可能会发生无法挽回的危险。)。

虽然前端在大部分情况下可以校验数据是否合法,但是这只是防君子不防小人,一些人可能会看控制台知道这个请求是如何组织的,通过一些工具如 postman 向后台发送请求,这样就可以绕过前端的参数校验,所以以防万一,后端同样需要对传入的数据进行校验。

后端最简单的实现就是直接在业务方法中对数据进行处理,但是不同的业务方法可能会出现同样的校验操作,产生冗余的代码。并且传统的校验方式下,我们常常会编写许多 if-else,有的代码甚至会嵌套好几层,大大降低了代码的可读性。

JSR-303 就是一种很优雅的处理参数校验的规范,使用 JSR-303 规范,通过我们在对象或者参数字段上添加注解的方式,进行参数校验,这样即简化了代码,又提高了代码的可读性。

2.快速上手

上面我们介绍了 JSR-303 强大,现在让我们亲身感受 JSR-303 带给我们的便利。

2.1引入依赖

在使用 JSR-303 之前,我们在我们的 SpringBoot 项目中引入依赖。

导入 JSR-303 依赖,springboot 对于 jsr 集成了自己的 starter,我们直接导入即可。

<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
<version>${spring.version}</version>
</dependency>

2.2 使用

现在我们有一个 BrandDTO

@Data
public class BrandDTO implements Serializable {
private static final long serialVersionUID = 1L;

/**
* 品牌id
*/
@NotNull(message = "修改必须指定品牌id") //分组校验 给校验注解标准什么情况需要进行校验 不指定分组
@TableId
private Long brandId;
/**
* 品牌名
*/
@NotBlank(message = "品牌名不能为空")
private String name;
/**
* 品牌logo地址
*/
@URL(message = "logo必须是一个合法的url地址")
private String logo;
/**
* 介绍
*/
private String descript;
/**
* 显示状态[0-不显示;1-显示]
*/
@NotNull
private Integer showStatus;
}

我们只需要在在这个 DTO 的参数字段上加上 Spring 官方对 JSR 303 的实现注解即可。

接着我们编写一个 BrandController 用于测试

/**
* 保存
*
* @@Validated 用于指定校验分组
*/
@RequestMapping("/save")
public R save(@Validated @RequestBody BrandEntity brand ){
brandService.save(brand);

return R.ok();
}

注意:传参的DTO前必须要带有 @Validated 或者 @Valid 注解才能使得 DTO 内部的参数校验生效

当我们在传参时出现了参数不满足参数校验的情况,系统就会抛出异常。

2.3 校验结果捕获

在业务中,我们常常会将校验有误的结果的信息返回给前端。

我们可以通过在 Controller 传参中添加 BindingResult 来获取这些校验的结果。

@RequestMapping("/save")
public R save(@Validated @RequestBody BrandEntity brand, BindingResult result){ //给校验的Bean后紧跟一个BindingResult,就可以获取到校验的结果
List<FieldError> errors = result.getFieldErrors(); //获取与所有字段关联的所有错误。
HashMap<String, String> map = new HashMap<>();

errors.forEach((error)->{
String field = error.getField(); //获取校验错误的字段
String defaultMessage = error.getDefaultMessage();//获取对应的信息
map.put(field,defaultMessage);//将这些信息填充到map中方便返回
});
brandService.save(brand);

return R.ok().put("data",map);
}

大型的项目中,这种获取校验结果的方式会产生大量冗余代码,我们一般会编写一个全局异常捕获处理类来解决这个问题。

@Slf4j
@RestControllerAdvice
public class GulimallExceptionControllerAdvice {

@ExceptionHandler(value = MethodArgumentNotValidException.class)
public R handleValidException(MethodArgumentNotValidException e){

BindingResult bindingResult = e.getBindingResult(); //获取校验结果

HashMap<String, String> errorMap = new HashMap<>();
bindingResult.getFieldErrors().forEach((item)-> errorMap.put(item.getField(),item.getDefaultMessage()));
log.info("数据校验出现问题{}", errorMap);
return R.error(BizCodeEnum.VALID_EXCEPTION.getCode(),BizCodeEnum.VALID_EXCEPTION.getMessage()).put("data",errorMap);
}

@ExceptionHandler(value = Throwable.class)
public R HandleException(Throwable throwable){
throwable.printStackTrace();
return R.error(BizCodeEnum.UNKNOWN_EXCEPTION.getCode(),BizCodeEnum.UNKNOWN_EXCEPTION.getMessage());
}
}

通过捕获我们知道,由 spring-boot-starter-validation 参数校验抛出的异常类型为 MethodArgumentNotValidException,所以针对参数校验的异常捕获处理,我们可以通过捕获它并获取详细信息来完成。

通过如上的方式,我们就可以在我们的代码中用少量的代码优雅地完成参数校验了。

3.分组校验

3.1 需求

有时对于不同业务,对参数的检验也会不同,如果我想保存一个新的对象,要往数据库插入一个新的一行数据,有些字段是必不可少的,所以我会为它们加上 @NotNull 注解。但是如果我只是想修改那行数据,并且传参时只携带修改的字段,并且为了复用我使用和新增同样的 DTO,这时就会出现一个问题,就会产生冲突。所以 spring-boot-starter-validation 考虑到了这种情况,并且提出了分组校验的新功能。

面对不同的业务场景,我们可以将其分为不同的分组,对于不同的分组我们有不同的校验规则,这样就可以灵活地对参数进行校验。

3.2 使用

@NotNull 为例,它有一个 group 属性,通过这个属性我们可以来指定它属于那个分组,可以用接口作为参数来指定。

这里我们编写了两个接口来作为分组参数。

public interface AddGroup {
}
public interface UpdateGroup {
}

根据业务场景修改后的可以适用于分组校验的 BrandDTO

@Data
public class BrandDTO implements Serializable {
private static final long serialVersionUID = 1L;

/**
* 品牌id
*/
@NotNull(message = "修改必须指定品牌id",groups = {UpdateGroup.class}) //分组校验 给校验注解标准什么情况需要进行校验 不指定分组的校验注解会不生效(指定校验分组后)
@Null(message = "新增不能指定id", groups = {AddGroup.class})
@TableId
private Long brandId;
/**
* 品牌名
*/
@NotBlank(message = "品牌名不能为空",groups = {AddGroup.class, UpdateGroup.class})
private String name;
/**
* 品牌logo地址
*/
@NotBlank(groups = {AddGroup.class})
@URL(message = "logo必须是一个合法的url地址",groups = {AddGroup.class, UpdateGroup.class})
private String logo;
/**
* 介绍
*/
private String descript;
/**
* 显示状态[0-不显示;1-显示]
*/
@NotNull(groups = {AddGroup.class})
private Integer showStatus;
}

据不同业务场景分为了新增组和修改组,通过我们在 Controller 中指定 @Validation 中的 group 属性来执行指定分组的参数校验规则。

@RequestMapping("/save")
public R save(@Validated(value = {AddGroup.class}) @RequestBody BrandEntity brand){
brandService.save(brand);

return R.ok();
}

3.3 注意

注意:

这里待检验的 DTO 前只能使用 @Validation 注解,因为只有这个注解才支持分组校验

指定了分组校验后,DTO 中没有指定分组的校验注解是不生效的。

4.自定义校验注解

4.1需求

有时候 spring-boot-starter-validation 内置的校验注解不能完全满足所有业务场景。

比如这里有个字段,我们希望它的值为0 或者 1,如果用内置的注解就只有 @Pattern 的正则表达式可以做到,但是正则只能用于字符串,而不能用于Integer类型。所以我们需要编写一个自己校验注解。

private Integer showStatus;

4.2 步骤

  1. 编写一个自定义的校验注解
@ListValue(vals={0,1})
private Integer showStatus;
@Documented
@Constraint(validatedBy = { }) //这里指定校验器
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
@Retention(RUNTIME)
public @interface ListValue {
//jsr303 规范中校验注解必须拥有三个属性 message groups payload
String message() default "{top.devildyw.common.valid.ListValue.message}"; //出错时的响应信息 默认值会从配置文件中获取 我们可以在resource目录下创建配置文件填入属性值

Class<?>[] groups() default { }; //所属分组

Class<? extends Payload>[] payload() default { }; //负载

int[] vals() default { }; //自定义属性 校验值
}

在 resouce 目录下创建配置文件 ValidationMessages.properties 填入

top.devildyw.common.valid.ListValue.message = 必须提交指定的值
  1. 编写一个自定义的校验器

    public class ListValueConstraintValidator implements ConstraintValidator<ListValue,Integer> { //第一个泛型指定注解 第二个泛型指定校验什么类型的数据

    private Set<Integer> set = new HashSet<>();

    /**
    * 初始化方法
    * @param constraintAnnotation annotation instance for a given constraint declaration
    */
    @Override
    public void initialize(ListValue constraintAnnotation) {
    int[] vals = constraintAnnotation.vals(); //返回注解中指定范围的值
    for (int val : vals) {
    set.add(val);
    }
    }

    /**
    * 判断是否校验成功
    * @param value 传入的需要校验的值
    * @param context context in which the constraint is evaluated
    *
    * @return
    */
    @Override
    public boolean isValid(Integer value, ConstraintValidatorContext context) {
    return set.contains(value);
    }
    }
  2. 关联自定义的校验器和校验注解

    @Documented
    @Constraint(validatedBy = {ListValueConstraintValidator.class}) //这里指定校验器
    @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
    @Retention(RUNTIME)
    public @interface ListValue {
    ......
    }

4.3 注意

同一个校验注解可以关联多个校验器,如我们现在要校验的字段为 showStatus,他是一个 Integer 字段,但是如果有一天我们将其更改为 Double,那么现有的校验器因为只能校验 Integer 而失效,此时我们就可以新编写一个校验器(可以适用 Double),最后将其添加到 注解的 @Constraint 中(是一个数组 可以添加多个)

5.JSR-303 内置注解

常用的注解如下:

空检查 
@Null 验证对象是否为null
@NotNull 验证对象是否不为null, 无法查检长度为0的字符串
@NotBlank 检查约束字符串是不是Null还有被Trim的长度是否大于0,只对字符串,且会去掉前后空格.
@NotEmpty 检查约束元素是否为NULL或者是EMPTY.

Booelan检查
@AssertTrue 验证 Boolean 对象是否为 true
@AssertFalse 验证 Boolean 对象是否为 false

长度检查
@Size(min=, max=) 验证对象(Array,Collection,Map,String)长度是否在给定的范围之内
@Length(min=, max=) Validates that the annotated string is between min and max included.

日期检查
@Past 验证 Date 和 Calendar 对象是否在当前时间之前,验证成立的话被注释的元素一定是一个过去的日期
@Future 验证 Date 和 Calendar 对象是否在当前时间之后 ,验证成立的话被注释的元素一定是一个将来的日期
@Pattern 验证 String 对象是否符合正则表达式的规则,被注释的元素符合制定的正则表达式,regexp:正则表达式 flags: 指定 Pattern.Flag 的数组,表示正则表达式的相关选项。

数值检查
建议使用在Stirng,Integer类型,不建议使用在int类型上,因为表单值为“”时无法转换为int,但可以转换为Stirng为”“,Integer为null
@Min 验证 Number 和 String 对象是否大等于指定的值
@Max 验证 Number 和 String 对象是否小等于指定的值
@DecimalMax 被标注的值必须不大于约束中指定的最大值. 这个约束的参数是一个通过BigDecimal定义的最大值的字符串表示.小数存在精度
@DecimalMin 被标注的值必须不小于约束中指定的最小值. 这个约束的参数是一个通过BigDecimal定义的最小值的字符串表示.小数存在精度
@Digits 验证 Number 和 String 的构成是否合法
@Digits(integer=,fraction=) 验证字符串是否是符合指定格式的数字,interger指定整数精度,fraction指定小数精度。
@Range(min=, max=) 被指定的元素必须在合适的范围内
@Range(min=10000,max=50000,message=”range.bean.wage”)
@Valid 递归的对关联对象进行校验, 如果关联对象是个集合或者数组,那么对其中的元素进行递归校验,如果是一个map,则对其中的值部分进行校验.(是否进行递归验证)
@CreditCardNumber信用卡验证
@Email 验证是否是邮件地址,如果为null,不进行验证,算通过验证。
@ScriptAssert(lang= ,script=, alias=)
@URL(protocol=,host=, port=,regexp=, flags=)