Java 后端数据校验
一、概述
当我们想提供可靠的 API 接口,对参数的校验,以保证最终数据入库的正确性,是 必不可少 的活。比如下图就是 我们一个项目里 新增一个菜单校验 参数的函数,写了一大堆的 if else 进行校验,非常的不优雅,比起枯燥的 CRUD 来说,参数校验更是枯燥。
这只是一个创建菜单的校验,只需要判断菜单,菜单 url 以及菜单的父类 id 是否为空,上级菜单是否挂载正确,这样已经消耗掉了 30,40 行代码了,更不要说,管理后台这种参数贼多的接口。估计要写几百行校验代码了。
if(mapper.get("customerId") == null){return RespBean.error("customerId is null!");}if(mapper.get("name") == null){return RespBean.error("name is null!");}if(mapper.get("userName") == null){return RespBean.error("userName is null!");}//查询条件 判断用户名是否重复Map<String,Object> args = new HashMap<>();args.put("userName",mapper.get("userName").toString());args.put("customerId",mapper.get("customerId").toString());Integer findNum = userService.findUserNameIsExist(args);if(!Objects.equals(findNum, 0)){ //查询结果不为0return RespBean.error("用户名重复,请重新输入!");}int ret = userService.addUser(mapper);if(ret >= 0){return RespBean.ok("UserController add user success");}else{return RespBean.error("UserController add User ailed");}
二、注解
在开始入门之前,我们先了解下本文可能会涉及到的注解。javax.validation.constraints 包下,定义了一系列的约束( constraint )注解。共 22 个,如下:
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-HMb3Jaa9-1690357601543)(file:///C:\Users\ADMINI~1\AppData\Local\Temp\ksohtml16688\wps1.jpg)]
大致可以分为以下几类:
2.1 空和非空检查
@NotBlank :只能用于字符串不为 null ,并且字符串 #trim() 以后 length 要大于 0 。
@NotBlank(message = "文本不能为空")
private String text;
@NotEmpty :集合对象的元素不为 0 ,即集合不为空,也可以用于字符串不为 null 。
@NotEmpty(message = "密码不能为空")
private String password;
@NotNull :不能为 null 。
@NotNull(message = "用户名不能为null")
private String userName;
@Null :必须为 null 。
@Null(message = "精度必须为null")
private Double jd;
2.2 数值检查
@DecimalMax(value) :被注释的元素必须是一个数字,其值必须小于等于指定的最大值。
@DecimalMax(value = "50.5",message = "number1必须小于等于50.5")
private Double number1;
@DecimalMin(value) :被注释的元素必须是一个数字,其值必须大于等于指定的最小值。
@DecimalMin(value = "100.6",message = "number2必须大于等于100.6")
private Double number2;
@Max(value) :该字段的值只能小于或等于该值。不支持小数位判断
@Max(value = 100,message = "number7必须小于等于100")
private Long number7;
@Min(value) :该字段的值只能大于或等于该值。 不支持小数位判断
@Min(value = 60,message = "number6必须大于等于60")
private Integer number6;
@Digits(integer, fraction) :被注释的元素必须是一个数字,其值必须在可接受的范围内。
@Digits(integer = 4,fraction = 3,message = "整数位上限4,小数位上限3")
private Double number3;
@Positive :判断正数。
@Positive(message = "number4必须为正数")
private Double number4;
@PositiveOrZero :判断正数或 0 。
@PositiveOrZero(message = "number5必须为正数或0")
private Double number5;
@Negative :判断负数。
@Negative(message = "number8必须为负数")
private Double number8;
@NegativeOrZero :判断负数或 0 。
@NegativeOrZero(message = "number9必须为负数或0")
private Double number9;
2.3 Boolean 值检查
@AssertFalse :被注释的元素必须为 true 。
@AssertTrue(message = "b1只能为true")
private Boolean b1;
@AssertTrue :被注释的元素必须为 false 。
@AssertFalse(message = "b2只能为false")
private Boolean b2;
2.4 长度检查
@Size(max, min) :检查该字段的 size 是否在 min 和 max 之间,可以是字符串、数组、集合、Map 等。
@Size(max = 5,min = 2,message = "字符串长度在2-5之间")
private String str;
2.5 日期检查
@Future :被注释的元素必须是一个将来的日期。
@Future
private Date date1;
@FutureOrPresent :判断日期是否是将来或现在日期。
@FutureOrPresent
private Date date2;
@Past :检查该字段的日期是在过去。
@Past
private Date date3;
@PastOrPresent :判断日期是否是过去或现在日期。
@PastOrPresent
private Date date4;
2.6 其它检查
@Email :被注释的元素必须是电子邮箱地址。
@Email
private String email;
@Pattern(value) :被注释的元素必须符合指定的正则表达式。注解需要传的参数:一般默认就填入正则表达式正则表达式即可,但是java中字符串需要转义
@Pattern(regexp = "^\\d{15}|\\d{18}$", message = "身份证号码在15-18位")
private String cardNum;
2.7 Hibernate Validator 附加的约束注解
org.hibernate.validator.constraints 包下,定义了一系列的约束( constraint )注解。如下:
@Range(min=, max=) :被注释的元素必须在合适的范围内。只判断整数位数值
@Range(min = 10,max = 20,message = "数值范围在10-20之间")
private Double range;
@Length(min=, max=) :被注释的字符串的大小必须在指定的范围内。
@Length(min = 20,max = 25,message = "字符串长度在20-25之间")
private String str1;
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-ctYx6pQh-1690357601545)(file:///C:\Users\ADMINI~1\AppData\Local\Temp\ksohtml16688\wps2.jpg)]
2.8 @Valid 和 @Validated
@Valid 注解,是 Bean Validation 所定义,可以添加在普通方法、构造方法、方法参数、方法返回、成员变量上,表示它们需要进行约束校验。
@Validated 注解,是 Spring Validation 锁定义,可以添加在类、方法参数、普通方法上,表示它们需要进行约束校验。同时,@Validated 有 value 属性,支持分组校验。属性如下:
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Validated {/*** Specify one or more validation groups to apply to the validation step* kicked off by this annotation.* <p>JSR-303 defines validation groups as custom annotations which an application declares* for the sole purpose of using them as type-safe group arguments, as implemented in* {@link org.springframework.validation.beanvalidation.SpringValidatorAdapter}.* <p>Other {@link org.springframework.validation.SmartValidator} implementations may* support class arguments in other ways as well.*/Class<?>[] value() default {};}
对于初学的来说,很容易搞混 @Valid(javax.validation 包下) 和 @Validated (org.springframework.validation.annotation 包下)注解。两者大致有以下的区别:
名称 | Spring validation是否实现了声明式检验 | 是否支持嵌套校验 | 是否支持分组校验 |
---|---|---|---|
@Validated | 是 | 否 | 是 |
@Valid | 否 | 是 | 否 |
总的来说,绝大多数场景下,我们使用 @Validated 注解即可。而在有嵌套校验的场景,我们使用 @Valid 注解添加到成员属性上。
三、快速入门
3.1 引入依赖
<dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency><!--在一些高版本springboot中默认并不会引入这个依赖,需要手动引入-->
<!-- <dependency><groupId>org.hibernate.validator</groupId><artifactId>hibernate-validator</artifactId><scope>compile</scope></dependency>--><!-- 保证 Spring AOP 相关的依赖包 --><dependency><groupId>org.springframework</groupId><artifactId>spring-aspects</artifactId></dependency><!--lombok相关 方便开发--><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><scope>provided</scope></dependency><!--knife4j接口文档 方便待会进行接口测试--><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>3.0.3</version></dependency></dependencies>
1) @Valid 的使用
首先,需要在实体类的相关字段上添加需要校验的注解。
public class User {private String id; @NotBlank(message = "密码不能为空")private String password;@Min(value = 18,message = "未成年禁止入内") private Integer age;
}
其次,在controller层的方法的要校验的参数上添加@Valid注解
@PostMapping("/action/register")public Result registerByForm(@Valid @RequestBody User user){return userService.register(user);}
嵌套功能的使用
在检验 Country对象的 provinces字段时,在provinces字段上添加 @Valid 注解后,就可以检验 list 中的 provinces的属性是否符合要求;
否则只会检验 citys的集合大小是否大于1,不会校验集合中的 citys对象,比如 citys对象的 name 是否符合要求。
@GetMapping (value = "/test1")public RespBean test1(@RequestBody @Valid Country country) {log.info("country:"+country);return RespBean.sucess();}@Data
public class Country {@NotNull(message = "国家id不能为null")private Long countryId;@Valid@Size(min = 1,max = 2,message = "省份数量在1-2之间")private List<Province> provinces;@Size(min = 1,message = "城市大于1")private List<City> citys;}@Data
public class Province {@NotNull(message = "省份id不能为null")private Long id;@NotBlank(message = "省份名称不能为空")private String name;}@Data
public class City {@NotNull(message = "城市id不能为null")private Long id;@NotBlank(message = "城市名称不能为空")private String name;}
2)@Validated 的使用
@Validated 是 @Valid 的一次封装,在@Valid的基础上增加了分组以及验证排序的功能。
分组功能的使用
当一个实体类需要多种验证方式时,比如:添加时需要对姓名进行非空验证,修改时需要对id进行验证,而添加时就不需要对id进行验证。
首先,定义两个分组的接口:
public interface Add{
}public interface Update{
}
其次,在实体类上使用@Validated的分组功能。
@Data
public class Person {@NotNull(groups = Update.class, message = "更新时候id不能为空")private Long id;@NotEmpty(groups = Add.class, message = "姓名不能为空")private String name;
}在controller中,使用分组进行接口验证。
@RestController
@Slf4j
public class VerifyController {@PostMapping(value = "/validated/add")public void add(@Validated(value = Add.class) @RequestBody Person person) {...}@PostMapping(value = "/validated/update")public void update(@Validated(value = Update.class) @RequestBody Person person) {...}
}
3)定义全局异常处理,才能返回参数校验信息
异常共四种
BindException:处理所有RequestParam注解数据验证异常
MethodArgumentNotValidException:处理所有RequestBody注解参数验证异常
ConstraintViolationException
UnexpectedTypeException
@RestControllerAdvice
@Slf4j
public class GlobalDefaultExceptionHandler {/*** 处理所有RequestBody注解参数验证异常* @param exception* @return*/@ExceptionHandler(MethodArgumentNotValidException.class)public RespBean methodArgumentNotValidException(MethodArgumentNotValidException exception){//封装需要返回的错误信息List<FieldError> fieldErrors = exception.getBindingResult().getFieldErrors();log.error("参数绑定异常,ex = {}", fieldErrors.get(0).getDefaultMessage());return RespBean.error(fieldErrors.get(0).getDefaultMessage());}/*** 处理所有RequestParam注解数据验证异常* @param e* @return*/@ExceptionHandler(BindException.class)public RespBean validationBodyException(BindException e){e.printStackTrace();//打印校验住的所有的错误信息StringBuilder sb = new StringBuilder("参数错误:[");List<ObjectError> list = ((BindException) e).getAllErrors();for (ObjectError item : list) {sb.append(item.getDefaultMessage()).append(',');}sb.deleteCharAt(sb.length()-1);sb.append(']');String msg = sb.toString();return RespBean.error(msg);}@ExceptionHandler(UnexpectedTypeException.class)public RespBean unexpectedTypeException(UnexpectedTypeException exception){//封装需要返回的错误信息log.error("参数绑定异常,ex = {}", exception.getMessage());return RespBean.error(exception.getMessage());}@ExceptionHandler(value = ConstraintViolationException.class)public RespBean ConstraintViolationExceptionHandler(ConstraintViolationException ex) {Set<ConstraintViolation<?>> constraintViolations = ex.getConstraintViolations();Iterator<ConstraintViolation<?>> iterator = constraintViolations.iterator();List<String> msgList = new ArrayList<>();while (iterator.hasNext()) {ConstraintViolation<?> cvl = iterator.next();msgList.add(cvl.getMessageTemplate());}return RespBean.error(msgList.toString());}
}
补充:分组功能使用多个组检验数据
contoller层使用{}添加多个组别
@PostMapping(value = "/validated/del")public RespBean dealMore(@Validated(value = {Add.class,Update.class}) @RequestBody Person person) {return RespBean.sucess();}
自定义注解
1-添加自定义注解类接口
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE, ElementType.CONSTRUCTOR, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Constraint(validatedBy = {MobileValidator.class})
public @interface MobileCheck {boolean required() default true;String message() default "手机号码格式有误!";Class<?>[] groups() default {};Class<? extends Payload>[] payload() default {};
}
2-实现自定义校验器类
/** 手机号校验器* */
public class MobileValidator implements ConstraintValidator<MobileCheck, String> {private boolean required = false;private static final Pattern mobile_pattern = Pattern.compile("1\\d{10}");public static boolean isMobile(String src){if (StringUtils.isEmpty(src)){return false;}Matcher matcher = mobile_pattern.matcher(src);return matcher.matches();}@Overridepublic void initialize(MobileCheck isMobile) {required = isMobile.required();}@Overridepublic boolean isValid(String value, ConstraintValidatorContext context) {if (required) { //如果必须(不能为空),进行校验return isMobile(value);} else { //如果不必须,非空进行校验if (StringUtils.isEmpty(value)) {return true;}return isMobile(value);}}
}
3-使用
@Data
public class Country {@MobileCheckprivate String phone;}@PostMapping(value = "/checkPhone")
public RespBean checkPhone(@Valid @RequestBody Country country) {return RespBean.sucess();
}
}
@Override
public boolean isValid(String value, ConstraintValidatorContext context) {if (required) { //如果必须(不能为空),进行校验return isMobile(value);} else { //如果不必须,非空进行校验if (StringUtils.isEmpty(value)) {return true;}return isMobile(value);}
}
}
3-使用
@Data
public class Country {
@MobileCheck
private String phone;
}
@PostMapping(value = “/checkPhone”)
public RespBean checkPhone(@Valid @RequestBody Country country) {
return RespBean.sucess();
}