项目介绍

变更日志

特性

开源地址

创作目的

hibernate-validator 无法满足的场景

validation-api 过于复杂

自定义缺乏灵活性

过程式编程 vs 注解式编程

项目模块说明

依赖说明

快速开始

准备工作

maven 引入

<dependency>
 <groupId>com.github.houbb</groupId>
 <artifactId>valid-jsr</artifactId>
 <version>0.2.2</version>
</dependency>

工具类

User user = new User();
user.sex("what").password("old").password2("new");
ValidHelper.failOverThrow(user);

name: 值 <null> 不是预期值,password: 值 <old> 不是预期值,sex: 值 <what> 不是预期值

public class User {
 /**
 * 名称
 */
 @HasNotNull({"nickName"})
 private String name;
 /**
 * 昵称
 */
 private String nickName;
 /**
 * 原始密码
 */
 @AllEquals("password2")
 private String password;
 /**
 * 新密码
 */
 private String password2;
 /**
 * 性别
 */
 @Ranges({"boy", "girl"})
 private String sex;
 /**
 * 失败类型枚举
 */
 @EnumRanges(FailTypeEnum.class)
 private String failType;
 //Getter and Setter
}

例子

public void helloValidTest() {
 IResult result = ValidBs.on(null, JsrConstraints.notNullConstraint())
 .result()
 .print();
 Assert.assertFalse(result.pass());
}

DefaultResult{pass=false, notPassList=[DefaultConstraintResult{pass=false, message='预期值为 <not null>,实际值为 <null>', value=null, constraint='NotNullConstraint', expectValue='not null'}], allList=null}

方法初步说明

public void helloValidAllConfigTest() {
 IResult result = ValidBs.on(null, JsrConstraints.notNullConstraint())
 .fail(Fails.failFast())
 .group()
 .valid(DefaultValidator.getInstance())
 .result()
 .print();
 Assert.assertFalse(result.pass());
}

on(Object value, IConstraint... constraints) 指定约束

fail(IFail fail)

group(Class[] classes) 支持分组验证

valid(IValidator validator) 支持验证策略

result(IResultHandler resultHandler) 验证结果处理

IResult 内置方法

@Test(expected = ValidRuntimeException.class)
public void resultThrowsExTest() {
 ValidBs.on(null, notNullValidatorEntry())
 .valid()
 .result()
 .throwsEx();
}

内置的属性约束

valid-core

enumRangesConstraint

/**
 * 枚举范围内约束
 * (1)当前值必须在枚举类对应枚举的 toString() 列表中。
 * @param enumClass 枚举类,不可为空
 * @return 约束类
 * @since 0.1.1
 * @see com.github.houbb.valid.core.annotation.constraint.EnumRanges 枚举类指定范围注解
 */
public static IConstraint enumRangesConstraint(final Class<? extends Enum> enumClass)

IResult result = ValidBs.on("DEFINE", Constraints.enumRangesConstraint(FailTypeEnum.class))
 .result();
Assert.assertFalse(result.pass());

rangesConstraint

 * 值在指定范围内约束
 * (1)这里为了和注解保持一致性,暂时只支持 String
 * @param strings 对象范围
 * @return 约束类
 * @since 0.1.1
 * @see com.github.houbb.valid.core.annotation.constraint.Ranges String 指定范围内注解
 */
public static IConstraint rangesConstraint(String ... strings)

IResult result = ValidBs.on("DEFINE", Constraints.rangesConstraint("FAIL_OVER",
 "FAIL_FAST"))
 .result();
Assert.assertFalse(result.pass());

valid-jsr

自定义约束实现

需求

例子

自定义 notNullConstraint

IResult result = ValidBs.on(null, new AbstractStrictConstraint() {
 @Override
 protected boolean pass(IConstraintContext context, Object value) {
 return value != null;
 }
}).result();
Assert.assertFalse(result.pass());

自定义 assertTrueConstraint

IConstraint assertTrueConstraint = new AbstractConstraint<Boolean>() {
 @Override
 protected boolean pass(IConstraintContext context, Boolean value) {
 return false;
 }
};
IResult nullValid = ValidBs.on(null, assertTrueConstraint)
 .result();
Assert.assertTrue(nullValid.pass());
IResult falseValid = ValidBs.on(false, assertTrueConstraint)
 .result();
Assert.assertFalse(falseValid.pass());

core 模块注解验证

内置注解

测试对象

public class User {
 /**
 * 名称
 */
 @HasNotNull({"nickName"})
 private String name;
 /**
 * 昵称
 */
 private String nickName;
 /**
 * 原始密码
 */
 @AllEquals("password2")
 private String password;
 /**
 * 新密码
 */
 private String password2;
 /**
 * 性别
 */
 @Ranges({"boy", "girl"})
 private String sex;
 /**
 * 失败类型枚举
 */
 @EnumRanges(FailTypeEnum.class)
 private String failType;
 //fluent getter & setter
}

测试代码

User user = new User();
user.sex("what").password("old").password2("new")
 .failType("DEFINE");
IResult result = ValidBs.on(user)
 .fail(Fails.failOver())
 .result()
 .print();
Assert.assertFalse(result.pass());

DefaultResult{pass=false, notPassList=[DefaultConstraintResult{pass=false, message='值 <null> 不是预期值', value=null, constraint='HasNotNullConstraint', expectValue=''}, DefaultConstraintResult{pass=false, message='值 <old> 不是预期值', value=old, constraint='AllEqualsConstraint', expectValue=''}, DefaultConstraintResult{pass=false, message='值 <what> 不是预期值', value=what, constraint='RangesConstraint', expectValue=''}, DefaultConstraintResult{pass=false, message='值 <DEFINE> 不是预期值', value=DEFINE, constraint='EnumRangesConstraint', expectValue=''}], allList=null}

jsr 模块注解验证

注解

对象定义

public class JsrUser {
 @Null
 private Object nullVal;
 @NotNull
 private String notNullVal;
 @AssertFalse
 private boolean assertFalse;
 @AssertTrue
 private boolean assertTrue;
 @Pattern(regexp = "[123456]{2}")
 private String pattern;
 @Size(min = 2, max = 5)
 private String size;
 @DecimalMax("12.22")
 private BigDecimal decimalMax;
 @DecimalMin("1.22")
 private BigDecimal decimalMin;
 @Min(10)
 private long min;
 @Max(10)
 private long max;
 @Past
 private Date past;
 @Future
 private Date future;
 @Digits(integer = 2, fraction = 4)
 private Long digits;
 //fluent getter and setter
}

测试代码

public void beanFailTest() {
 Date future = DateUtil.getFormatDate("90190101", DateUtil.PURE_DATE_FORMAT);
 Date past = DateUtil.getFormatDate("20190101", DateUtil.PURE_DATE_FORMAT);
 JsrUser jsrUser = new JsrUser();
 jsrUser.assertFalse(true)
 .assertTrue(false)
 .decimalMin(new BigDecimal("1"))
 .decimalMax(new BigDecimal("55.55"))
 .min(5)
 .max(20)
 .digits(333333L)
 .future(past)
 .past(future)
 .nullVal("123")
 .notNullVal(null)
 .pattern("asdfasdf")
 .size("22222222222222222222");
 IResult result = ValidBs.on(jsrUser)
 .fail(Fails.failOver())
 .valid(JsrValidator.getInstance())
 .result()
 .print();
 Assert.assertFalse(result.pass());
}

DefaultResult{pass=false, notPassList=[DefaultConstraintResult{pass=false, message='值必须为空', value=123, constraint='NullConstraint', expectValue='null'}, DefaultConstraintResult{pass=false, message='值必须为非空', value=null, constraint='NotNullConstraint', expectValue='not null'}, DefaultConstraintResult{pass=false, message='值必须为假', value=true, constraint='AssertFalseConstraint', expectValue='false'}, DefaultConstraintResult{pass=false, message='值必须为真', value=false, constraint='AssertTrueConstraint', expectValue='true'}, DefaultConstraintResult{pass=false, message='值必须满足正则表达式', value=asdfasdf, constraint='PatternConstraint', expectValue='必须匹配正则表达式 [123456]{2}'}, DefaultConstraintResult{pass=false, message='值必须为在指定范围内', value=22222222222222222222, constraint='SizeConstraint', expectValue='大小必须在范围内 [2, 5]'}, DefaultConstraintResult{pass=false, message='值必须小于金额最大值', value=55.55, constraint='DecimalMaxConstraint', expectValue='小于等于 12.22'}, DefaultConstraintResult{pass=false, message='值必须大于金额最小值', value=1, constraint='DecimalMinConstraint', expectValue='大于等于 1.22'}, DefaultConstraintResult{pass=false, message='值必须大于最小值', value=5, constraint='MinConstraint', expectValue='大于等于 10'}, DefaultConstraintResult{pass=false, message='值必须小于最大值', value=20, constraint='MaxConstraint', expectValue='小于等于 10'}, DefaultConstraintResult{pass=false, message='时间必须在过去', value=Fri Jan 01 00:00:00 CST 9019, constraint='PastConstraint', expectValue='小于等于 Sun Oct 13 12:12:07 CST 2019'}, DefaultConstraintResult{pass=false, message='时间必须在未来', value=Tue Jan 01 00:00:00 CST 2019, constraint='FutureConstraint', expectValue='大于等于 Sun Oct 13 12:12:07 CST 2019'}, DefaultConstraintResult{pass=false, message='值必须满足位数', value=333333, constraint='DigitsConstraint', expectValue='整数位数 [2], 小数位数 [4]'}], allList=null}

@Valid 递归属性验证

需求

对象定义

public class ValidUser {
 /**
 * 子节点
 */
 @Valid
 private User user;
 //fluent setter & getter
}

测试代码

public void beanFailTest() {
 User user = new User();
 user.sex("default").password("old").password2("new")
 .failType("DEFINE");
 ValidUser validUser = new ValidUser();
 validUser.user(user);
 IResult result = ValidBs.on(validUser)
 .fail(Fails.failOver())
 .result()
 .print();
 Assert.assertFalse(result.pass());
}

DefaultResult{pass=false, notPassList=[DefaultConstraintResult{pass=false, message='值 <null> 不是预期值', value=null, constraint='HasNotNullConstraint', expectValue=''}, DefaultConstraintResult{pass=false, message='值 <old> 不是预期值', value=old, constraint='AllEqualsConstraint', expectValue=''}, DefaultConstraintResult{pass=false, message='值 <default> 不是预期值', value=default, constraint='RangesConstraint', expectValue=''}, DefaultConstraintResult{pass=false, message='值 <DEFINE> 不是预期值', value=DEFINE, constraint='EnumRangesConstraint', expectValue=''}], allList=null}

自引用问题

i18n 支持

需求

指定为英文

public void i18nEnTest() {
 Locale.setDefault(Locale.ENGLISH);
 IResult result = ValidBs.on(null, JsrConstraints.notNullConstraint())
 .result()
 .print();
 Assert.assertEquals("Expect is <not null>, but actual is <null>.", result.notPassList().get(0).message());
}

指定为中文

public void i18nZhTest() {
 Locale.setDefault(Locale.CHINESE);
 IResult result = ValidBs.on(null, JsrConstraints.notNullConstraint())
 .result()
 .print();
 Assert.assertEquals("预期值为 <not null>,实际值为 <null>", result.notPassList().get(0).message());
}

IFail 失败策略接口详解

需求

创建方式

测试代码

failFast

IResult result = ValidBs.on("12", JsrConstraints.sizeConstraintMin(3),
 JsrConstraints.patternConstraint("[678]{3}"))
 .fail(Fails.failFast())
 .result()
 .print();
Assert.assertEquals(1, result.notPassList().size());

DefaultResult{pass=false, notPassList=[DefaultConstraintResult{pass=false, message='预期值为 <必须匹配正则表达式 [678]{3}>,实际值为 <12>', value=12, constraint='PatternConstraint', expectValue='必须匹配正则表达式 [678]{3}'}], allList=null}

failOver

IResult result = ValidBs.on("12", JsrConstraints.sizeConstraintMin(3),
 JsrConstraints.patternConstraint("[678]{3}"))
 .fail(Fails.failOver())
 .result()
 .print();
Assert.assertEquals(2, result.notPassList().size());

DefaultResult{pass=false, notPassList=[DefaultConstraintResult{pass=false, message='预期值为 <必须匹配正则表达式 [678]{3}>,实际值为 <12>', value=12, constraint='PatternConstraint', expectValue='必须匹配正则表达式 [678]{3}'}, DefaultConstraintResult{pass=false, message='预期值为 <大小必须在范围内 [3, 2147483647]>,实际值为 <2>', value=12, constraint='SizeConstraint', expectValue='大小必须在范围内 [3, 2147483647]'}], allList=null}

IValidator 验证策略接口详解

需求

默认验证器策略-DefaultValidator

JSR-303 验证器策略-JsrValidator

IResult result = ValidBs.on(jsrUser)
 .valid(JsrValidator.getInstance())
 .result()
 .print();

自定义验证器策略

IResultHandler 结果处理策略接口详解

需求

接口

public interface IResultHandler<T> {
 /**
 * 对约束结果进行统一处理
 * @param constraintResultList 约束结果列表
 * @return 结果
 */
 T handle(final List<IConstraintResult> constraintResultList);
}

简单实现

ValidBs.on("12", JsrConstraints.sizeConstraintMin(2))
 .result(ResultHandlers.simple())
 .print();

DefaultResult{pass=true, notPassList=[], allList=null}

详细实现

ValidBs.on("12", JsrConstraints.sizeConstraintMin(2))
 .result(ResultHandlers.detail())
 .print();

DefaultResult{pass=true, notPassList=[], allList=[DefaultConstraintResult{pass=true, message='null', value=12, constraint='SizeConstraint', expectValue='null'}]}

IResult 结果接口详解

说明

测试代码

@Test(expected = ValidRuntimeException.class)
public void methodsTest() {
 IResult result = ValidBs.on("12", JsrConstraints.sizeConstraintMin(3))
 .result(ResultHandlers.detail())
 .print()
 .throwsEx();
 Assert.assertFalse(result.pass());
 Assert.assertEquals(1, result.notPassList().size());
 Assert.assertEquals(1, result.allList().size());
}

DefaultResult{pass=false, notPassList=[DefaultConstraintResult{pass=false, message='预期值为 <大小必须在范围内 [3, 2147483647]>,实际值为 <2>', value=12, constraint='SizeConstraint', expectValue='大小必须在范围内 [3, 2147483647]'}], allList=[DefaultConstraintResult{pass=false, message='预期值为 <大小必须在范围内 [3, 2147483647]>,实际值为 <2>', value=12, constraint='SizeConstraint', expectValue='大小必须在范围内 [3, 2147483647]'}]}

IConstraint 约束接口详解

需求

接口说明

public interface IConstraint {
 /**
 * 触发约束规则
 * @param context 上下文
 * @return 结果
 * @since 0.0.3
 */
 IConstraintResult constraint(final IConstraintContext context);
}

自定义说明

IValidEntry 验证明细接口详解

说明

使用方式

IValidEntry validEntry = ValidEntry.of(JsrConstraints.notNullConstraint());
IResult result = ValidBs.on(null, validEntry)
 .result()
 .print();
Assert.assertFalse(result.pass());

message() 自定义提示消息

final IValidEntry validEntry = ValidEntry.of(JsrConstraints.notNullConstraint())
 .message("自定义:指定值不能为空");
IResult result = ValidBs.on(null, validEntry)
 .valid()
 .result();
Assert.assertEquals("自定义:指定值不能为空", result.notPassList().get(0).message());

group() 分组验证

需求

测试代码

final IValidEntry firstEntry = ValidEntry.of(JsrConstraints.sizeConstraint(5, 10))
 .group(String.class);
final IValidEntry otherEntry = ValidEntry.of(JsrConstraints.sizeConstraint(3, 20))
 .group(Integer.class);
IResult result = ValidBs
 .on("12", firstEntry, otherEntry)
 .fail(Fails.failOver())
 .group(String.class)
 .result();
Assert.assertEquals(1, result.notPassList().size());

condition 拓展

自定义注解

需求

核心设计理念

@AllEquals 注解解析

注解内容

@Inherited
@Documented
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Constraint(AtAllEqualsConstraint.class)
public @interface AllEquals {
 /**
 * 当前字段及其指定的字段 全部相等
 * 1. 字段类型及其他字段相同
 * @return 指定的字段列表
 */
 String[] value();
 /**
 * 提示消息
 * @return 错误提示
 */
 String message() default "";
 /**
 * 分组信息
 * @return 分组类
 * @since 0.1.2
 */
 Class[] group() default {};
}

注解与约束的关系

@Constraint 注解

@Inherited
@Documented
@Target(ElementType.ANNOTATION_TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface Constraint {
 /**
 * 约束条件实现类
 * @return 实现类 class
 */
 Class<? extends IAnnotationConstraint> value();
}

IAnnotationConstraint 接口

/**
 * 注解约束规则接口
 * 注意:所有的实现类都需要提供无参构造函数。
 * @author binbin.hou
 * @since 0.0.9
 */
public interface IAnnotationConstraint<A extends Annotation> extends IConstraint {
 /**
 * 初始化映射关系
 * @param annotation 注解信息
 * @since 0.0.9
 */
 void initialize(A annotation);
}

后期特性

参考项目

JSR 标准

ROAD-MAP