如何使用自定义注解进行参数校验

背景

在日常的开发工作过程中，我们用的比较多的参数校验注解有 @NotBlank、@NotBlank、@NotEmpty、@Min、@Max 等等。这些注解只实现了一些基本校验，但是实际工作当中有很多参数的校验要比这个复杂的多（例如：校验输入参数是否符合身份证的规则）。当我们面对这些复杂校验的时候，这些基本的注解就无能为力了。

通常的解决方案

如果工作中真遇到上述的情况，我们该怎么办呢？

通常的做法是将复杂的校验逻辑写在业务代码中，如下：

public class AccountController {
    public AccountVo getAccount(@RequestParam("cardNo") String cardNo) {
        if (!isValid(cardNo) {
            // 校验证件号是否有效，若无效则提示无效证件号
        }
        
        // TODO 验证通过后，进行业务处理
        ...
        
        return accountVo;
    }
}

这种实现方式的弊端是：参数校验逻辑与业务处理逻辑掺杂在一起，看起来并不是那么简洁。

优化后的解决方案

我们可以通过 「自定义注解 + 自定义验证器」将参数验证逻辑与业务处理逻辑剥离开。具体做法如下：

1. 首先我们需要自定义一个 @IdCard 注解，代码如下：

   @Target({ ElementType.FIELD, ElementType.PARAMETER })
   @Retention(RetentionPolicy.RUNTIME)
   @Documented
   public @interface IdCard {
       String message() default “cardNo invalid”;
   
       Class<?>[] groups() default { };
   
       Class<? extends Payload>[] payload() default { };
   } 
   

2. 然后，我们需要自定义一个针对 @IdCard 注解的验证器，代码如下：

   public class IdCardValidator implements ConstraintValidator<IdCard, String> {
       @Override
       public boolean isValid(String value, ConstraintValidatorContext context) {
           // 这里的 value 就是输入参数（证件号），例如：230102197701013467
   
           // TODO 根据自己的实际业务情况，编写校验逻辑，返回校验结果
           return true;
       }
   } 
   

   这里需要说明的是，如下图：
   

3. 当我们为 @IdCard 注解创建好了对应的自定义验证器 IdCardValidator 后，我们还要回头在 @IdCard 注解的定义类上标识 @IdCard 与 IdCardValidator 的关系，如下图：
   
   如上图，需要在 @IdCard 注解的定义类上增加 @Constraint(validatedBy = IdCardValidator.class) 注解。

4. 至此，我们就可以像使用 @NotNull 注解一样来使用自定义 @IdCard 注解了，代码如下：

    import org.springframework.validation.annotation.Validated;
    import org.springframework.web.bind.annotation.RestController;
    
    @RestController
    @Validated
    public class AccountController {
        public AccountVo getAccount(@RequestParam("cardNo") @IdCard String cardNo) {
           return accountVo;
        }
    }