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

This guide covers how to use Hibernate Validator/Bean Validation for:

  • validating the input/output of your REST services;

  • validating the parameters and return values of the methods of your business services.

Prerequisites

要完成这个指南,你需要:

  • 大概15分钟

  • 编辑器

  • 安装JDK 11以上版本并正确配置了 JAVA_HOME

  • Apache Maven 3.8.1+

  • 如果你愿意的话,还可以选择使用Quarkus CLI

  • 如果你想构建原生可执行程序,可以选择安装Mandrel或者GraalVM,并正确配置(或者使用Docker在容器中进行构建)

Architecture

The application built in this guide is quite simple. The user fills a form on a web page. The web page sends the form content to the BookResource as JSON (using Ajax). The BookResource validates the user input and returns the result as JSON.

Architecture

Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.

The solution is located in the validation-quickstart directory.

Creating the Maven project

First, we need a new project. Create a new project with the following command:

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

创建Grade项目,请添加 --gradle 或者 --gradle-kotlin-dsl 参数。

关于如何安装并使用Quarkus CLI的更多信息,请参考Quarkus CLI指南

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

创建Grade项目,请添加 -DbuildTool=gradle 或者 -DbuildTool=gradle-kotlin-dsl 参数。

This command generates a Maven structure importing the RESTEasy Reactive/JAX-RS, Jackson and Hibernate Validator/Bean Validation extensions.

If you already have your Quarkus project configured, you can add the hibernate-validator extension to your project by running the following command in your project base directory:

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

The result of this command is dependent on your build tool:

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

Constraints

In this application, we are going to test an elementary object, but we support complicated constraints and can validate graphs of objects. Create the org.acme.validation.Book class with the following content:

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

Constraints are added on fields, and when an object is validated, the values are checked. The getter and setter methods are also used for JSON mapping.

JSON mapping and validation

Create the following REST resource as 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.

Yes it does not compile, Result is missing, but we will add it very soon.

The method parameter (book) is created from the JSON payload automatically.

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.

Let’s now create the Result class as an inner class:

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

}

The class is very simple and only contains 2 fields and the associated getters and setters. Because we indicate that we produce JSON, the mapping to JSON is made automatically.

REST end point validation

While using the Validator manually might be useful for some advanced usage, if you simply want to validate the parameters or the return value or your REST end point, you can annotate it directly, either with constraints (@NotNull, @Digits…​) or with @Valid (which will cascade the validation to the bean).

Let’s create an end point validating the Book provided in the request:

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

As you can see, we don’t have to manually validate the provided Book anymore as it is automatically validated.

If a validation error is triggered, a violation report is generated and serialized as JSON as our end point produces a JSON output. It can be extracted and manipulated to display a proper error message.

Service method validation

It might not always be handy to have the validation rules declared at the end point level as it could duplicate some business validation.

The best option is then to annotate a method of your business service with your constraints (or in our particular case with @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
    }
}

Calling the service in your rest end point triggers the Book validation automatically:

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

Note that, if you want to push the validation errors to the frontend, you have to catch the exception and push the information yourselves as they will not be automatically pushed to the JSON output.

Keep in mind that you usually don’t want to expose to the public the internals of your services - and especially not the validated value contained in the violation object.

A frontend

Now let’s add the simple web page to interact with our BookResource. Quarkus automatically serves static resources contained in the META-INF/resources directory. In the src/main/resources/META-INF/resources directory, replace the index.html file with the content from this index.html file in it.

Run the application

Now, let’s see our application in action. Run it with:

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

Then, open your browser to http://localhost:8080/:

  1. Enter the book details (valid or invalid)

  2. Click on the Try me…​ buttons to check if your data is valid using one of the methods we presented above.

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

Going further

Hibernate Validator extension and CDI

The Hibernate Validator extension is tightly integrated with CDI.

Configuring the ValidatorFactory

Sometimes, you might need to configure the behavior of the ValidatorFactory, for instance to use a specific ParameterNameProvider.

While the ValidatorFactory is instantiated by Quarkus itself, you can very easily tweak it by declaring replacement beans that will be injected in the configuration.

If you create a bean of the following types in your application, it will automatically be injected into the ValidatorFactory configuration:

  • 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

You don’t have to wire anything.

Obviously, for each listed type, you can declare only one 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.

Constraint validators as beans

You can declare your constraint validators as CDI beans:

@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.

Thus, as demonstrated in our example, you can fully use injection in your constraint validator beans.

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.

Validation and localization

By default, constraint violation messages will be returned in the build system locale.

You can configure this behavior by adding the following configuration in your 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

Validation groups for REST endpoint or service method validation

It’s sometimes necessary to enable different validation constraints for the same class when it’s passed to a different method.

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).

To address this, you can take advantage of validation groups. Validation groups are markers that you put on your constraints in order to enable or disable them at will.

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.

Then add the relevant constraints to Book, assigning the right group to each constraint:

public class Book {

    @Null(groups = ValidationGroups.Post.class)
    @NotNull(groups = ValidationGroups.Put.class)
    public Long id;

    @NotBlank
    public String title;

}

Finally, add a @ConvertGroup annotation next to your @Valid annotation in your validated method.

@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 Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

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