Validation with Hibernate Validator

本指南介绍了如何使用 Hibernate Validator/Bean Validation：

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

Unresolved directive in validation.adoc - include::{includes}/prerequisites.adoc[]

Architecture

本指南中构建的应用程序非常简单。用户在网页上填写表单。网页将表单内容作为 JSON（通过 Ajax）发送到 BookResource。BookResource 验证用户信息，并将 result 作为 JSON 返回。

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.

validation guide 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.

克隆 Git 存储库： git clone {quickstarts-clone-url}，或下载 {quickstarts-archive-url}[存档]。

Clone the Git repository: git clone {quickstarts-clone-url}, or download an {quickstarts-archive-url}[archive].

该解决方案位于 validation-quickstart directory 中。

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:

Unresolved directive in validation.adoc - include::{includes}/devtools/create-app.adoc[]

此命令会生成一个 Maven 结构，导入 Quarkus REST（以前为 RESTEasy Reactive）/Jakarta REST、Jackson 和 Hibernate Validator/Bean Validation 扩展。

This command generates a Maven structure importing the Quarkus REST (formerly RESTEasy Reactive)/Jakarta REST, Jackson and Hibernate Validator/Bean Validation extensions.

如果已配置 Quarkus 项目，可通过在自己的项目基本目录中运行以下命令将 hibernate-validator 扩展添加到自己的项目中：

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:

Unresolved directive in validation.adoc - include::{includes}/devtools/extension-add.adoc[]

这会将以下内容添加到构建文件中：

This will add the following to your build file:

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

Constraints

在此应用程序中，我们将测试一个基本对象，但我们支持复杂约束并可以验证对象图。使用以下内容创建 org.acme.validation.Book 类：

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

约束添加到字段中，当对象得到验证时，将检查其值。getter 和 setter 方法也用于 JSON 映射。

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

将以下 REST 资源创建为 org.acme.validation.BookResource：

Create the following REST resource as 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 The Validator instance is injected via CDI.

是的，它不会编译，缺少 Result，但我们很快就会添加。

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

方法参数 (book) 自动从 JSON 负载创建。

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

该方法使用 Validator 实例来检查负载。它返回违规集。如果该集合为空，则表示对象有效。如果失败，消息将被连接起来并发送回浏览器。

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 类为内部类：

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

}

该类非常简单，仅包含 2 个字段及其关联的 getter 和 setter。由于我们指示生成 JSON，因此会自动执行到 JSON 的映射。

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

尽管手动使用 Validator 可能对一些高级用法有用，但如果你只想验证参数或 REST 端点的返回值，你可以直接注释它，用约束 (@NotNull、@Digits…​) 或 @Valid (它会将验证逐步应用到 Bean)。

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

让我们创建一个端点，验证请求中提供的 Book：

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

正如你所见，由于已自动验证提供的 Book，因此不再需要手动验证。

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

如果触发验证错误，将生成违规报告，并以 JSON 格式序列化，因为我们的端点会生成 JSON 输出。可以提取和操作它以显示适当的错误消息。

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.

最佳选择是使用约束（或在我们的特定情况下使用 @Valid）注释业务服务的方法：

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 jakarta.enterprise.context.ApplicationScoped;
import jakarta.validation.Valid;

@ApplicationScoped
public class BookService {

    public void validateBook(@Valid Book book) {
        // your business logic here
    }
}

在 REST 端点中调用服务会自动触发 Book 验证：

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

请注意，如果希望将验证错误推送到前端，则必须手动捕获异常并推送信息，因为它们不会自动推送到 JSON 输出。

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

现在，我们添加一个简单的网页来与我们的 BookResource 进行交互。Quarkus 就会自动提供 META-INF/resources 目录中包含的静态资源。在 src/main/resources/META-INF/resources 目录中，用此 index.html 文件中的内容替换 index.html 文件。

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:

Unresolved directive in validation.adoc - include::{includes}/devtools/dev.adoc[]

然后，在浏览器中打开 [role="bare"][role="bare"]http://localhost:8080/：

Then, open your browser to [role="bare"]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.

validation guide screenshot

可以使用以下命令打包应用程序：

The application can be packaged using:

Unresolved directive in validation.adoc - include::{includes}/devtools/build.adoc[]

并使用 java -jar target/quarkus-app/quarkus-run.jar 执行。

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

您还可以使用以下命令构建本机可执行文件：

You can also build the native executable using:

Unresolved directive in validation.adoc - include::{includes}/devtools/build-native.adoc[]

Going further

Hibernate Validator extension and CDI

Hibernate Validator 扩展与 CDI 紧密集成。

The Hibernate Validator extension is tightly integrated with CDI.

Configuring the ValidatorFactory

有时，你可能需要配置 ValidatorFactory 的行为，例如使用特定的 ParameterNameProvider。

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

虽然 Quarkus 本身实例化 ValidatorFactory，但你可以非常简单地通过声明替换的 Bean 来调整它，这些 Bean 将注入配置。

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.

如果你在应用程序中创建以下类型 Bean，它将自动注入到 ValidatorFactory 配置中：

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

  • 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

你不必连接任何东西。

You don’t have to wire anything.

显然，对于每个已列出类型，你只能声明一个 Bean。

Obviously, for each listed type, you can declare only one bean.

大多数情况下，这些 Bean 应该声明为 @ApplicationScoped。

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

但是，在 ConstraintValidator`s that are dependent of attributes of the constraint annotation (typically when implementing the `initialize(A constraintAnnotation) 方法的情况下，使用 @Dependent 作用域以确保每个注释上下文都有 ConstraintValidator Bean 的单独实例。

However, in the case of ConstraintValidator`s 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.

如果通过可用的配置属性和上述 CDI Bean 定制 ValidatorFactory ，无法满足你的要求，你可以通过注册 ValidatorFactoryCustomizer 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.

例如，你可以覆盖内置的验证器（强制 @Email 约束）并使用以下类改用 MyEmailValidator：

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

所有实现 ValidatorFactoryCustomizer 的 Bean 都适用，这意味着你可以使用多个 Bean。如果你需要强制某些顺序，可以使用通常的 @jakarta.annotation.Priority 注释 —— 具有较高优先级的 Bean 先予以应用。

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 @jakarta.annotation.Priority annotation - beans with higher priority are applied first.

Constraint validators as beans

可将约束验证器声明为 CDI bean：

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

初始化给定类型的约束验证器时，Quarkus 会检查此类型的 bean 是否可用，如果是，它会使用该 bean，而不是实例化 ConstraintValidator 。

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 中完全使用注入。

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

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

Validation and localization

默认情况下，约束违反消息会以构建系统区域设置返回。

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

可在 application.properties 中添加以下配置来配置此行为：

You can configure this behavior by adding the following configuration in your application.properties:

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

如果在 Jakarta REST 端点的上下文中使用的是 Quarkus REST 或 RESTEasy Classic，则 Hibernate Validator 将自动解析最佳区域设置，并从 Accept-Language HTTP 头部中使用它，前提是已在 application.properties 中正确指定支持的区域设置：

If you are using Quarkus REST or RESTEasy Classic, in the context of a Jakarta REST 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

或者，可使用 all 使本机镜像可执行文件包含所有可用的区域设置。但这会显著增加可执行文件的体积。仅包含两个或三个区域设置与包含所有区域设置之间的差异至少为 23 MB。

Alternatively, you can use all to make native-image executable to include all available locales. It inflate the size of the executable substantially though. The difference between including just two or three locales and including all locales is at least 23 MB.

基于 quarkus-smallrye-graphql 扩展程序的 GraphQL 服务也存在类似的机制。

A similar mechanism exists for GraphQL services based on the quarkus-smallrye-graphql extension.

如果此默认机制不够用，并且需要自定义区域设置解析，则可添加其他 org.hibernate.validator.spi.messageinterpolation.LocaleResolver：

If this default mechanism is not sufficient and you need a custom locale resolution, you can add additional `org.hibernate.validator.spi.messageinterpolation.LocaleResolver`s:

  • Any CDI bean implementing org.hibernate.validator.spi.messageinterpolation.LocaleResolver will be taken into account.

  • The LocaleResolver`s are consulted in the order of `@Priority (higher priority goes first).

  • A LocaleResolver may return null if it cannot resolve the locale, it will then be ignored.

  • The first non-null locale returned by a LocaleResolver is the one resolved.

Validation groups for REST endpoint or service method validation

在将类传给不同方法时，有时需要启用相同的验证约束。

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

例如， Book 在传给 post 方法时可能需要 null 标识符（因为该标识符将被生成），但在传给 put 方法时需要一个非 null 标识符（因为该方法需要标识符来了解要更新的内容）。

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.

首先，定义 Post 和 Put 组，它们只是 Java 接口。

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，为每个约束分配正确的组：

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;

}

最后，在您验证的方法中，在您的 @Valid 注释旁边添加一个 @ConvertGroup 注释。

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.

Limitations

META-INF/validation.xml

使用 META-INF/validation.xml 文件配置 ValidatorFactory 在 Quarkus 中受 NOT 支持。

Configuring the ValidatorFactory using a META-INF/validation.xml file is NOT supported in Quarkus.

目前，Hibernate Validator 并未公开 API 从该文件中提取信息，以便我们可以注册反射的适当类。

At the moment, Hibernate Validator does not expose an API to extract the information from this file so that we could register the appropriate classes for reflection.

要配置 ValidatorFactory，请使用公开的配置属性和 CDI 集成。

To configure the ValidatorFactory, use the exposed configuration properties and the CDI integration.

因此，在 Quarkus 中定义约束的唯一方法是通过注释您的类。

Consequently, the only way to define constraints in Quarkus is by annotating your classes.

ValidatorFactory and native executables

Quarkus 提供了一个您可使用配置属性自定义的默认 ValidatorFactory。此 ValidatorFactory 经过精心初始化，以使用 Quarkus 特有的引导程序来支持原生可执行文件。

Quarkus provides a default ValidatorFactory that you can customize using configuration properties. This ValidatorFactory is carefully initialized to support native executables using a bootstrap that is Quarkus-specific.

在原生可执行文件中，不支持自行创建 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. 的错误。

Creating a ValidatorFactory by yourself it not supported in native executables and if you try to do so, you will get an error similar to 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. when running your native executable.

因此，您应始终通过注入 ValidatorFactory 实例或使用 CDI 注入直接注入 Validator 实例，使用 Quarkus 管理的 ValidatorFactory。

Thus why you should always use the Quarkus-managed ValidatorFactory by injecting an instance of ValidatorFactory or directly an instance of Validator using CDI injection.

为了支持使用默认引导程序创建 ValidatorFactory 的一些外部库，当调用 Validation.buildDefaultValidatorFactory() 时，Quarkus 返回由 Quarkus 管理的 ValidatorFactory。

To support some external libraries that are creating a ValidatorFactory using the default bootstrap, Quarkus returns the ValidatorFactory managed by Quarkus when Validation.buildDefaultValidatorFactory() is called.

Hibernate Validator Configuration Reference

Unresolved directive in validation.adoc - include::{generated-dir}/config/quarkus-hibernate-validator.adoc[]