Hibernate Validator 中文操作指南

13. Annotation Processor

你是否曾经无意中做了类似这样的事情？

Have you ever caught yourself by unintentionally doing things like

specifying constraint annotations at unsupported data types (e.g. by annotating a String with @Past)
annotating the setter of a JavaBeans property (instead of the getter method)
annotating static fields/methods with constraint annotations (which is not supported)?

那么 Hibernate Validator 注解处理器正适合你。它通过插入到构建过程中并在错误使用约束注解时引发编译错误，从而帮助防止此类错误。

Then the Hibernate Validator Annotation Processor is the right thing for you. It helps preventing such mistakes by plugging into the build process and raising compilation errors whenever constraint annotations are incorrectly used.

你可以在 Sourceforge 的分发包中或在通常的 Maven 存储库（例如 Maven Central）中，使用 GAV org.hibernate.validator:hibernate-validator-annotation-processor:8.0.1.Final 在 Hibernate Validator Annotation Processor 中找到它。

You can find the Hibernate Validator Annotation Processor as part of the distribution bundle on Sourceforge or in the usual Maven repositories such as Maven Central under the GAV org.hibernate.validator:hibernate-validator-annotation-processor:8.0.1.Final.

13.1. Prerequisites

Hibernate 验证器注释处理器基于 JSR 269 定义的“可插拔注释处理 API”，它属于 Java 平台的一部分。

The Hibernate Validator Annotation Processor is based on the "Pluggable Annotation Processing API" as defined by JSR 269 which is part of the Java Platform.

13.2. Features

截至 Hibernate Validator 8.0.1.Final，Hibernate Validator 注解处理器检查：

As of Hibernate Validator 8.0.1.Final the Hibernate Validator Annotation Processor checks that:

constraint annotations are allowed for the type of the annotated element
only non-static fields or methods are annotated with constraint annotations
only non-primitive fields or methods are annotated with @Valid
only such methods are annotated with constraint annotations which are valid JavaBeans getter methods (optionally, see below)
only such annotation types are annotated with constraint annotations which are constraint annotations themselves
definition of dynamic default group sequence with @GroupSequenceProvider is valid
annotation parameter values are meaningful and valid
method parameter constraints in inheritance hierarchies respect the inheritance rules
method return value constraints in inheritance hierarchies respect the inheritance rules

13.3. Options

可以使用以下 processor options 控制 Hibernate 验证器注释处理器的行为：

The behavior of the Hibernate Validator Annotation Processor can be controlled using the following processor options:

diagnosticKind

控制约束问题报告的方式。必须是枚举 javax.tools.Diagnostic.Kind 中某个值字符串表示，例如 WARNING 。如果 AP 检测到约束问题，则 ERROR 值将导致编译停止。默认为 ERROR 。

Controls how constraint problems are reported. Must be the string representation of one of the values from the enum javax.tools.Diagnostic.Kind, e.g. WARNING. A value of ERROR will cause compilation to halt whenever the AP detects a constraint problem. Defaults to ERROR.

methodConstraintsSupported

控制方法中是否允许任何类型的约束。使用 Hibernate Validator 支持的方法级别约束时，必须将其设置为 true 。可以将其设置为 false ，以仅允许 Jakarta Bean Validation API 定义的 JavaBeans getter 方法中存在约束。默认为 true 。

Controls whether constraints are allowed at methods of any kind. Must be set to true when working with method level constraints as supported by Hibernate Validator. Can be set to false to allow constraints only at JavaBeans getter methods as defined by the Jakarta Bean Validation API. Defaults to true.

verbose

控制是否显示详细处理信息，此功能可用于调试。必须为 true 或 false 。默认为 false 。

Controls whether detailed processing information shall be displayed or not, useful for debugging purposes. Must be either true or false. Defaults to false.

13.4. Using the Annotation Processor

本部分详细说明了如何将 Hibernate Validator 注解处理器集成到命令行构建（Maven、Ant、javac）以及基于 IDE 的构建（Eclipse、IntelliJ IDEA、NetBeans）中。

This section shows in detail how to integrate the Hibernate Validator Annotation Processor into command line builds (Maven, Ant, javac) as well as IDE-based builds (Eclipse, IntelliJ IDEA, NetBeans).

13.4.1. Command line builds

13.4.1.1. Maven

要使用 Maven 和 Hibernate Validator 注解处理器，请通过 annotationProcessorPaths 选项进行设置，如下所示：

For using the Hibernate Validator annotation processor with Maven, set it up via the annotationProcessorPaths option like this:

示例 13.1：在 Maven 中使用 HV 注释处理器

. Example 13.1: Using the HV Annotation Processor with Maven

<project>
    [...]
    <build>
        [...]
        <plugins>
            [...]
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.6.1</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                    <annotationProcessorPaths>
                        <path>
                            <groupId>org.hibernate.validator</groupId>
                            <artifactId>hibernate-validator-annotation-processor</artifactId>
                            <version>8.0.1.Final</version>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>
            [...]
        </plugins>
        [...]
    </build>
    [...]
</project>

13.4.1.2. Gradle

使用 Gradle 时，足以将注释处理器引用为 annotationProcessor 依赖项。

When using Gradle it is enough to reference the annotation processor as an annotationProcessor dependency.

示例 13.2：在 Gradle 中使用注释处理器

. Example 13.2: Using the annotation processor with Gradle

dependencies {
    annotationProcessor group: 'org.hibernate.validator', name: 'hibernate-validator-annotation-processor', version: '8.0.1.Final'

    // any other dependencies ...
}

13.4.1.3. Apache Ant

类似于直接使用 javac，可以在调用 javac task 时将注释处理器添加为编译器参数，以用于 Apache Ant：

Similar to directly working with javac, the annotation processor can be added as as compiler argument when invoking the javac task for Apache Ant:

示例 13.3：在 Ant 中使用注释处理器

. Example 13.3: Using the annotation processor with Ant

<javac srcdir="src/main"
       destdir="build/classes"
       classpath="/path/to/validation-api-3.0.2.jar">
       <compilerarg value="-processorpath" />
       <compilerarg value="/path/to/hibernate-validator-annotation-processor-8.0.1.Final.jar"/>
</javac>

13.4.1.4. javac

使用 javac 在命令行上编译时，使用“processorpath”选项指定 JAR hibernate-validator-annotation-processor-8.0.1.Final.jar，如下面的清单所示。编译器将自动检测到该处理器并在编译期间调用它。

When compiling on the command line using javac, specify the JAR hibernate-validator-annotation-processor-8.0.1.Final.jar using the "processorpath" option as shown in the following listing. The processor will be detected automatically by the compiler and invoked during compilation.

示例 13.4：在 javac 中使用注释处理器

. Example 13.4: Using the annotation processor with javac

13.4.2. IDE builds

13.4.2.1. Eclipse

只要安装了 M2E Eclipse plug-in，为按上述方式配置的 Maven 项目自动设置注释处理器。

The annotation processor will automatically be set up for Maven projects configured as described above, provided you have the M2E Eclipse plug-in installed.

对于普通 Eclipse 项目，请遵循以下步骤设置注解处理器：

For plain Eclipse projects follow these steps to set up the annotation processor:

Right-click your project, choose "Properties"
Go to "Java Compiler" and make sure, that "Compiler compliance level" is set to "1.8". Otherwise the processor won’t be activated
Go to "Java Compiler - Annotation Processing" and choose "Enable annotation processing"
Go to "Java Compiler - Annotation Processing - Factory Path" and add the JAR hibernate-validator-annotation-processor-8.0.1.Final.jar
Confirm the workspace rebuild

您现在应该在编辑器中看到任何注释问题，这些注释问题显示为普通错误标记，并且在“问题”视图中显示：

You now should see any annotation problems as regular error markers within the editor and in the "Problem" view:

13.4.2.2. IntelliJ IDEA

在 IntelliJ IDEA （版本 9 及更高版本）中使用注释处理器时，必须执行以下步骤：

The following steps must be followed to use the annotation processor within IntelliJ IDEA (version 9 and above):

Go to "File", then "Settings",
Expand the node "Compiler", then "Annotation Processors"
Choose "Enable annotation processing" and enter the following as "Processor path": /path/to/hibernate-validator-annotation-processor-8.0.1.Final.jar
Add the processor’s fully qualified name org.hibernate.validator.ap.ConstraintValidationProcessor to the "Annotation Processors" list
If applicable add you module to the "Processed Modules" list

然后再编译您的项目，然后应显示任何错误的约束注释：

Rebuilding your project then should show any erroneous constraint annotations:

13.4.2.3. NetBeans

NetBeans IDE 支持在 IDE 构建中使用注释处理器。为此，请执行以下操作：

The NetBeans IDE supports using annotation processors within the IDE build. To do so, do the following:

Right-click your project, choose "Properties"
Go to "Libraries", tab "Processor", and add the JAR hibernate-validator-annotation-processor-8.0.1.Final.jar
Go to "Build - Compiling", select "Enable Annotation Processing" and "Enable Annotation Processing in Editor". Add the annotation processor by specifying its fully qualified name org.hibernate.validator.ap.ConstraintValidationProcessor

然后，任何约束注释问题都将直接在编辑器中标记：

Any constraint annotation problems will then be marked directly within the editor:

13.5. Known issues

截至 2017 年 7 月，存在以下已知问题：

The following known issues exist as of July 2017:

Container element constraints are not supported for now.
Constraints applied to a container but in reality applied to the container elements (be it via the Unwrapping.Unwrap payload or via a value extractor marked with @UnwrapByDefault) are not supported correctly.
HV-308: Additional validators registered for a constraint using XML are not evaluated by the annotation processor.
Sometimes custom constraints can’t be properly evaluated when using the processor within Eclipse. Cleaning the project can help in these situations. This seems to be an issue with the Eclipse JSR 269 API implementation, but further investigation is required here.
When using the processor within Eclipse, the check of dynamic default group sequence definitions doesn’t work. After further investigation, it seems to be an issue with the Eclipse JSR 269 API implementation.