Hibernate Validatorによるバリデーション
このガイドでは、以下の場合のHibernate Validator/Bean Validation の使用方法について説明します:
-
REST サービスの入出力の検証
-
ビジネスサービスのメソッドのパラメーターと戻り値の検証
前提条件
このガイドを完成させるには、以下が必要です:
-
約15分
-
IDE
-
JDK 17+がインストールされ、
JAVA_HOME
が適切に設定されていること -
Apache Maven 3.9.9
-
使用したい場合は、 Quarkus CLI
-
ネイティブ実行可能ファイルをビルドしたい場合、MandrelまたはGraalVM(あるいはネイティブなコンテナビルドを使用する場合はDocker)をインストールし、 適切に設定していること
アーキテクチャ
このガイドで構築されたアプリケーションは非常にシンプルです。ユーザーはウェブページ上でフォームを入力します。Web ページはフォームの内容を JSON として BookResource
に送信します (Ajax を使用)。 BookResource
はユーザーの入力を検証し、 結果 をJSON として返します。
ソリューション
次の章で紹介する手順に沿って、ステップを踏んでアプリを作成することをお勧めします。ただし、完成した例にそのまま進んでも構いません。
Gitレポジトリ git clone https://github.com/quarkusio/quarkus-quickstarts.git
をクローンするか、 アーカイブ をダウンロードします。
ソリューションは validation-quickstart
ディレクトリ にあります。
Mavenプロジェクトの作成
まず、新しいプロジェクトが必要です。以下のコマンドで新規プロジェクトを作成します。
Windowsユーザーの場合:
-
cmdを使用する場合、(バックスラッシュ
\
を使用せず、すべてを同じ行に書かないでください)。 -
Powershellを使用する場合は、
-D
パラメータを二重引用符で囲んでください。例:"-DprojectArtifactId=validation-quickstart"
このコマンドは、Quarkus REST (旧RESTEasy Reactive)/Jakarta REST、Jackson、およびHibernate Validator/Bean ValidationエクステンションをインポートするMaven構造を生成します。
すでにQuarkusプロジェクトが設定されている場合は、プロジェクトのベースディレクトリーで以下のコマンドを実行することで、プロジェクトに hibernate-validator
エクステンションを追加することができます。
quarkus extension add hibernate-validator
./mvnw quarkus:add-extension -Dextensions='hibernate-validator'
./gradlew addExtension --extensions='hibernate-validator'
これにより、pom.xml
に以下が追加されます:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-hibernate-validator</artifactId>
</dependency>
implementation("io.quarkus:quarkus-hibernate-validator")
制約
今回のアプリケーションでは、基本のオブジェクトをテストすることになりますが、複雑な制約にも対応しており、オブジェクトのグラフを検証することができます。以下の内容で org.acme.validation.Book
クラスを作成します。
package org.acme.validation;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Min;
public class Book {
@NotBlank(message="Title may not be blank")
public String title;
@NotBlank(message="Author may not be blank")
public String author;
@Min(message="Author has been very lazy", value=1)
public double pages;
}
フィールドに制約を加え、オブジェクトが検証されると値がチェックされます。ゲッターメソッドとセッターメソッドはJSONマッピングにも使われています。
JSONのマッピングとバリデーション
以下のRESTリソースを org.acme.validation.BookResource
として作成します。
package org.acme.validation;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
@Path("/books")
public class BookResource {
@Inject
Validator validator; (1)
@Path("/manual-validation")
@POST
public Result tryMeManualValidation(Book book) {
Set<ConstraintViolation<Book>> violations = validator.validate(book);
if (violations.isEmpty()) {
return new Result("Book is valid! It was validated by manual validation.");
} else {
return new Result(violations);
}
}
}
1 | Validator インスタンスはCDIで注入されます。 |
はい、これはコンパイル出来ません。 Result
がありませんが、私たちはすぐに追加します。
メソッドパラメーター( book
)は、JSONペイロードから自動的に作成されます。
このメソッドは、 Validator
インスタンスを使用してペイロードをチェックします。このメソッドは、違反のセットを返却します。このセットが空であれば、オブジェクトが有効であることを意味します。失敗した場合は、メッセージが連結され、ブラウザに送り返されます。
それでは、 Result
クラスをインナークラスとして作成してみましょう。
public static class Result {
Result(String message) {
this.success = true;
this.message = message;
}
Result(Set<? extends ConstraintViolation<?>> violations) {
this.success = false;
this.message = violations.stream()
.map(cv -> cv.getMessage())
.collect(Collectors.joining(", "));
}
private String message;
private boolean success;
public String getMessage() {
return message;
}
public boolean isSuccess() {
return success;
}
}
このクラスは非常にシンプルで、2つのフィールドとそれに関連するゲッターとセッターだけが含まれています。JSONを生成することを示しているので、JSONへのマッピングは自動的に行われます。
RESTエンドポイントバリデーション
Validator
を手動で使用することは、高度な使用法には便利かもしれませんが、単にパラメーターや戻り値、RESTのエンドポイントを検証したい場合は、制約( @NotNull
, @Digits
…)や @Valid
(Beanに検証をカスケードします)を使用して直接アノテーションすることができます。
リクエストで提供された Book
を検証するエンドポイントを作成してみましょう。
@Path("/end-point-method-validation")
@POST
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public Result tryMeEndPointMethodValidation(@Valid Book book) {
return new Result("Book is valid! It was validated by end point method validation.");
}
ご覧のように、提供された Book
は自動的に検証されるので、もう手動で検証する必要はありません。
検証エラーが発生した場合、違反レポートが生成され、そしてエンドポイントがJSON出力を生成することによってJSONとしてシリアライズされます。これを抽出して操作することで、適切なエラーメッセージを表示することができます。
An example of such a report could be:
{
"title": "Constraint Violation",
"status": 400,
"violations": [
{
"field": "tryMeEndPointMethodValidation.book.title",
"message": "Title cannot be blank"
}
]
}
This response is produced by Quarkus via a builtin implementation of jakarta.ws.rs.ext.ExceptionMapper
. If the application code needs to handle ValidationException
in some custom way,
it can provide an implementation of jakarta.ws.rs.ext.ExceptionMapper
like so:
import jakarta.validation.ValidationException;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.ext.ExceptionMapper;
import jakarta.ws.rs.ext.Provider;
@Provider
public class ResteasyReactiveViolationExceptionMapper implements ExceptionMapper<ValidationException> {
@Override
public Response toResponse(ValidationException exception) {
// TODO: implement
}
}
サービスメソッドの検証
バリデーションルールをエンドポイントレベルで宣言するのは、必ずしも便利とは限りません。ビジネスバリデーションと重複する可能性があるためです。
最良の選択肢は、ビジネスサービスのメソッドに制約をアノテーションすることです(私たちの場合は @Valid
):
package org.acme.validation;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.validation.Valid;
@ApplicationScoped
public class BookService {
public void validateBook(@Valid Book book) {
// your business logic here
}
}
RESTエンドポイントでサービスを呼び出すと、自動的に Book
の検証が行われます。
@Inject BookService bookService;
@Path("/service-method-validation")
@POST
public Result tryMeServiceMethodValidation(Book book) {
try {
bookService.validateBook(book);
return new Result("Book is valid! It was validated by service method validation.");
} catch (ConstraintViolationException e) {
return new Result(e.getConstraintViolations());
}
}
検証エラーをフロントエンドにプッシュしたい場合は、例外をキャッチして自分で情報をプッシュしなければなりません。
通常、サービスの内部、特に違反オブジェクトに含まれる検証された値を公開したくないことに留意してください。
フロントエンド
それでは、 BookResource
と対話するための簡単なWebページを追加してみましょう。
Quarkusは、 META-INF/resources
ディレクトリに含まれる静的リソースを自動的に提供します。
src/main/resources/META-INF/resources
ディレクトリで、 index.html
ファイルをこの index.html ファイルの内容で置き換えます。
アプリケーションの実行
では、実際にアプリケーションを見てみましょう。以下のように実行してみてください:
quarkus dev
./mvnw quarkus:dev
./gradlew --console=plain quarkusDev
そして、ブラウザで http://localhost:8080/ を開いてください:
-
書籍の詳細を入力してください(有効または無効)
-
Try me… ボタンをクリックして、上記で紹介した方法のいずれかを使用してデータが有効かどうかを確認してください。
アプリケーションは以下でパッケージ化することができます:
quarkus build
./mvnw install
./gradlew build
そして次のように実行します java -jar target/quarkus-app/quarkus-run.jar
。
ネイティブ実行可能ファイルも次のようにビルドすることもできます:
quarkus build --native
./mvnw install -Dnative
./gradlew build -Dquarkus.native.enabled=true
さらに詳しく
Hibernate Validator エクステンションと CDI
Hibernate ValidatorエクステンションはCDIと緊密に統合されています。
ValidatorFactoryの設定
時には、 ValidatorFactory
の動作を設定する必要があるかもしれません。例えば、特定の ParameterNameProvider
を使用するためなどです。
ValidatorFactory
は、Quarkus 自体によってインスタンス化されていますが、設定に注入される代わりのBeanを宣言することで、非常に簡単に微調整することができます。
アプリケーションで以下のタイプのBeanを作成すると、自動的に ValidatorFactory
の設定に注入されます。
-
jakarta.validation.ClockProvider
-
jakarta.validation.ConstraintValidator
-
jakarta.validation.ConstraintValidatorFactory
-
jakarta.validation.MessageInterpolator
-
jakarta.validation.ParameterNameProvider
-
jakarta.validation.TraversableResolver
-
org.hibernate.validator.spi.properties.GetterPropertySelectionStrategy
-
org.hibernate.validator.spi.nodenameprovider.PropertyNodeNameProvider
-
org.hibernate.validator.spi.scripting.ScriptEvaluatorFactory
何も設定しなくても大丈夫です。
勿論、リストされた各型に対して、宣言することができるのは1つのBeanだけです。 ほとんどの場合、これらのBeanは ただし、制約アノテーションの属性に依存する |
利用可能な設定プロパティと上記の CDI Bean を介して ValidatorFactory
をカスタマイズしても要件が満たされない場合は、ValidatorFactoryCustomizer
Bean を登録することでさらにカスタマイズできます。
たとえば、@Email
制約を強制する組み込みバリデーターをオーバーライドし、代わりに次のクラスで MyEmailValidator
を使用できます。
@ApplicationScoped
public class MyEmailValidatorFactoryCustomizer implements ValidatorFactoryCustomizer {
@Override
public void customize(BaseHibernateValidatorConfiguration<?> configuration) {
ConstraintMapping constraintMapping = configuration.createConstraintMapping();
constraintMapping
.constraintDefinition(Email.class)
.includeExistingValidators(false)
.validatedBy(MyEmailValidator.class);
configuration.addMapping(constraintMapping);
}
}
ValidatorFactoryCustomizer
を実装するすべての Bean が適用されます。つまり、複数の Bean を持つことができます。もし、何らかの順序付けが必要な場合は、通常の @jakarta.annotation.Priority
アノテーションを使用することができます - より高い優先順位の Bean が最初に適用されます。
Beanとしての制約バリデーター
制約バリデーターをCDI Beanとして宣言することができます。
@ApplicationScoped
public class MyConstraintValidator implements ConstraintValidator<MyConstraint, String> {
@Inject
MyService service;
@Override
public boolean isValid(String value, ConstraintValidatorContext context) {
if (value == null) {
return true;
}
return service.validate(value);
}
}
指定された型の制約バリデーターを初期化する際、Quarkusはこの型のBeanが利用可能かどうかをチェックし、利用可能な場合は ConstraintValidator
のインスタンスを作成する代わりにそれを使用します。
このように、例で示したように、制約バリデーターBeanでインジェクションを完全に使用することができます。
|
バリデーションとローカリゼーション
デフォルトでは、制約違反のメッセージはビルドシステムのロケールで返されます。
この動作は、以下の設定を application.properties
に追加することで変更することが出来ます:
# The default locale to use
quarkus.default-locale=fr-FR
Jakarta REST エンドポイントのコンテキストでQuarkus REST または RESTEasy Classic を使用している場合、
サポートされているロケールが application.properties
で適切に指定されていれば、Hibernate Validator は Accept-Language
HTTP ヘッダーから使用する最適なロケールを自動的に解決します:
# The list of all the supported locales
quarkus.locales=en-US,es-ES,fr-FR
あるいは、 all
を使って、利用可能なすべてのロケールを含むネイティブイメージの実行可能ファイルを作成することもできます。ただし、実行可能ファイルのサイズが大幅に膨れ上がります。
2つか3つのロケールを含めるのと、すべてのロケールを含めるのとでは、少なくとも23MBの差があります。
同様の仕組みは、 quarkus-smallrye-graphql
エクステンションに基づく GraphQL サービスにも存在します。
このデフォルトのメカニズムでは不十分で、カスタムのロケール解決が必要な場合は、 org.hibernate.validator.spi.messageinterpolation.LocaleResolver
を追加することができます。
-
org.hibernate.validator.spi.messageinterpolation.LocaleResolver
を実装しているCDIビーンはすべて考慮されます。 -
LocaleResolver
は、@Priority
(優先順位の高いものから)順に参照されます。 -
LocaleResolver
は、ロケールを解決できない場合は null を返すかもしれない。その場合は無視される。 -
LocaleResolver
が最初に返した非 NULL ロケールに解決されます。
RESTエンドポイントまたはサービスメソッドのバリデーショングループ
同じクラスが異なるメソッドに渡されたときに、異なる検証制約を有効にする必要があることがあります。
例えば、 Book
は、 post
メソッドに渡されるときには null
識別子が必要ですが(識別子が生成されるため)、 put
メソッドに渡されるときには null
以外の識別子が必要になる場合があります(メソッドが更新内容を知るために識別子を必要とするため)。
これに対処するために、バリデーション・グループを利用することができます。バリデーション・グループは、制約を有効または無効にするために制約に付けるマーカーです。
まず、 Post
と Put
グループを定義します。これらは単なるJavaインターフェースです。
public interface ValidationGroups {
interface Post extends Default { (1)
}
interface Put extends Default { (1)
}
}
1 | カスタムグループが Default グループを拡張するようにします。これは、これらのグループが有効なときはいつでも、 Default グループも有効であることを意味します。これは、 Post と Put の両方のメソッドで検証したい制約がある場合に便利です。以下の title プロパティのように、これらの制約に単純にデフォルトグループを使用することができます。 |
次に、関連する制約を Book
に追加し、各制約に適切なグループを割り当てます。
public class Book {
@Null(groups = ValidationGroups.Post.class)
@NotNull(groups = ValidationGroups.Put.class)
public Long id;
@NotBlank
public String title;
}
最後に、検証済みメソッドの @Valid
アノテーションの横に @ConvertGroup
アノテーションを追加します。
@Path("/")
@POST
@Consumes(MediaType.APPLICATION_JSON)
public void post(@Valid @ConvertGroup(to = ValidationGroups.Post.class) Book book) { (1)
// ...
}
@Path("/")
@PUT
@Consumes(MediaType.APPLICATION_JSON)
public void put(@Valid @ConvertGroup(to = ValidationGroups.Put.class) Book book) { (2)
// ...
}
1 | Post グループを有効にすると、 Post (および Default ) グループに割り当てられた制約のみが post メソッドの book パラメータに対して検証されることを意味します。この場合、 Book.id は null でなければならず、 Book.title は空白であってはならないことを意味します。 |
2 | Put グループを有効にすると、 Put (および Default ) グループに割り当てられた制約のみが put メソッドの book パラメータに対して検証されることを意味します。この場合、 Book.id は null であってはならず、 Book.title は空白であってはならないことを意味します。 |
制約事項
META-INF/validation.xml
Quarkusでは、 META-INF/validation.xml
ファイルを使用した ValidatorFactory
の設定はサポートされて いません 。
現時点では、Hibernate Validatorはリフレクションのために適切なクラスを登録する為にこのファイルから情報を抽出するAPIを公開していません。
ValidatorFactory
を設定するには、公開された設定プロパティとCDI統合を使用します。
したがって、Quarkusで制約を定義する唯一の方法は、クラスにアノテーションを付けることです。
ValidatorFactoryとネイティブ実行可能ファイル
Quarkusは、設定プロパティを使用してカスタマイズ可能なデフォルトの ValidatorFactory
を提供します。この ValidatorFactory
は、Quarkus 固有のブートストラップを使用してネイティブ実行ファイルをサポートするように慎重に初期化されています。
ValidatorFactory
を自分で作成することは、ネイティブ実行ファイルではサポートされていません。作成しようとすると、ネイティブ実行ファイルを実行する際に jakarta.validation.NoProviderFoundException: Unable to create a Configuration, because no Jakarta Bean Validation provider could be found. Add a provider like Hibernate Validator (RI) to your classpath.
のようなエラーが発生します。
これが、ValidatorFactory
のインスタンスを注入するか、CDIインジェクションを使用して Validator
のインスタンスを直接注入することで、Quarkusが管理する ValidatorFactory
を常に使用しなければならない理由です。
デフォルトのブートストラップを使用して ValidatorFactory
を作成している一部の外部ライブラリをサポートするために、Quarkus は Validation.buildDefaultValidatorFactory()
が呼び出されたときに Quarkus によって管理されている ValidatorFactory
を返却します。
Hibernate Validator設定リファレンス
ビルド時に固定される構成プロパティ - 他のすべての構成プロパティは実行時にオーバーライド可能
Configuration property |
型 |
デフォルト |
---|---|---|
Enable the fail fast mode. When fail fast is enabled the validation will stop on the first constraint violation detected. Environment variable: Show more |
boolean |
|
型 |
デフォルト |
|
Define whether overriding methods that override constraints should throw a See Section 4.5.5 of the JSR 380 specification, specifically
Environment variable: Show more |
boolean |
|
Define whether parallel methods that define constraints should throw a See Section 4.5.5 of the JSR 380 specification, specifically
Environment variable: Show more |
boolean |
|
Define whether more than one constraint on a return value may be marked for cascading validation are allowed. The default value is See Section 4.5.5 of the JSR 380 specification, specifically
Environment variable: Show more |
boolean |
|
型 |
デフォルト |
|
Configure the Expression Language feature level for constraints, allowing the selection of Expression Language features available for message interpolation. This property only affects the EL feature level of "static" constraint violation messages set through the In particular, it doesn’t affect the default EL feature level for custom violations created programmatically in validator implementations. The feature level for those can only be configured directly in the validator implementation. Environment variable: Show more |
|
|