在 Spring/Spring Boot 中实现优雅地参数校验

最近在写项目的时候,在每一个controller都充满了大量的if来校验参数,而且每一个controller还不同,不能把校验的方法封装起来.特别麻烦.

最普通的做法就像下面这样。我们通过 if/else 语句对请求的每一个参数一一校验。

				if (
                        StringUtils.isBlank(dto.getFwsz().get(i).getFwmc()) ||
                                dto.getFwsz().get(i).getCsl() == null ||
                                dto.getFwsz().get(i).getLjzcsl() == null ||
                                dto.getFwsz().get(i).getYlzcsl() == null)
                {
                    throw new APIException("缺少必填项");
                }

这样的代码明显违背了 单一职责原则。大量的非业务代码混杂在业务代码中，非常难以维护，还会导致业务层代码冗杂！

下面会通过实例程序演示如何在 SpringBoot 程序中优雅地的进行参数验证(普通的 Java 程序同样适用)。

@PostMapping
    public ResponseEntity<PersonRequest> save(@RequestBody @Valid PersonRequest personRequest) {
        return ResponseEntity.ok().body(personRequest);
    }

@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
public class PersonRequest {

    @NotNull(message = "classId 不能为空")
    private String classId;

    @Size(max = 33)
    @NotNull(message = "name 不能为空")
    private String name;

    @Pattern(regexp = "(^Man$|^Woman$|^UGM$)", message = "sex 值不在可选范围")
    @NotNull(message = "sex 不能为空")
    private String sex;

}

正则表达式说明：

• ^string : 匹配以 string 开头的字符串
• string$ ：匹配以 string 结尾的字符串
• ^string$ ：精确匹配 string 字符串
• (^{Man$|^Woman$|}UGM$) : 值只能在 Man,Woman,UGM 这三个值中选择

默认情况下，Spring 会将此异常转换为 HTTP Status 400(错误请求).但是这样返回不友善,自定义异常处理器可以帮助我们捕获异常，并进行一些简单的处理。

@ControllerAdvice(assignableTypes = {PersonController.class})
public class GlobalExceptionHandler {
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<Map<String, String>> handleValidationExceptions(
            MethodArgumentNotValidException ex) {
        Map<String, String> errors = new HashMap<>();
        ex.getBindingResult().getAllErrors().forEach((error) -> {
            String fieldName = ((FieldError) error).getField();
            String errorMessage = error.getDefaultMessage();
            errors.put(fieldName, errorMessage);
        });
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(errors);
    }
}

验证请求参数

验证请求参数（Path Variables 和 Request Parameters）即是验证被 @PathVariable 以及 @RequestParam 标记的方法参数。

PersonController

一定一定不要忘记在类上加上 Validated 注解了，这个参数可以告诉 Spring 去校验方法参数。

@RestController
@RequestMapping("/api/persons")
@Validated
public class PersonController {

    @GetMapping("/{id}")
    public ResponseEntity<Integer> getPersonByID(@Valid @PathVariable("id") @Max(value = 5, message = "超过 id 的范围了") Integer id) {
        return ResponseEntity.ok().body(id);
    }

    @PutMapping
    public ResponseEntity<String> getPersonByName(@Valid @RequestParam("name") @Size(max = 6, message = "超过 name 的范围了") String name) {
        return ResponseEntity.ok().body(name);
    }
}

ExceptionHandler

  @ExceptionHandler(ConstraintViolationException.class)
  ResponseEntity<String> handleConstraintViolationException(ConstraintViolationException e) {
     return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(e.getMessage());
  }

验证 Service 中的方法

我们还可以验证任何 Spring Bean 的输入，而不仅仅是 Controller 级别的输入。通过使用@Validated和@Valid注释的组合即可实现这一需求！

一般情况下，我们在项目中也更倾向于使用这种方案。

一定一定不要忘记在类上加上 Validated 注解了，这个参数可以告诉 Spring 去校验方法参数。

@Service
@Validated
public class PersonService {

    public void validatePersonRequest(@Valid PersonRequest personRequest) {
        // do something
    }

}

Validator 编程方式手动进行参数验证

某些场景下可能会需要我们手动校验并获得校验结果。

我们通过 Validator 工厂类获得的 Validator 示例。另外，如果是在 Spring Bean 中的话，还可以通过 @Autowired 直接注入的方式。

@Autowired
Validator validate

具体使用情况如下：

ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
Validator validator = factory.getValidator()
PersonRequest personRequest = PersonRequest.builder().sex("Man22")
  .classId("82938390").build();
Set<ConstraintViolation<PersonRequest>> violations = validator.validate(personRequest);
// 输出异常信息
violations.forEach(constraintViolation -> System.out.println(constraintViolation.getMessage()));
}

输出结果如下：

sex 值不在可选范围
name 不能为空

自定以 Validator(实用)

如果自带的校验注解无法满足你的需求的话，你还可以自定义实现注解。

案例一:校验特定字段的值是否在可选范围
比如我们现在多了这样一个需求：PersonRequest 类多了一个 Region 字段，Region 字段只能是China、China-Taiwan、China-HongKong这三个中的一个。

第一步，你需要创建一个注解 Region。

@Target({FIELD})
@Retention(RUNTIME)
@Constraint(validatedBy = RegionValidator.class)
@Documented
public @interface Region {

    String message() default "Region 值不在可选范围内";

    Class<?>[] groups() default {};

    Class<? extends Payload>[] payload() default {};
}

第二步，你需要实现 ConstraintValidator接口，并重写isValid 方法。

public class RegionValidator implements ConstraintValidator<Region, String> {

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        HashSet<Object> regions = new HashSet<>();
        regions.add("China");
        regions.add("China-Taiwan");
        regions.add("China-HongKong");
        return regions.contains(value);
    }
}

现在你就可以使用这个注解：

@Region
private String region;

案例二:校验电话号码

校验我们的电话号码是否合法，这个可以通过正则表达式来做，相关的正则表达式都可以在网上搜到，你甚至可以搜索到针对特定运营商电话号码段的正则表达式。

PhoneNumber.java


Documented
@Constraint(validatedBy = PhoneNumberValidator.class)
@Target({FIELD, PARAMETER})
@Retention(RUNTIME)
public @interface PhoneNumber {
    String message() default "Invalid phone number";
    Class[] groups() default {};
    Class[] payload() default {};
}

PhoneNumberValidator.java

public class PhoneNumberValidator implements ConstraintValidator<PhoneNumber, String> {

    @Override
    public boolean isValid(String phoneField, ConstraintValidatorContext context) {
        if (phoneField == null) {
            // can be null
            return true;
        }
        //  大陆手机号码11位数，匹配格式：前三位固定格式+后8位任意数
        // ^ 匹配输入字符串开始的位置
        // \d 匹配一个或多个数字，其中 \ 要转义，所以是 \\d
        // $ 匹配输入字符串结尾的位置
        String regExp = "^[1]((3[0-9])|(4[5-9])|(5[0-3,5-9])|([6][5,6])|(7[0-9])|(8[0-9])|(9[1,8,9]))\\d{8}$";
        return phoneField.matches(regExp);
    }
}

搞定，我们现在就可以使用这个注解了。

@PhoneNumber(message = "phoneNumber 格式不正确")
@NotNull(message = "phoneNumber 不能为空")
private String phoneNumber;

常用校验注解总结
JSR303 定义了 Bean Validation（校验）的标准 validation-api，并没有提供实现。Hibernate Validation是对这个规范/规范的实现 hibernate-validator，并且增加了 @Email、@Length、@Range 等注解。Spring Validation 底层依赖的就是Hibernate Validation。

JSR 提供的校验注解:

• @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(regex=,flag=) 被注释的元素必须符合指定的正则表达式

Hibernate Validator 提供的校验注解：

• @NotBlank(message =) 验证字符串非 null，且长度必须大于 0
• @Email 被注释的元素必须是电子邮箱地址
• @Length(min=,max=) 被注释的字符串的大小必须在指定的范围内
• @NotEmpty 被注释的字符串的必须非空
• @Range(min=,max=,message=) 被注释的元素必须在合适的范围内
  拓展

@NotNull 和 @Column(nullable = false) 两者有什么区别？

• @NotNull是 JSR 303 Bean 验证批注,它与数据库约束本身无关。
• @Column(nullable = false) : 是 JPA 声明列为非空的方法。
  总结来说就是即前者用于验证，而后者则用于指示数据库创建表的时候对表的约束。