1.5.孤城暗雪：验证

青海长云暗雪山，孤城遥望玉门关。——王昌龄《从军行七首·其四》

• 项目地址：https://github.com/silentbalanceyh/vertx-zero-example/（子项目：up-apollo）

「壹」JSR303

    本章我们进入Zero中的另外一大亮点——对JSR303的支持；JSR303是Java EE 6开始出现的一项子规范，又称为Bean Validation，它提供了后端执行请求校验的基本规范，而常用的一个该规范的实现就是Hibernate Validator，Zero中则使用了它来实现该规范，并且对之进行了深度扩展。

    接下来的讲解中，我们将忽略控制台中大部分输出，而关注异常响应部分来看Zero中对JSR部分的支持。Zero对JSR303支持的使用场景如下：

1. JSR303可以在Zero中的Agent组件中使用。

2. 扩展了JSR303过后，Zero可针对Json结构的数据进行验证（配合yaml配置文件）。

在Zero中一个标准的Verticle组件分两种：Agent组件和Worker组件，后续章节会逐步讲解异步模式下的开发，让读者逐渐了解这两种组件。

    关于Zero中对JSR303的部分有两个限制：

1. 在对Json结构的数据执行验证时，验证的数据规范和zero-ui前端一致，一方面可以和它无缝集成，另外一方面可以独立使用。

2. JSR303在执行Json结构数据验证时，需配合yml格式的接口描述文件执行验证定义描述。

1.1. JSR303注解

    JSR303中的注解如下：

注解位于包javax.validation.constraints中。

注解名	说明
@Null	注释的元素必须为null。
@NotNull	注释的元素必须不为null。
@AssertTrue	注释的元素必须是true。
@AssertFalse	注释的元素必须是false。
@Min(value)	被注释的元素必须是一个数字，其值必须大于等于指定的最小值。
@Max(value)	被注释的元素必须是一个数字，其值必须小于等于指定的最大值。
@DecimalMin(value)	被注释的元素必须是一个数字，其值必须大于等于指定的最小值。
@DecimalMax(value)	被注释的元素必须是一个数字，其值必须小于等于指定的最大值。
@Size(max,min)	被注释的元素大小必须在指定的范围内。
@Digits(integer,fraction)	被注释的元素必须是数值，且精度是可接受的范围。
@Past	被注释的元素必须是一个过去的时间。
@Future	被注释的元素必须是一个将来的时间。
@Pattern(value)	被注释的元素必须符合指定的正则表达式。

1.2. 环境准备

1.2.1. Hibernate Validator基础配置

    Hibernate Validator的默认配置文件位于资源文件ValidationMessages.properties ，在Zero中，默认的文件名修改成vertx-validation.properties，同样支持国际化。在Maven结构项目中，仅需在src/main/resources 目录中引入vertx-validation.properties配置文件配置验证过程中的文字说明。

    如果要设置验证信息，则可在资源目录中添加属性文件vertx-validation.properties，而该文件在处理中文编码时需注意：

• 如果编辑器使用的编码是UTF-8（推荐），则可直接在.properties中输入中文。

• 如果编辑器使用的编码是ISO-8859-1（系统默认），则使用native2ascii工具直接将中文字符串转换成Unicode格式。

1.2.2. 响应规范

    Zero中严格遵循HTTP应用层协议，当验证失败时，会生成HTTP状态代码为400（Bad Request）的错误响应，该响应的基础格式如：

{
    "code": "",
    "message": "",
    "info": ""
}

    三节点的含义如下：

属性名	类型	含义
code	负整数	系统内部错误码，通常是小于-10000的负数。
message	字符串	「Debug」系统错误描述。
info	字符串	客户端专用异常信息，如验证异常会显示验证信息在前端。

1.3. JSR303示例

1.3.1. @Null/@NotNull

    必填和可选专用注解，参考下边示例：

package cn.vertxup.micro.jsr303.agent;

import io.vertx.up.annotations.EndPoint;

import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Null;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.QueryParam;

@EndPoint
@Path("/hi/jsr303")
public class NullableAgent {
    /*
     * HTTP 方法为GET，提供参数则抛异常
     * 参数位于 `/api/jsr303/null?name=`位置
     */
    @GET
    @Path("/null")
    public String nullNo(@Null @QueryParam("name") final String name) {
        return "Hi, Null: " + name;
    }

    /* 对应 vertx-validation.properties 文件中的 nullable.null 值！*/
    @GET
    @Path("/null-msg")
    public String nullMsg(@Null(message = "{nullable.null}")
                          @QueryParam("name") final String name) {
        return "Hi, Null: " + name;
    }

    /*
     * HTTP 方法为GET，不提供参数则抛异常
     * 参数位于 `/api/jsr303/notnull?name=`位置
     */
    @POST
    @Path("/notnull")
    public String notnull(@NotNull @QueryParam("name") final String name) {
        return "Hi, Value: " + name;
    }

    /* 对应 vertx-validation.properties 文件中的 nullable.notnull 值！*/
    @POST
    @Path("/notnull-msg")
    public String notnullMsg(@NotNull(message = "{nullable.notnull}")
                             @QueryParam("name") final String name) {
        return "Hi, Value: " + name;
    }
}

    您可以在up-apollo项目中找到该源代码，上述示例中对应的配置文件内容如下：

nullable.null=对不起参数`name`必须是null！
nullable.notnull=对不起参数`name`是必须参数！

    发送下边请求：

/hi/jsr303/null-msg?name=lang

    您就可以得到一个HTTP状态代码为400（Bad Request）的响应：

{
    "code": -60000,
    "message": "[ERR-60000] (Validator) Web Exception occurs: (400) ...",
    "info": "对不起参数`name`必须是null！"
}

有关JSR303和Hibernate-Validator的信息读者可以参考相关教程，这里就不重述了，但后续示例会对JSR303的基础注解提供部分参考代码。

1.3.2. @AssertTrue/@AssertFalse

    布尔类型专用注解，参考下边示例：

package cn.vertxup.micro.jsr303.agent;

import io.vertx.up.annotations.EndPoint;

import jakarta.validation.constraints.AssertFalse;
import jakarta.validation.constraints.AssertTrue;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.QueryParam;

@EndPoint
@Path("/hi/jsr303")
public class AssertAgent {
    @Path("assert")
    @GET
    public String sayBoolean(
            @AssertTrue @QueryParam("male") final Boolean isMale,
            @AssertFalse @QueryParam("female") final Boolean isFemale) {
        return "Hi, Lang, the parameters is 'male' = " + isMale +
                ", 'female' = " + isFemale;
    }
}

    发送下边请求：

/hi/jsr303/assert

    于是您将得到如下响应：

{
    "data": "Hi, Lang, the parameters is 'male' = null, 'female' = null"
}

    也许读者会困惑，为什么看起来验证并没有生效呢？主要是该参数并没有配合@NotNull 来验证必填性质。Zero中默认是所有参数都可选的，即Optional，当您要求单个参数必填时，则需进一步执行@NotNull限定，不仅仅是@AssertTrue，@AssertFalse的注解，其他所有JSR303的基础注解都依赖@NotNull限定来区分参数的** 必填和可选**。

    加入了@NotNull过后，发送请求：

/hi/jsr303/assert?male=true&female=true

    您就得到了400 Bad Request的响应信息：

{
    "code": -60000,
    "message": "[ERR-60000] (Validator) Web Exception occurs: (400) - ...",
    "info": "must be false"
}

1.3.3. @Min/@Max

    数值类型专用注解，参考下边示例：

package cn.vertxup.micro.jsr303.agent;

import io.vertx.up.annotations.EndPoint;

import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.QueryParam;

@EndPoint
@Path("/hi/jsr303")
public class NumericAgent {

    @Path("numeric")
    @GET
    public String sayNum(
            @Min(10) @Max(100)
            @QueryParam("age") final Integer age,
            @Min(1)
            @QueryParam("test") final Integer test
    ) {
        return "Hello, please check your age. " + age;
    }
}

    发送下边请求：

/hi/jsr303/numeric?age=8&test=101

    您就得到了400 Bad Request的响应信息：

{
    "code": -60000,
    "message": "[ERR-60000] (Validator) Web Exception occurs: (400) - ...",
    "info": "must be greater than or equal to 10"
}

1.3.4. @DecimalMin/@DecimalMax

    浮点类型专用注解，参考下边示例：

package cn.vertxup.micro.jsr303.agent;

import io.vertx.up.annotations.EndPoint;

import jakarta.validation.constraints.DecimalMax;
import jakarta.validation.constraints.DecimalMin;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.QueryParam;

@EndPoint
@Path("/hi/jsr303")
public class DecimalAgent {

    @Path("decimal")
    @GET
    public String sayDecimal(
            @DecimalMin("0.3")
            @QueryParam("min") final Double min,
            @DecimalMax("0.7")
            @QueryParam("max") final Double max
    ) {
        return "Hi, min = " + min + ", max = " + max;
    }
}

    发送下边请求：

/hi/jsr303/decimal?min=0.1&max=0.8

    您就得到了400 Bad Request的响应信息：

{
    "code": -60000,
    "message": "[ERR-60000] (Validator) Web Exception occurs: (400) - ...",
    "info": "must be less than or equal to 0.7"
}

注：这两个注解的字面量使用的是java.lang.String类型，而并不是java.lang.Double类型，简言之，只要字面量可转换成合法浮点数，那么就可以设置到注解的value中。

1.3.5. @Size

    字符串专用注解，参考下边示例：

package cn.vertxup.micro.jsr303.agent;

import io.vertx.up.annotations.EndPoint;

import jakarta.validation.constraints.Size;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.QueryParam;

@EndPoint
@Path("/hi/jsr303")
public class SizeAgent {

    @Path("size")
    @GET
    public String saySize(
            @Size(min = 1, max = 20)
            @QueryParam("size") final String size
    ) {
        return "Hi, Size = " + size;
    }
}

    发送下边请求：

/hi/jsr303/size?size=[e-mail]

    您就得到了400 Bad Request的响应信息：

{
    "code": -60000,
    "message": "[ERR-60000] (Validator) Web Exception occurs: (400) - ...",
    "info": "size must be between 1 and 20"
}

1.3.6. @Digits

    浮点数精度专用注解，参考下边示例：

package cn.vertxup.micro.jsr303.agent;

import io.vertx.up.annotations.EndPoint;

import jakarta.validation.constraints.Digits;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.QueryParam;

@EndPoint
@Path("/hi/jsr303")
public class DigitAgent {

    @Path("digit")
    @GET
    public String sayDigit(
            @Digits(integer = 2, fraction = 2)
            @QueryParam("digit") final Double currency
    ) {
        return "Hi, Currency is " + currency;
    }
}

    发送下边请求：

/hi/jsr303/digit?digit=140.22

    您就得到了400 Bad Request的响应信息：

{
    "code": -60000,
    "message": "[ERR-60000] (Validator) Web Exception occurs: (400) - ...",
    "info": "numeric value out of bounds (<2 digits>.<2 digits> expected)"
}

1.3.7. @Future/@Post

    时间专用注解，参考下边示例：

package cn.vertxup.micro.jsr303.agent;

import io.vertx.up.annotations.EndPoint;

import jakarta.validation.constraints.Future;
import jakarta.validation.constraints.Past;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.QueryParam;
import java.util.Date;

@EndPoint
@Path("/hi/jsr303")
public class DateAgent {

    @Path("date")
    @GET
    public String sayDate(
            @Future
            @QueryParam("to") final Date future,
            @Past
            @QueryParam("from") final Date past
    ) {
        return "Hi, Future = " + future + ", Past = " + past;
    }
}

    发送下边请求：

hi/jsr303/date?to=2018-09-11&from=2018-04-01

    您就得到了400 Bad Request的响应信息：

{
    "code": -60000,
    "message": "[ERR-60000] (Validator) Web Exception occurs: (400) - ...",
    "info": "must be a future date"
}

1.3.8. @Pattern

    正则表达式专用注解，参考下边示例：

package cn.vertxup.micro.jsr303.agent;

import io.vertx.up.annotations.EndPoint;

import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.Pattern;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.QueryParam;

@EndPoint
@Path("/hi/jsr303")
public class PatternAgent {

    @Path("pattern")
    @GET
    public String sayRegex(
            @Pattern(regexp = "^$|^[a-zA-Z]+$",
                    message = "must be a letter ")
            @QueryParam("pattern") final String size
    ) {
        return "Hi, Size = " + size;
    }

    @Path("email")
    @GET
    public String sayEmail(
            @Email
            @QueryParam("email") final String email
    ) {
        return "Hi, email = " + email;
    }
}

    发送下边请求：

hi/jsr303/pattern?pattern=1017

    您就得到了400 Bad Request的响应信息：

{
    "code": -60000,
    "message": "[ERR-60000] (Validator) Web Exception occurs: (400) - ...",
    "info": "must be a letter "
}

    该示例中不仅使用了JSR303原生的@Pattern注解，还使用了Hibernate Validator中扩展的JSR303的相关注解，它扩展的常用注解如下：

注解名	说明
@Email	被注解的元素必须是电子邮件地址。
@Length(min,max)	被注解的字符串大小必须在指定的范围内。
@NotEmpty	被注解的字符串必须非空。
@Range(min,max)	被注解的元素必须在合适的范围内。
@NotBlank	被注解的字符串必须非空。
@URL(protocol,host,port,regexp,flags)	被注释的字符串必须是一个有效的URL。
@CreditCardNumber	被注释的字符串必须通过Luhn校验算法（银行卡、信用卡）。
@ScriptAssert(lang,script,alias)	必须有JSR 223规范支持。
@SafeHtml(whitelistType,additionalTags)	Class类类路径中有jsonup包。

详细用法参考Hibernate Validator官方文档。

1.3.9. Pojo模式

    除了上边的单独参数的校验以外，Zero中同样借着Hibernate Validator支持Pojo类型的Java类的校验，参考下边示例代码：

JavaJson类

package cn.vertxup.micro.jsr303.agent;

import lombok.Data;

import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotNull;

@Data
public class JavaJson {

    @NotNull
    private String name;
    @Email
    private String email;
    @Min(1)
    private Integer age;
}

PojoAgent主类

package cn.vertxup.micro.jsr303.agent;

import io.vertx.core.json.JsonObject;
import io.vertx.up.annotations.EndPoint;
import io.vertx.up.util.Ut;

import javax.validation.Valid;
import jakarta.ws.rs.BodyParam;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;

@EndPoint
@Path("/hi/jsr303")
public class PojoAgent {

    @Path("pojo")
    @POST
    public JsonObject sayPojo(
            @BodyParam @Valid final JavaJson json
    ) {
        return Ut.serializeJson(json);
    }
}

    发送下边请求：

hi/jsr303/pojo

    请求内容如：

{
    "email":"[e-mail]"
}

    您就得到了400 Bad Request的响应信息：

{
    "code": -60000,
    "message": "[ERR-60000] (Validator) Web Exception occurs: (400) - ...",
    "info": "must not be null"
}

    倘若您直接改成下边请求就可以发送成功了：

{
    "name":"Lang",
    "email":"[e-mail]",
    "age":33
}

该示例中使用了lombok库操作Pojo，并且使用了Zero对JSR303的扩展注解@BodyParam。

「贰」JSR303扩展

2.1. 现存问题

    在开发企业级项目过程中，JSR303的使用也许远远不够，它主要可以解决下边两个场景的使用：

• 普通零散参数的验证。

• 参数直接可转换成Pojo的参数的验证。

    但是还有很多场景可能无法满足某些基本需求，例如：

• 无固定Pojo结构的复杂参数验证，如JsonObject/JsonArray。

• 集合结构的验证。

• 上传文件的验证。

• 自定义验证。

2.2. Zero扩展

    Zero框架对JSR303进行了实现层的扩展，这些扩展让Zero在处理前文提到的问题时羽翼更加丰富了，关于入参的注解此处就不详细描述了，这部分在前边一个章节已经提及。

2.2.1. 启用配置

    本章节会使用一个特殊的Zero注解：io.vertx.up.annotations.Codex，该注解表示当前结构会启用Zero中的扩展验证功能。启用了@Codex 注解过后，需要在项目的资源目录中提供验证配置文件：

• 配置文件目录：src/main/resources/codex/

• 文件名基础规则：

  • 基本文件名 = <api>.<method>.yml。

  • api中的/直接被.符号替换。

  • api中如果出现了:name路径参数，则:被替换成$符号而生效。

    在对应目录中创建示例中所需的验证规则文件hi.jsr303.advanced.post.yml：

    该文件的内容如下：

username:
- type: required
  message: "Please input your username!"
- type: length
  min: 6
  message: "Your username length must be greater than 6"
password:
- type: required
  message: "Please provide your password"

2.2.2. 示例代码

    参考下边的示例代码：

package cn.vertxup.micro.jsr303.extension;

import io.vertx.core.json.JsonObject;
import io.vertx.up.annotations.Codex;
import io.vertx.up.annotations.EndPoint;

import jakarta.ws.rs.BodyParam;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;

@EndPoint
@Path("/hi/jsr303")
public class BodyAgent {

    @POST
    @Path("/advanced")
    public JsonObject testCodex(
            @BodyParam @Codex final JsonObject user
    ) {
        return user;
    }
}

    发送下边请求：

hi/jsr303/advanced

    请求内容如：

{
    "username":"Lang"
}

    您就得到了400 Bad Request的响应信息：

{
    "code": -60005,
    "message": "[ERR-60005] (MinLengthRuler) Web Exception occurs: (400) - ...",
    "info": "Your username length must be greater than 6"
}

2.3. Zero功能支持

    上述小节提供了基本的示例让读者对@Codex有了一定的了解，那么Zero对这种验证究竟扩展到何等程度呢——我相信这是读者最关心的。

2.3.1. 参数类型

    细心的读者会发现，@Codex只会作用于部分复杂结构，这种复杂结构主要包括：

包	类名	含义
io.vertx.core.json	JsonObject	Json对象类型。
io.vertx.core.json	JsonArray	Json数组类型。
io.vertx.ext.web	FileUpload	Vertx中的文件上传类型。
java.io	File	Java中的文件对象（Zero直接支持该参数）。

简单说上述类型作为参数时就可以直接使用@Codex注解。

2.3.2. 规则分类

    上述文件hi.jsr303.advanced.post.yml中为不同的字段定义了验证规则，字段的验证规则可支持多个，验证时按照定义顺序依次验证。

    每种类型的公共配置如：

配置名	含义
type	规则类型，不同类型决定了配置参数以及验证执行器。
message	验证失败响应消息，最终呈现在界面中的文字信息。

Zero中支持的类型表如下：

类型（type）	配置表	含义
required	验证某个属性是否必须。
length	min, max	验证某个字符串长度是否在某个范围。
minlength	min	验证某个字符串最小长度（length的快速版）。
maxlength	max	验证某个字符串最大长度（length的快速版）。
empty	「集合专用」验证某个集合是否为空。
singlefile	「上传专用」验证上传文件是否为单个文件，多个文件非法。

「叄」总结

    本章主要介绍了Zero对JSR303规范的支持、扩展和相关示例：

• Zero支持JSR303规范中的大部分验证注解（Hibernate-Validator实现）。

• Zero对JSR303规范进行了扩展，支持复杂数据结构的验证。