オブジェクトの検証
am.ik.yavi.builder.ValidatorBuilder は、既に存在するオブジェクトを検証する Validator<T> を構築します。オブジェクトのプロパティは、notNull() のような制約が拒否しない限り null でも有効です。これは Yavi.schema() のプロパティとの違いです。
Validator<User> validator = ValidatorBuilder.<User>of()
.constraint(User::name, "name", c -> c.notNull().lessThanOrEqual(20))
.constraint(User::email, "email", c -> c.notNull().greaterThanOrEqual(5).lessThanOrEqual(50).email())
.constraint(User::age, "age", c -> c.greaterThanOrEqual(0).lessThanOrEqual(200))
.build();
ConstraintViolations violations = validator.validate(user);
プロパティの型が曖昧になる場合は、constraint ではなく型ごとのメソッドを使います。_string、_integer、_bigDecimal などのメソッドはプロパティを読む Function を取るため、レコードのアクセサ、getter、ラムダのいずれも使えます。
Validator<User> validator = ValidatorBuilder.<User>of()
._string(User::name, "name", c -> c.notNull().lessThanOrEqual(20))
._string(User::email, "email", c -> c.notNull().email())
._integer(User::age, "age", c -> c.greaterThanOrEqual(0))
.build();
バリデータはスレッドセーフで、繰り返し使えます。既定ではすべての違反を蓄積します。最初の違反で止めるには「フェイルファストモード」を参照してください。
ネストしたオブジェクト
nest はネストしたオブジェクトにバリデータを適用します。ネストしたバリデータは渡すことも、その場で定義することもできます。
Validator<Address> addressValidator = ValidatorBuilder.<Address>of()
.nest(Address::country, "country", countryValidator)
.nest(Address::city, "city",
b -> b._string(City::name, "name", c -> c.notBlank().lessThanOrEqual(100)))
.build();
ネストしたオブジェクトの違反は、その名前の下に配置されます (country.name)。nestIfPresent はネストしたオブジェクトが null でない場合にだけ検証します。
Validator<Order> validator = ValidatorBuilder.<Order>of()
.nestIfPresent(Order::customer, "customer", customerValidator)
.build();
コレクション、Map、配列の要素
forEach はコレクション、Map の値、配列の各要素にバリデータを適用します。要素の名前は違反名のインデックスになります (histories[0].revision)。
Validator<Histories> validator = ValidatorBuilder.<Histories>of()
.forEach(Histories::value, "histories", historyValidator)
.build();
ネストしたオブジェクトと同様に、その場で定義するバリデータと forEachIfPresent も使えます。
Validator<Histories> validator = ValidatorBuilder.<Histories>of()
.forEach(Histories::value, "histories",
b -> b._integer(History::revision, "revision", c -> c.greaterThanOrEqual(1)))
.build();
既定で検証できるのは Map の値だけです。Map のキーを検証するには、キーをコレクションとして読みます。
Validator<CodeMap> validator = ValidatorBuilder.<CodeMap>of()
.forEach(codeMap -> codeMap.asMap().keySet(), "codeMap",
b -> b._string(k -> k, "value", c -> c.notEmpty()))
.build();
. 以外のメッセージキー区切り文字を持つ ValidatorBuilder は、forEach の下の名前でもそれを使います。
new ValidatorBuilder<Order>("/")
.forEach(Order::addresses, "addresses", b -> b._string(Address::street, "street", c -> c.notBlank()))
.build();
// addresses[0]/street
次のプログラムはバリデータをネストし、要素のバリデータを適用してから、違反名を出力します。
条件付きの制約
constraintOnCondition は条件が成り立つ場合にだけバリデータを適用します。条件は対象オブジェクトと検証呼び出しの ConstraintContext を受け取るため、リクエストの属性を読めます。
Validator<User> validator = ValidatorBuilder.<User>of()
.constraintOnCondition((user, context) -> "IT".equals(context.attribute("country").value()),
b -> b._string(User::taxId, "taxId", c -> c.notBlank()))
.build();
ConstraintContext context = ConstraintContext.from(Map.of("country", "IT"));
ConstraintViolations violations = validator.validate(user, context);
ConstraintCondition.hasAttribute と ConstraintCondition.hasAttributeWithValue は、よくある属性チェックの省略形です。
Validator<User> validator = ValidatorBuilder.<User>of()
.constraintOnCondition(ConstraintCondition.hasAttributeWithValue("country", "IT"),
b -> b._string(User::taxId, "taxId", c -> c.notBlank()))
.build();
制約グループ
ConstraintGroup は名前を持つ ConstraintContext です。constraintOnGroup で追加した制約は、そのグループを検証した場合にだけ適用されます。
enum Group implements ConstraintGroup {
CREATE, UPDATE
}
Validator<User> validator = ValidatorBuilder.<User>of()
.constraintOnGroup(Group.CREATE, b -> b._integer(User::id, "id", c -> c.isNull()))
.constraintOnGroup(Group.UPDATE, b -> b._integer(User::id, "id", c -> c.notNull()))
.build();
ConstraintViolations violations = validator.validate(user, Group.CREATE);
グループは enum を使わずに ConstraintGroup.of("CREATE") でも作成できます。グループを持たない制約はすべてのグループで適用され、validate にグループを渡さない場合は ConstraintGroup.DEFAULT が使われます。グループは名前で一致します。
オブジェクト全体の規則
constraintOnTarget は複数のプロパティにまたがる規則を追加します。違反は指定した名前の下に報告されます。
Validator<Range> validator = ValidatorBuilder.<Range>of()
._integer(Range::from, "from", c -> c.greaterThan(0))
._integer(Range::to, "to", c -> c.greaterThan(0))
.constraintOnTarget(range -> range.to() > range.from(), "to", "to.isGreaterThanFrom",
"\"to\" must be greater than \"from\"")
.build();
規則はプロパティの後に評価されます。CustomConstraint<T> で述語とメッセージを渡すこともできます。「カスタム制約」を参照してください。
メッセージの上書き
message は、その直前の制約のメッセージを置き換えます。{0} はプロパティ名、その他のプレースホルダは制約の引数、最後の引数は制約に違反した値です。
Validator<User> validator = ValidatorBuilder.<User>of()
._string(User::name, "name", c -> c.notNull().message("{0} is required!")
.greaterThanOrEqual(1).message("{0} is too small!")
.lessThanOrEqual(20).message("{0} is too large!"))
.build();
message(String) に渡したテキストがメッセージになります。MessageFormatter はそれをリソースバンドルのメッセージで置き換えず、引数を埋めるだけです。違反はメッセージキーを保持します。独自のメッセージをバンドルでローカライズするには、キーを付けます。
c -> c.notBlank().message(ViolationMessage.of("user.name.notBlank", "Enter your name"))
他の制約のメッセージをフォーマットするには、ビルダーに MessageFormatter を設定します。
Validator<User> validator = ValidatorBuilder.<User>of()
.messageFormatter(new MessageSourceMessageFormatter(messageSource::getMessage))
._string(User::name, "name", c -> c.notBlank())
.build();
フェイルファストモード
failFast(true) は最初の違反で検証から戻ります。モードはネストしたバリデータ、要素のバリデータ、条件付きバリデータにも引き継がれます。
Validator<User> validator = ValidatorBuilder.<User>of()
._string(User::name, "name", c -> c.notNull().lessThanOrEqual(20))
._string(User::email, "email", c -> c.notNull().email())
.failFast(true)
.build();
Validator<User> failFastValidator = validator.failFast(true);
boolean failFast = failFastValidator.isFailFast();
制約名の衝突
conflictStrategy(ConflictStrategy) は、同じ制約名が複数回追加された場合の動作を決めます。既定の ConflictStrategy.NOOP は新しい制約を追加します。ConflictStrategy.OVERRIDE は既存の制約を削除します。
Validator<User> validator = ValidatorBuilder.<User>of()
.conflictStrategy(ConflictStrategy.OVERRIDE)
._string(User::name, "name", c -> c.notNull())
._string(User::name, "name", c -> c.notBlank()) // replaces the previous "name" constraint
.build();
独自の戦略は既存の述語のリストを変更できます。新しい述語はその後に追加されます。
違反の扱い
validate は ConstraintViolations を返します。これは List<ConstraintViolation> であり、オブジェクトが有効な場合は空です。各違反を読むには繰り返します。
for (ConstraintViolation violation : violations) {
String name = violation.name(); // tags[1]
String key = violation.messageKey(); // charSequence.notBlank
String message = violation.message();
Object[] args = violation.args();
Object value = violation.violatedValue();
String pointer = violation.pointer(); // /tags/1
}
値そのものを検証した場合、ConstraintViolation に名前はありません。そのメッセージは「The value」となります。
messagesByName と messagesByPointer は、フォームや API レスポンスが必要とする形でメッセージを返します。details は JSON ライブラリがそのままシリアライズできるレコードを返します。
Map<String, List<String>> byName = violations.messagesByName();
Map<String, List<String>> byPointer = violations.messagesByPointer();
List<ViolationDetail> details = violations.details();
// [{"name": "items[1].quantity", "pointer": "/items/1/quantity",
// "messageKey": "numeric.lessThanOrEqual", "message": "...", "params": {"max": 99}}]
ViolationDetail はレコードの sealed インタフェースです。アクセサは name()、pointer()、messageKey()、message()、params() で、位置引数は ConstraintViolation#args() にあります。制約に違反した値は詳細に含まれないため、詳細はそのまま返せます。details() は変更できないリストを返します。