Java Bean Validation Basics – Java Bean验证基础知识

最后修改: 2015年 10月 26日

中文/混合/英文(键盘快捷键：t)

1. Overview

1.概述

In this quick tutorial, we cover the basics of validating a Java bean with the standard framework — JSR 380, also known as Bean Validation 2.0.

在这个快速教程中，我们将介绍用标准框架验证Java Bean的基础知识–JSR 380，也被称为Bean Validation 2.0。

Validating user input is a super common requirement in most applications. And the Java Bean Validation framework has become the de facto standard for handling this kind of logic.

在大多数应用程序中，验证用户输入是一个超级常见的需求。而Java Bean验证框架已经成为处理这种逻辑的事实上的标准。

2. JSR 380

2.JSR 380

JSR 380 is a specification of the Java API for bean validation, part of Jakarta EE and JavaSE. This ensures that the properties of a bean meet specific criteria, using annotations such as @NotNull, @Min, and @Max.

JSR 380是用于Bean验证的Java API规范，是Jakarta EE和JavaSE的一部分。它使用@NotNull、@Min和@Max等注解，确保Bean的属性符合特定标准。

This version requires Java 8 or higher, and takes advantage of new features added in Java 8, such as type annotations and support for new types like Optional and LocalDate.

该版本需要Java 8或更高版本，并利用了Java 8中增加的新功能，如类型注释和对新类型的支持，如Optional和LocalDate。

For full information on the specifications, go ahead and read through the JSR 380.

关于规格的全部信息，请继续阅读JSR 380。

3. Dependencies

3.依赖性

We’re going to use a Maven example to show the required dependencies. But of course, these jars can be added in various ways.

我们将使用一个Maven的例子来展示所需的依赖关系。但当然，这些罐子可以通过各种方式添加。

3.1. Validation API

3.1.验证API

Per the JSR 380 specification, the validation-api dependency contains the standard validation APIs:

根据JSR 380规范，validation-api 依赖包含标准的验证API。

<dependency>
    <groupId>javax.validation</groupId>
    <artifactId>validation-api</artifactId>
    <version>2.0.1.Final</version>
</dependency>

3.2. Validation API Reference Implementation

3.2.验证API参考实现

Hibernate Validator is the reference implementation of the validation API.

Hibernate Validator是验证API的参考实现。。

To use it, we need to add the following dependency:

为了使用它，我们需要添加以下依赖关系。

<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>6.0.13.Final</version>
</dependency>

A quick note: hibernate-validator is entirely separate from the persistence aspects of Hibernate. So, by adding it as a dependency, we’re not adding these persistence aspects into the project.

一个简短的说明： hibernate-validator完全独立于Hibernate的持久性方面。因此，通过将其作为依赖项添加，我们并没有将这些持久性方面添加到项目中。

3.3. Expression Language Dependencies

3.3.表达式语言的依赖性

JSR 380 supports variable interpolation, allowing expressions inside the violation messages.

JSR 380支持变量插值，允许在违规信息内部进行表达。

To parse these expressions, we’ll add the javax.el dependency from GlassFish, that contains  an implementation of the Expression Language specification:

为了解析这些表达式，我们将添加来自GlassFish的javax.el依赖项，它包含表达式语言规范的实现。

<dependency>
    <groupId>org.glassfish</groupId>
    <artifactId>javax.el</artifactId>
    <version>3.0.0</version>
</dependency>

4. Using Validation Annotations

4.使用验证注解

Here, we’ll take a User bean and work on adding some simple validation to it:

在这里，我们将使用一个Userbean，并为其添加一些简单的验证。

import javax.validation.constraints.AssertTrue;
import javax.validation.constraints.Max;
import javax.validation.constraints.Min;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Size;
import javax.validation.constraints.Email;

public class User {

    @NotNull(message = "Name cannot be null")
    private String name;

    @AssertTrue
    private boolean working;

    @Size(min = 10, max = 200, message 
      = "About Me must be between 10 and 200 characters")
    private String aboutMe;

    @Min(value = 18, message = "Age should not be less than 18")
    @Max(value = 150, message = "Age should not be greater than 150")
    private int age;

    @Email(message = "Email should be valid")
    private String email;

    // standard setters and getters 
}

All of the annotations used in the example are standard JSR annotations:

本例中使用的所有注释都是标准的JSR注释。

  • @NotNull validates that the annotated property value is not null.
  • @AssertTrue validates that the annotated property value is true.
  • @Size validates that the annotated property value has a size between the attributes min and max; can be applied to String, Collection, Map, and array properties.
  • @Min validates that the annotated property has a value no smaller than the value attribute.
  • @Max validates that the annotated property has a value no larger than the value attribute.
  • @Email validates that the annotated property is a valid email address.

Some annotations accept additional attributes, but the message attribute is common to all of them. This is the message that will usually be rendered when the value of the respective property fails validation.

有些注解接受额外的属性，但是message属性对所有的注解都是通用的。这是在各自属性的值验证失败时通常会呈现的消息。

And some additional annotations that can be found in the JSR:

还有一些额外的注释，可以在JSR中找到。

  • @NotEmpty validates that the property is not null or empty; can be applied to String, Collection, Map or Array values.
  • @NotBlank can be applied only to text values and validates that the property is not null or whitespace.
  • @Positive and @PositiveOrZero apply to numeric values and validate that they are strictly positive, or positive including 0.
  • @Negative and @NegativeOrZero apply to numeric values and validate that they are strictly negative, or negative including 0.
  • @Past and @PastOrPresent validate that a date value is in the past or the past including the present; can be applied to date types including those added in Java 8.
  • @Future and @FutureOrPresent validate that a date value is in the future, or in the future including the present.

The validation annotations can also be applied to elements of a collection:

验证注释也可以应用于集合的元素。

List<@NotBlank String> preferences;

In this case, any value added to the preferences list will be validated.

在这种情况下，任何添加到偏好列表的值都将被验证。

Also, the specification supports the new Optional type in Java 8:

同时，规范支持Java 8中新的Optional类型。

private LocalDate dateOfBirth;

public Optional<@Past LocalDate> getDateOfBirth() {
    return Optional.of(dateOfBirth);
}

Here, the validation framework will automatically unwrap the LocalDate value and validate it.

在这里，验证框架将自动解开LocalDate值并验证它。

5. Programmatic Validation

5.程序性验证

Some frameworks — such as Spring — have simple ways to trigger the validation process by just using annotations. This is mainly so that we don’t have to interact with the programmatic validation API.

一些框架–比如Spring–有简单的方法可以通过使用注解来触发验证过程。这主要是为了让我们不必与程序化的验证API进行交互。

Now let’s go the manual route and set things up programmatically:

现在让我们走手动路线，以编程方式设置东西。

ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
Validator validator = factory.getValidator();

To validate a bean, we first need a Validator object, which is built using a ValidatorFactory.

为了验证Bean，我们首先需要一个Validator对象，它是使用ValidatorFactory构建的。

5.1. Defining the Bean

5.1.定义 Bean

We’re now going to set up this invalid user — with a null name value:

我们现在要设置这个无效的用户–有一个空的name值。

User user = new User();
user.setWorking(true);
user.setAboutMe("Its all about me!");
user.setAge(50);

5.2. Validate the Bean

5.2.验证 Bean

Now that we have a Validator, we can validate our bean by passing it to the validate method.

现在我们有了一个Validator，我们可以通过将其传递给validate方法来验证我们的bean。

Any violations of the constraints defined in the User object will be returned as a Set:

任何违反User对象中定义的约束的行为将作为Set返回。

Set<ConstraintViolation<User>> violations = validator.validate(user);

By iterating over the violations, we can get all the violation messages using the getMessage method:

通过迭代违规行为，我们可以使用getMessage方法获得所有违规信息。

for (ConstraintViolation<User> violation : violations) {
    log.error(violation.getMessage()); 
}

In our example (ifNameIsNull_nameValidationFails), the set would contain a single ConstraintViolation with the message “Name cannot be null”.

在我们的例子中（ifNameIsNull_nameValidationFails），该集合将包含一个单一的ConstraintViolation，信息是 “名称不能为空”。

6. Conclusion

6.结论

This article focused on a simple pass through the standard Java Validation API. We showed the basics of bean validation using javax.validation annotations and APIs.

本文重点介绍了对标准Java验证API的简单传递。我们展示了使用javax.validation注解和API的bean验证的基础知识。

As usual, an implementation of the concepts in this article and all code snippets can be found over on GitHub.

像往常一样，本文中概念的实现和所有代码片段都可以在GitHub上找到over。