The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

Validation with Hibernate Validator

このガイドでは、以下の場合のHibernate Validator/Bean Validation の使用方法について説明します:

  • REST サービスの入出力の検証

  • ビジネスサービスのメソッドのパラメーターと戻り値の検証

前提条件

このガイドを完成させるには、以下が必要です:

  • 約15分

  • IDE

  • JDK 11+ がインストールされ、 JAVA_HOME が適切に設定されていること

  • Apache Maven 3.8.1+

  • 使用したい場合、 Quarkus CLI

  • ネイティブ実行可能ファイルをビルドしたい場合、MandrelまたはGraalVM(あるいはネイティブなコンテナビルドを使用する場合はDocker)をインストールし、 適切に設定していること

アーキテクチャ

このガイドで構築されたアプリケーションは非常にシンプルです。ユーザーはウェブページ上でフォームを入力します。Web ページはフォームの内容を JSON として BookResource に送信します (Ajax を使用)。 BookResource はユーザーの入力を検証し、 結果 をJSON として返します。

Architecture

ソリューション

次のセクションで紹介する手順に沿って、ステップを踏んでアプリを作成することをお勧めします。ただし、完成した例にそのまま進んでも構いません。

Gitレポジトリをクローンするか git clone https://github.com/quarkusio/quarkus-quickstarts.gitアーカイブ をダウンロードします。

ソリューションは validation-quickstart ディレクトリ にあります。

Mavenプロジェクトの作成

まず、新しいプロジェクトが必要です。以下のコマンドで新規プロジェクトを作成します。

CLI
quarkus create app org.acme:validation-quickstart \
    --extension=resteasy-reactive-jackson,hibernate-validator \
    --no-code
cd validation-quickstart

Gradleプロジェクトを作成するには、 --gradle または --gradle-kotlin-dsl オプションを追加します。

Quarkus CLIのインストール方法については、Quarkus CLIガイドをご参照ください。

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:2.11.1.Final:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=validation-quickstart \
    -Dextensions="resteasy-reactive-jackson,hibernate-validator" \
    -DnoCode
cd validation-quickstart

Gradleプロジェクトを作成するには、 -DbuildTool=gradle または -DbuildTool=gradle-kotlin-dsl オプションを追加します。

このコマンドは、RESTEasy/JAX-RS、Jackson、およびHibernate Validator/Bean ValidationエクステンションをインポートするMavenディレクトリー構造を生成します。

すでにQuarkusプロジェクトが設定されている場合は、プロジェクトのベースディレクトリーで以下のコマンドを実行することで、プロジェクトに hibernate-validator エクステンションを追加することができます。

CLI
quarkus extension add 'hibernate-validator'
Maven
./mvnw quarkus:add-extension -Dextensions="hibernate-validator"
Gradle
./gradlew addExtension --extensions="hibernate-validator"

このコマンドの結果は、お使いのビルドツールに依存します:

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-hibernate-validator</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-hibernate-validator")

制約

今回のアプリケーションでは、基本のオブジェクトをテストすることになりますが、複雑な制約にも対応しており、オブジェクトのグラフを検証することができます。以下の内容で org.acme.validation.Book クラスを作成します。

package org.acme.validation;

import javax.validation.constraints.NotBlank;
import javax.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 javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.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 The Validator instance is injected via CDI.

はい、これはコンパイル出来ません。 Result がありませんが、私たちはすぐに追加します。

メソッドパラメーター( book )は、JSONペイロードから自動的に作成されます。

The method uses the Validator instance to check the payload. It returns a set of violations. If this set is empty, it means the object is valid. In case of failures, the messages are concatenated and sent back to the browser.

それでは、 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としてシリアライズされます。これを抽出して操作することで、適切なエラーメッセージを表示することができます。

サービスメソッドの検証

バリデーションルールをエンドポイントレベルで宣言するのは、必ずしも便利とは限りません。ビジネスバリデーションと重複する可能性があるためです。

最良の選択肢は、ビジネスサービスのメソッドに制約をアノテーションすることです(私たちの場合は @Valid ):

package org.acme.validation;

import javax.enterprise.context.ApplicationScoped;
import javax.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.Quarkusと対話するためのシンプルなウェブページを追加してみましょう。Quarkusは、 META-INF/resources ディレクトリーに含まれる静的リソースを自動的に提供します。 src/main/resources/META-INF/resources ディレクトリーで、 index.html ファイルをこの index.html ファイルの内容で置き換えます。

アプリケーションの実行

では、実際にアプリケーションを見てみましょう。以下のように実行してみてください:

CLI
quarkus dev
Maven
./mvnw quarkus:dev
Gradle
./gradlew --console=plain quarkusDev

そして、ブラウザで http://localhost:8080/ を開いてください:

  1. 書籍の詳細を入力してください(有効または無効)

  2. Try me…​ ボタンをクリックして、上記で紹介した方法のいずれかを使用してデータが有効かどうかを確認してください。

Application

The application can be packaged using:

CLI
quarkus build
Maven
./mvnw clean package
Gradle
./gradlew build

and executed using java -jar target/quarkus-app/quarkus-run.jar.

You can also build the native executable using:

CLI
quarkus build --native
Maven
./mvnw package -Dnative
Gradle
./gradlew build -Dquarkus.package.type=native

さらに詳しく

Hibernate Validator エクステンションと CDI

Hibernate ValidatorエクステンションはCDIと緊密に統合されています。

ValidatorFactoryの設定

時には、 ValidatorFactory の動作を設定する必要があるかもしれません。例えば、特定の ParameterNameProvider を使用するためなどです。

ValidatorFactory は、Quarkus 自体によってインスタンス化されていますが、設定に注入される代わりのBeanを宣言することで、非常に簡単に微調整することができます。

アプリケーションで以下のタイプのBeanを作成すると、自動的に ValidatorFactory の設定に注入されます。

  • javax.validation.ClockProvider

  • javax.validation.ConstraintValidator

  • javax.validation.ConstraintValidatorFactory

  • javax.validation.MessageInterpolator

  • javax.validation.ParameterNameProvider

  • javax.validation.TraversableResolver

  • org.hibernate.validator.spi.properties.GetterPropertySelectionStrategy

  • org.hibernate.validator.spi.nodenameprovider.PropertyNodeNameProvider

  • org.hibernate.validator.spi.scripting.ScriptEvaluatorFactory

何も設定しなくても大丈夫です。

勿論、リストされた各型に対して、宣言することができるのは1つのBeanだけです。

Most of the time, these beans should be declared as @ApplicationScoped.

However, in the case of ConstraintValidators that are dependent of attributes of the constraint annotation (typically when implementing the initialize(A constraintAnnotation) method), use the @Dependent scope to make sure each annotation context has a separate instance of the ConstraintValidator bean.

If customizing the ValidatorFactory through the available configuration properties and the CDI beans above doesn’t cover your requirements, you can customize it further by registering ValidatorFactoryCustomizer beans.

For instance, you could override the built-in validator enforcing the @Email constraint and use MyEmailValidator instead with the following class:

@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);
    }
}

All beans implementing ValidatorFactoryCustomizer are applied, meaning you can have several of them. If you need to enforce some ordering, you can use the usual @javax.annotation.Priority annotation - beans with higher priority are applied first.

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);
    }
}

When initializing a constraint validator of a given type, Quarkus will check if a bean of this type is available and, if so, it will use it instead of instantiating a ConstraintValidator.

このように、例で示したように、制約バリデーターBeanでインジェクションを完全に使用することができます。

The scope you choose for your ConstraintValidator bean is important:

  • If the same instance of the ConstraintValidator bean can be used across the whole application, use the @ApplicationScoped scope.

  • If the ConstraintValidator bean implements the initialize(A constraintAnnotation) method and depends on the state of the constraint annotation, use the @Dependent scope to make sure each annotation context has a separate and properly configured instance of the ConstraintValidator bean.

バリデーションとローカリゼーション

デフォルトでは、制約違反のメッセージはビルドシステムのロケールで返されます。

この動作は、以下の設定を application.properties に追加することで変更することが出来ます:

# The default locale to use
quarkus.default-locale=fr-FR

If you are using RESTEasy Reactive, in the context of a JAX-RS endpoint, Hibernate Validator will automatically resolve the optimal locale to use from the Accept-Language HTTP header, provided the supported locales have been properly specified in the application.properties:

# The list of all the supported locales
quarkus.locales=en-US,es-ES,fr-FR

RESTエンドポイントまたはサービスメソッドのバリデーショングループ

同じクラスが別のメソッドに渡されたときに、異なるバリデーション制約を有効にする必要があることがあります。

For example, a Book may need to have a null identifier when passed to the post method (because the identifier will be generated), but a non-null identifier when passed to the put method (because the method needs the identifier to know what to update).

これに対処するために、バリデーション・グループを利用することができます。バリデーション・グループは、制約を有効または無効にするために制約に付けるマーカーです。

First, define the Post and Put groups, which are just Java interfaces.

public interface ValidationGroups {
    interface Post extends Default { (1)
    }
    interface Put extends Default { (1)
    }
}
1 Make the custom groups extend the Default group. This means that whenever these groups are enabled, the Default group is also enabled. This is useful if you have constraints that you want validated in both the Post and Put method: you can simply use the default group on those constraints, like on the title property below.

次に、関連する制約を 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 Enable the Post group, meaning only constraints assigned to the Post (and Default) groups will be validated for the book parameter of the post method. In this case, it means Book.id must be null and Book.title must not be blank.
2 Enable the Put group, meaning only constraints assigned to the Put (and Default) groups will be validated for the book parameter of the put method. In this case, it means Book.id must not be null and Book.title must not be blank.

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: QUARKUS_HIBERNATE_VALIDATOR_FAIL_FAST

boolean

false

Method validation

タイプ

デフォルト

Define whether overriding methods that override constraints should throw a ConstraintDefinitionException. The default value is false, i.e. do not allow. See Section 4.5.5 of the JSR 380 specification, specifically "In sub types (be it sub classes/interfaces or interface implementations), no parameter constraints may be declared on overridden or implemented methods, nor may parameters be marked for cascaded validation. This would pose a strengthening of preconditions to be fulfilled by the caller."

Environment variable: QUARKUS_HIBERNATE_VALIDATOR_METHOD_VALIDATION_ALLOW_OVERRIDING_PARAMETER_CONSTRAINTS

boolean

false

Define whether parallel methods that define constraints should throw a ConstraintDefinitionException. The default value is false, i.e. do not allow. See Section 4.5.5 of the JSR 380 specification, specifically "If a sub type overrides/implements a method originally defined in several parallel types of the hierarchy (e.g. two interfaces not extending each other, or a class and an interface not implemented by said class), no parameter constraints may be declared for that method at all nor parameters be marked for cascaded validation. This again is to avoid an unexpected strengthening of preconditions to be fulfilled by the caller."

Environment variable: QUARKUS_HIBERNATE_VALIDATOR_METHOD_VALIDATION_ALLOW_PARAMETER_CONSTRAINTS_ON_PARALLEL_METHODS

boolean

false

Define whether more than one constraint on a return value may be marked for cascading validation are allowed. The default value is false, i.e. do not allow. See Section 4.5.5 of the JSR 380 specification, specifically "One must not mark a method return value for cascaded validation more than once in a line of a class hierarchy. In other words, overriding methods on sub types (be it sub classes/interfaces or interface implementations) cannot mark the return value for cascaded validation if the return value has already been marked on the overridden method of the super type or interface."

Environment variable: QUARKUS_HIBERNATE_VALIDATOR_METHOD_VALIDATION_ALLOW_MULTIPLE_CASCADED_VALIDATION_ON_RETURN_VALUES

boolean

false

Expression Language

タイプ

デフォルト

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 message attribute of constraint annotations. 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: QUARKUS_HIBERNATE_VALIDATOR_EXPRESSION_LANGUAGE_CONSTRAINT_EXPRESSION_FEATURE_LEVEL

default, none, variables, bean-properties, bean-methods

bean-properties