Java API 开发中使用 Bean Validation 进行参数校验

在 Java API 的开发中，参数校验是一个非常重要的环节。使用 Bean Validation 框架可以方便地实现对参数的校验，从而保证 API 的参数传递的合法性。本文将介绍 Bean Validation 的使用方法。

一、什么是 Bean Validation？

Bean Validation 是 Java EE 6 规范中的一部分。它是一个基于注解的参数校验框架，可以用于在方法、构造函数、字段和属性等注解中添加校验规则。这些注解可以帮助开发人员在代码编写阶段更好地预防输入错误，并在运行时检测和提示用户输入错误。

Bean Validation 框架主要解决以下问题：

1. 验证业务逻辑和限制（例如：是否为空、是否为邮箱、是否为数字等）。
2. 验证格式和语法（例如：日期、电话号码、邮政编码等）。
3. 验证两个或多个字段的互相依赖性（例如：开始日期必须早于结束日期）。

二、Bean Validation 如何工作？

Bean Validation 框架使用注解来标注需要校验的参数，这些注解包括 @NotNull、@Min、@Max、@Size、@Pattern 等。当参数被传递到方法中时，Bean Validation 框架自动执行相应的校验规则，当校验失败时，Bean Validation 框架发送一个错误信息。开发人员可以编写自定义的校验规则，以满足业务需求。

Bean Validation 框架提供了一组预定义的校验规则，这些规则可以应用于 Java Bean 中的属性和方法参数。预定义的规则包括：

@NotNull：检查是否为空值

@Size：检查String、Collection、Map和数组的长度

@Min、@Max：检查数值的大小

@Email：检查是否为电子邮件地址

@Pattern：根据正则表达式检查字符串

使用 Bean Validation 框架时，需要在类路径下包含 javax.validation-api 和相应的 Bean Validation 实现，例如 Hibernate Validator，通过 Maven，可以添加以下依赖：

<dependency>
    <groupId>javax.validation</groupId>
    <artifactId>validation-api</artifactId>
    <version>2.0.1.Final</version>
</dependency>
<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>6.0.10.Final</version>
</dependency>

三、Bean Validation 示例

假设我们有一个 User 类，其中包含了用户的基本信息，现在需要对 User 类中的属性进行校验：

public class User {
    private String name;
    private Integer age;
    private String email;
    private String address;
  
    // getters and setters
}

项目所需的校验规则如下：

1. name 不为空且长度大于 5 且小于 10；
2. age 不为空且大于 0 且小于 200；
3. email 不为空且为有效的邮箱地址；
4. address 可以为空。

我们可以使用 Bean Validation 来定义这些校验规则，具体实现如下：

public class UserValidator {

    private Validator validator;

    public UserValidator() {
        ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
        validator = factory.getValidator();
    }

    /**
     * 对 User 对象进行校验
     * 
     * @param user
     * @return
     */
    public String validate(User user) {

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

        StringBuilder result = new StringBuilder();
        if (!violations.isEmpty()) {
            for (ConstraintViolation<User> violation : violations) {
                result.append(violation.getMessage()).append(";");
            }
        }

        return result.toString();
    }
}

在 UserValidator 类中，我们使用了 Validator 工具类，通过 buildDefaultValidatorFactory() 方法创建一个 ValidatorFactory 对象，从而创建一个实例化的 Validator 对象。通过调用 validator.validate(user) 方法，可以对 User 对象进行校验。对于校验结果，我们将所有错误信息记录在 StringBuilder 对象中，并返回给调用端。

最后，我们可以在测试类中使用 UserValidator 对象并进行测试：

public class UserValidatorTest {
  
    @Test
    void testValidateUser() {
        User user = new User();
        user.setName("abcd");
        user.setAge(300);
        user.setEmail("abc");
        user.setAddress(null);

        UserValidator validator = new UserValidator();
        String result = validator.validate(user);

        assertThat(result, containsString("Name length must be between 5 and 10."));
        assertThat(result, containsString("Size must be between 1 and 200."));
        assertThat(result, containsString("must be a well-formed email address"));
    }
}

在上面的测试方法中，我们创建了一个 User 对象，其中的属性不符合校验规则，因此调用 UserValidator 的 validate() 方法会返回相应的错误信息。

四、总结

本文介绍了 Bean Validation 框架的概念和使用方法。该框架通过注解对参数进行校验，可以帮助开发人员在编写代码时预防输入错误，在运行时检测和提示用户输入错误。同时，开发人员可以根据业务需求编写自定义的校验规则，满足更复杂的校验场景。