65.2. 使用 Bean 验证开发服务

65.2.1. 为 Service Bean 标注

概述

使用 bean 验证开发服务的第一个步骤是将相关验证注解应用到代表服务的 Java 类或接口。验证注解可让您应用约束来将限制应用到方法参数、返回值和类字段,然后在运行时检查该服务。

验证简单的输入参数

要验证服务方法的参数-其中参数简单 Java 类型,您可以应用 bean 验证 API 中的任何约束注解(javax.validation.constraints 软件包)。例如,以下代码示例测试了 nullness(@NotNull 注释)、id 字符串与 \\d+ 正则表达式匹配(@Pattern 注释),以及 名称 字符串在范围 1 到 50 的长度:

import javax.validation.constraints.NotNull;
import javax.validation.constraints.Pattern;
import javax.validation.constraints.Size;
...
@POST
@Path("/books")
public Response addBook(
        @NotNull @Pattern(regexp = "\\d+") @FormParam("id") String id,
        @NotNull @Size(min = 1, max = 50) @FormParam("name") String name) {
    // do some work
    return Response.created().build();
}

验证复杂的输入参数

要验证复杂的输入参数(对象实例),请将 @Valid 注释应用到参数,如下例所示:

import javax.validation.Valid;
...
@POST
@Path("/books")
public Response addBook( @Valid Book book ) {
    // do some work
    return Response.created().build();
}

@Valid 注释不自行指定任何限制。使用 @Valid 注解 Book 参数时,您可以有效地告知验证引擎在 Book 类的定义中(递归)查找验证限制。在本例中,Book 类定义了在其 idname 字段上的验证限制,如下所示:

import javax.validation.constraints.NotNull;
import javax.validation.constraints.Pattern;
import javax.validation.constraints.Size;
...
public class Book {
    @NotNull @Pattern(regexp = "\\d+") private String id;
    @NotNull @Size(min = 1, max = 50) private String name;

    // ...
}

验证返回值(非Response)

要将验证应用到常规方法返回值(非Response),请在方法签名前添加注解。例如,要测试 nullness(@NotNull 注释)的返回值,并以递归方式测试验证约束(@Valid 注释),请注解 getBook 方法,如下所示:

import javax.validation.constraints.NotNull;
import javax.validation.Valid;
...
@GET
@Path("/books/{bookId}")
@Override
@NotNull @Valid
public Book getBook(@PathParam("bookId") String id) {
    return new Book( id );
}

验证返回值(Response)

要将验证应用到返回 javax.ws.rs.core.Response 对象的方法,您可以使用与非接收情况下相同的注解。例如:

import javax.validation.constraints.NotNull;
import javax.validation.Valid;
import javax.ws.rs.core.Response;
...
@GET
@Path("/books/{bookId}")
@Valid @NotNull
public Response getBookResponse(@PathParam("bookId") String id) {
    return Response.ok( new Book( id ) ).build();
}

65.2.2. 标准注解

Bean 验证限制

表 65.1 “Bean 验证的标准注释” 显示 Bean Validation 规范中定义的标准注释,它们可用于定义字段和方法返回值和参数(标准注解没有可以在类级别上应用)。

表 65.1. Bean 验证的标准注释

注解适用于描述

@AssertFalse

布尔值,布尔值

检查注解的元素是否为 false

@AssertTrue

布尔值,布尔值

检查注解的元素是否为 true

@DecimalMax(value=, inclusive=)

BigDecimal,BigInteger,CharSequence, byte, short, int ,int,long 和 primitive type wrappers

inclusive=false 时,检查注解的值是否小于指定的最大值。否则,检查该值是否小于或等于指定的最大值。value 参数指定最大为 BigDecimal 字符串格式。

@DecimalMin(value=, inclusive=)

BigDecimal,BigInteger,CharSequence, byte, short, int ,int,long 和 primitive type wrappers

inclusive=false 时,检查注解的值是否大于指定最小值。否则,检查值是否大于或等于指定最小值。value 参数指定最小值,采用 BigDecimal 字符串格式。

@Digits(integer=, fraction=)

BigDecimal,BigInteger,CharSequence, byte, short, int ,int,long 和 primitive type wrappers

检查注释的值是否为具有最多 整数 数和 部分 部分数字的数字。

@Future

java.util.Date, java.util.Calendar

检查注解日期是否在将来。

@Max(value=)

BigDecimal,BigInteger,CharSequence, byte, short, int ,int,long 和 primitive type wrappers

检查注解的值是否小于或等于指定的最大值。

@Min(value=)

BigDecimal,BigInteger,CharSequence, byte, short, int ,int,long 和 primitive type wrappers

检查注解的值是否大于或等于指定最小值。

@NotNull

任何类型

检查注释的值不是 null

@Null

任何类型

检查注释的值是否为 null

@Past

java.util.Date, java.util.Calendar

检查注解的日期是否位于过去。

@Pattern(regex=, flag=)

CharSequence

检查注释的字符串 是否与 正则表达式正则表达式匹配。

@Size(min=, max=)

CharSequence,Collection,Map and 数组

检查注解的集合、映射或数组的大小(包括在 minmax (含)之间。

@Valid

任何非保护类型

在注释的对象上递归执行验证。如果对象是集合或数组,则会以递归方式验证元素。如果对象是映射映射,则将递归验证值元素。

65.2.3. 自定义注解

在 Hibernate 中定义自定义限制

可以使用 bean 验证 API 自行定义自定义约束注解。有关如何在 Hibernate 验证器实现中进行此操作的详情,请参考 Hibernate 验证器 参考指南 中的 创建自定义约束 章节。