当前位置: 首页 > 工具软件 > yue-library > 使用案例 >

SpringBoot校验框架:yue-library

洪博艺
2023-12-01

validator

  • 出色的服务端校验框架validator,功能齐全、简单易用
  • 完善的校验方式,支持单参数连写校验、POJO对象校验、分组校验
  • 丰富的校验注解,更贴切国内校验场景
  • 友好的异常提示,错误迅速定位,开发简单易懂

一、功能简介

主要提供便捷的后台数据校验功能,支持单个字段或参数校验,也支持通过注解校验对象,用法简单。

提供基本的非空、长度、大小等校验方法,也提供一些特殊的正则校验、身份证、电话、邮箱、IP等校验方法。

二、注解介绍

@Validated 被注解的元素是一个POJO对象,用于检查此对象的所有被注解字段的值是否符合预期

Bean Validation 中内置的 constraint

注解作用
@Null被注解的元素必须为 null
@NotNull被注解的元素必须不为 null
@NotBlank被注解的元素必须不为空,并且必须包含至少一个非空白字符
@NotEmpty被注解的元素必须非空
@AssertTrue被注解的元素必须为 true
@AssertFalse被注解的元素必须为 false
@Max被注解的元素必须是一个数字,其值必须小于等于指定的最大值
@Min被注解的元素必须是一个数字,其值必须大于等于指定的最小值
@DecimalMax被注解的元素必须是一个数字,其值必须小于等于指定的最大值
@DecimalMin被注解的元素必须是一个数字,其值必须大于等于指定的最小值
@Digits被注解的元素必须是一个数字,其值必须在可接受的范围内
@Positive被注解的元素必须是严格意义上的正数
@PositiveOrZero被注解的元素必须是正数或0
@Negative被注解的元素必须是一个严格意义上的负数
@NegativeOrZero被注解的元素必须是负数或0
@Past被注解的元素必须是过去的某个瞬间、日期或时间
@PastOrPresent被注解的元素必须是过去或现在的某个瞬间、日期或时间
@Future被注解的元素必须是将来的某个瞬间、日期或时间。
@FutureOrPresent被注解的元素必须是当前或将来的某个瞬间、日期或时间。
@Size被注解的元素的大小必须在指定的范围内
@Email被注解的元素必须是电子邮箱地址
@Pattern被注解的元素必须符合指定的正则表达式

Hibernate Validator 附加的 constraint

注解作用
@Length被注解的字符串的大小必须在指定的范围内
@Range被注解的元素必须在合适的范围内
@URL验证带注解的字符串是否为URL
@Currency货币金额必须在正确的货币单位
@CreditCardNumber带注解的元素必须表示有效的信用卡号
@CodePointLength验证包含字符序列的代码点长度在min和max之间
@ConstraintComposition布尔运算符,应用于组合约束注解的所有约束
@SafeHtml验证用户提供的富文本值,以确保它不包含恶意代码,例如嵌入的<script>元素
@UniqueElements验证所提供集合中的每个对象都是惟一的,即不能在集合中找到两个相等的元素
@EAN检查带注解的字符序列是否是有效的EAN 13号。验证数字的长度和校验数字
@ISBN检查带注解的字符序列是否是有效的ISBN。数字的长度和校验数字都经过验证
@LuhnCheckLuhn算法检查约束
@Mod10CheckModulo 10 检查约束
@Mod11CheckModulo 11 检查约束
@ParameterScriptAssert方法级约束,它根据带注解的方法或构造函数计算脚本表达式
@ScriptAssert类级约束,它根据带注解的元素计算脚本表达式

Yue Validator 附加的 constraint

注解作用
@Cellphone手机号校验
@IdCard身份证校验
@PlateNumber中国车牌号校验
@Birthday生日校验
@Chinese中文校验
@English英语校验
@UUIDUUID校验
@IPV4IPV4地址校验
@IPV6IPV6地址校验
@MacAddressMAC地址校验
@CarDrivingLicence验证是否为驾驶证(仅限:中国驾驶证档案编号)
@CarVin验证是否为车架号
@CreditCode是否是有效的统一社会信用代码
@ZipCode验证是否为邮政编码(中国)

三、参数校验

单个参数校验

校验参数定义:单个参数

String name = validationIPO.getName();
String email = validationIPO.getEmail();
String cellphone = validationIPO.getCellphone();
int age = validationIPO.getAge();
DateTime birthday = validationIPO.getBirthday();

获取参数校验器:通过Bean注入方式

@Autowired
private Validator validator;

获取参数校验器:通过静态方法方式

Validator.getValidatorAndSetParam(email).email("email");

单个参数校验

validator.param(email).email("email");
validator.param(cellphone).cellphone("cellphone");
validator.param(name).notNull("name").chinese("name").length(1, 30, "name");

单个参数校验:通过param()连写(直接切换校验对象)

validator.param(name).notNull("name").param(email).length(5, 25, "email").param(age).min(20, "age").max(60, "age");

POJO对象校验(推荐

校验参数定义:POJO对象(在类的属性上定义注解,同时支持自定义错误信息)

@Data
public class ValidationIPO {

    @NotEmpty(message = "姓名不能为空")
    @Length(max = 20, message = "姓名不能超过20个字")
    private String name;
    
    private DateTime birthday;
    
    @IdCard
    private String idcard;
    
    @Max(30)
    @Min(12)
    private int age;
    
    @Email
    @Length(max = 50)
    private String email;
    
    @Cellphone
    private String cellphone;
    
    @Pattern(regexp = "[1-9]([0-9]{5,11})")
    private String qq;
    
}

校验方式一Controller层,通过注解@Validated校验(推荐)

@PostMapping("/valid")
public Result<?> valid(@Validated ValidationIPO validationIPO) {

校验方式二:通过调用validator.valid()方法

validator.valid(validationIPO);
// 同样支持连写
validator.valid(validationIPO).param(birthday).birthday("birthday");

校验方式三

  1. @Validated注解添加到POJO类上
@Data
@Validated
public class ValidationIPO {
	// ...
}
  1. Controller层接收此实体参数
@PostMapping("/valid")
public Result<?> valid(ValidationIPO validationIPO) {

分组校验

当增删改查都复用同一个POJO时,分组校验就显得尤为重要,比如新增时不允许传入id,修改时必须有id,使用方式如下:

示例POJO(多了一个groups属性):

@Data
public class ValidationGroupIPO extends ValidationGroups {

    @Null(groups = {Create.class})
    @NotNull(groups = {Delete.class, Update.class, Read.class})
    private Long id;

}

校验方式,在控制器上指定@Validated注解的value属性值,如下:

@PostMapping("/validationGroupCreate")
public Result<?> validationGroupCreate(@Validated(ValidationGroups.Create.class) ValidationGroupIPO validationGroupIPO) {

分组校验可灵活使用,还支持以下能力:

  • 使用GroupSequence注解可指定分组校验顺序,同时还拥有短路能力
  • 使用GroupSequenceProvider注解可动态指定分组校验顺序,解决多字段组合逻辑校验的痛点问题,但需自行实现DefaultGroupSequenceProvider接口

参考1参考2

四、校验异常处理

当校验不通过时会抛出ValidateException,yue-library默认已在ResultExceptionHandler类中进行了拦截处理,将异常提示转换成友好的RESTful响应。

错误响应示例如下:

{
    "code": 433,
    "msg": "参数校验未通过,请参照API核对后重试",
    "flag": false,
    "count": null,
    "data": [
        {
            "errorkey": "cellphone",
            "errorValue": null,
            "errorHintMsg": "不是一个合法的手机号码"
        },
        {
            "errorkey": "idcard",
            "errorValue": "500223199605156666",
            "errorHintMsg": "不是一个合法的身份证号码"
        }
    ]
}

五、扩展知识

  • @Valid注解由java提供,验证时不支持指定校验分组
  • @Validated注解由spring扩展提供,验证时支持指定校验分组,推荐使用
  • 验证还支持递归校验(即:POJO中包含POJO)
  • 关于如何自定义校验注解,参考@Cellphone@IdCard等(即:yue-library扩展实现)校验注解即可
 类似资料: