はじめる
注意
この内容は https://hibernate.org/validator/documentation/getting-started/ をもとにしています。
YAVI へようこそ。
以降では、YAVI をアプリケーションに組み込むための最初の手順を説明します。
前提
- Java Runtime 8 以上
- Apache Maven
プロジェクトの設定
Maven プロジェクトで YAVI を使うには、pom.xml に次の依存関係を追加します。
<dependency>
<groupId>am.ik.yavi</groupId>
<artifactId>yavi</artifactId>
<version>0.17.3</version>
</dependency>
このチュートリアルでは JUnit 5 と AssertJ を使います。 必要に応じて次の依存関係を追加します。
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-api</artifactId>
<version>5.14.4</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.assertj</groupId>
<artifactId>assertj-core</artifactId>
<version>3.27.7</version>
<scope>test</scope>
</dependency>
制約の適用
制約を適用する方法を例で見ていきます。
src/main/java/com/example/Car.java を作成し、次のコードを書きます。
package com.example;
import am.ik.yavi.builder.ValidatorBuilder;
import am.ik.yavi.core.Validator;
public class Car {
private final String manufacturer;
private final String licensePlate;
private final int seatCount;
public static final Validator<Car> validator = ValidatorBuilder.<Car>of()
.constraint(Car::getManufacturer, "manufacturer", c -> c.notNull())
.constraint(Car::getLicensePlate, "licensePlate", c -> c.notNull().greaterThanOrEqual(2).lessThanOrEqual(14))
.constraint(Car::getSeatCount, "seatCount", c -> c.greaterThanOrEqual(2))
.build();
public Car(String manufacturer, String licencePlate, int seatCount) {
this.manufacturer = manufacturer;
this.licensePlate = licencePlate;
this.seatCount = seatCount;
}
public String getManufacturer() {
return manufacturer;
}
public String getLicensePlate() {
return licensePlate;
}
public int getSeatCount() {
return seatCount;
}
}
ValidatorBuilder#constraint は、Car インスタンスの getter の戻り値に適用する制約を宣言するために使います。
manufacturerは null であってはなりませんlicensePlateは null であってはならず、2 文字以上 14 文字以下でなければなりませんseatCountは 2 以上でなければなりません
ヒント
完全なソースコード は GitHub で公開しています。
制約の検証
これらの制約を検証するには、Validator インスタンスを使います。
簡単な単体テストで確かめます。
src/test/java/com/example/CarTest.java を作成し、次のコードを書きます。
package com.example;
import am.ik.yavi.core.ConstraintViolations;
import org.junit.jupiter.api.Test;
import static org.assertj.core.api.Assertions.assertThat;
class CarTest {
@Test
void manufacturerIsNull() {
final Car car = new Car(null, "DD-AB-123", 4);
final ConstraintViolations violations = Car.validator.validate(car);
assertThat(violations.isValid()).isFalse();
assertThat(violations).hasSize(1);
assertThat(violations.get(0).message()).isEqualTo("\"manufacturer\" must not be null");
}
@Test
void licensePlateTooShort() {
final Car car = new Car("Morris", "D", 4);
final ConstraintViolations violations = Car.validator.validate(car);
assertThat(violations.isValid()).isFalse();
assertThat(violations).hasSize(1);
assertThat(violations.get(0).message()).isEqualTo("The size of \"licensePlate\" must be greater than or equal to 2. The given size is 1");
}
@Test
void seatCountTooLow() {
final Car car = new Car("Morris", "DD-AB-123", 1);
final ConstraintViolations violations = Car.validator.validate(car);
assertThat(violations.isValid()).isFalse();
assertThat(violations).hasSize(1);
assertThat(violations.get(0).message()).isEqualTo("\"seatCount\" must be greater than or equal to 2");
}
@Test
void carIsValid() {
final Car car = new Car("Morris", "DD-AB-123", 2);
final ConstraintViolations violations = Car.validator.validate(car);
assertThat(violations.isValid()).isTrue();
assertThat(violations).hasSize(0);
}
}
Validator インスタンスはスレッドセーフであり、何度でも再利用できます。
validate() メソッドは ConstraintViolations インスタンスを返すので、これを反復すればどの検証エラーが起きたかがわかります。
最初の 3 つのテストメソッドは、想定される制約違反を示しています。
manufacturerIsNull()ではmanufacturerのnotNull()制約に違反しますlicensePlateTooShort()ではlicensePlateのgreaterThanOrEqual(int)制約に違反しますseatCountTooLow()ではseatCountのgreaterThanOrEqual(int)制約に違反します
オブジェクトが検証に成功した場合、carIsValid() の例のように、validate() は空の ConstraintViolations を返します。
検証が成功したかどうかは ConstraintViolations.isValid メソッドでも確認できます。
例を実行する
次のプログラムは完全なコンパイル単位です。同じ検証を定義し、不正な Car を検証して見つかった違反を出力します。Run を押すとブラウザでコンパイル・実行され、結果がセルの下に表示されます。
Always Valid モデル
上の例では Car インスタンスを生成してから検証するため、不正な Car が一時的に存在し得ます。
YAVI は、コンストラクタの実行前に引数を検証し、すべての引数が有効なときだけ結果を返すことで、不正なオブジェクトを生成できなくすることもできます。
コンストラクタを private にし、Validated<Car> を返す static ファクトリメソッドを公開します。
package com.example;
import am.ik.yavi.arguments.Arguments3Validator;
import am.ik.yavi.core.Validated;
import am.ik.yavi.validator.Yavi;
public final class Car {
private static final Arguments3Validator<String, String, Integer, Car> validator = Yavi.arguments()
._string("manufacturer", c -> c.notNull())
._string("licensePlate", c -> c.notNull().greaterThanOrEqual(2).lessThanOrEqual(14))
._integer("seatCount", c -> c.greaterThanOrEqual(2))
.apply(Car::new);
private final String manufacturer;
private final String licensePlate;
private final Integer seatCount;
public static Validated<Car> of(String manufacturer, String licensePlate, Integer seatCount) {
return validator.validate(manufacturer, licensePlate, seatCount);
}
private Car(String manufacturer, String licensePlate, Integer seatCount) {
this.manufacturer = manufacturer;
this.licensePlate = licensePlate;
this.seatCount = seatCount;
}
public String manufacturer() {
return manufacturer;
}
public String licensePlate() {
return licensePlate;
}
public Integer seatCount() {
return seatCount;
}
}
Car.of(...) は引数を検証し、結果を Validated に包んで返します。
コンストラクタが private なので、Car は検証結果からしか取得できません。
検証に失敗した場合は、Validated#errors() で違反を調べます。
Validated<Car> validated = Car.of(null, "DD-AB-123", 4);
if (!validated.isValid()) {
ConstraintViolations violations = validated.errors();
// ...
}
record を使い、コンストラクタの中で検証したい場合は、lazy() を使い、コンパクトコンストラクタから validated(...) を呼びます。
package com.example;
import am.ik.yavi.arguments.Arguments3Validator;
import am.ik.yavi.validator.Yavi;
public record Car(String manufacturer, String licensePlate, Integer seatCount) {
private static final Arguments3Validator<String, String, Integer, Car> validator = Yavi.arguments()
._string("manufacturer", c -> c.notNull())
._string("licensePlate", c -> c.notNull().greaterThanOrEqual(2).lessThanOrEqual(14))
._integer("seatCount", c -> c.greaterThanOrEqual(2))
.apply(Car::new);
public Car {
validator.lazy().validated(manufacturer, licensePlate, seatCount);
}
}
lazy() は、マッパーを呼ぶ代わりに Supplier を生成するバリデータを返すので、Car::new を再び呼ばずに検証が実行されます。
lazy() を使わない場合、コンストラクタが実行中にバリデータが Car を生成しようとして再帰し、StackOverflowError になるまで続きます。
不正な引数があると、コンパクトコンストラクタは ConstraintViolationsException を投げます。
その violations() メソッドが違反を返します。
assertThatThrownBy(() -> new Car(null, "DD-AB-123", 4))
.isInstanceOf(ConstraintViolationsException.class)
.satisfies(e -> {
ConstraintViolations violations = ((ConstraintViolationsException) e).violations();
assertThat(violations).hasSize(1);
});
Yavi.arguments() ビルダーと、引数バリデータを定義する他の方法については 引数の検証 を参照してください。