每天一个摆脱if-else工程师的技巧,优雅的参数校验

简介: 在日常的开发工作中,为了程序的健壮性,大部分方法都需要进行入参数据校验。本文围绕作者如何优雅的进行参数校验展开讨论。

1. 前言

在日常的开发工作中,为了程序的健壮性,大部分方法都需要进行入参数据校验。最直接的当然是在相应方法内对数据进行手动校验,但是这样代码里就会有很多冗余繁琐的if-else。比如如下的保存用户信息的方法:

@RestController
public class TestController {

    private static final Pattern ID_CARD_PATTERN = Pattern.compile("(^\\d{15}$)|(^\\d{18}$)|(^\\d{17}(\\d|X|x)$)");
    private static final Pattern MOBILE_PHONE_PATTERN = Pattern.compile("^(13[0-9]|14[01456879]|15[0-35-9]|16[2567]|17[0-8]|18[0-9]|19[0-35-9])\\d{8}$");

    @RequestMapping(value = "/api/saveUser", method = RequestMethod.POST)
    public Result<Boolean> saveUser(UserRequest user) {
        if (StringUtils.isBlank(user.getUserName())) {
            throw new IllegalArgumentException("用户姓名不能为空");
        }
        if (Objects.isNull(user.getGender())) {
            throw new IllegalArgumentException("性别不能为空");
        }
        if (Objects.isNull(GenderType.getGenderType(user.getGender()))) {
            throw new IllegalArgumentException("性别错误");
        }
        if (Objects.isNull(user.getAge())) {
            throw new IllegalArgumentException("年龄不能为空");
        }
        if (user.getAge() < 0 || user.getAge() > 150) {
            throw new IllegalArgumentException("年龄必须在0-150之间");
        }
        if (StringUtils.isBlank(user.getIdCard())) {
            throw new IllegalArgumentException("身份证号不能为空");
        }
        if (!ID_CARD_PATTERN.matcher(user.getIdCard()).find()) {
            throw new IllegalArgumentException("身份证号格式错误");
        }
        if (StringUtils.isBlank(user.getMobilePhone())) {
            throw new IllegalArgumentException("手机号不能为空");
        }
        if (!MOBILE_PHONE_PATTERN.matcher(user.getIdCard()).find()) {
            throw new IllegalArgumentException("手机号格式错误");
        }
        // 省略其他业务代码
        return new ResponseEntity<>(HttpStatus.OK);
    }
}

上面的方法因为请求对象里的参数很多,所以就有了好多if/else。当然这么写没问题,但是:1.扩展性差:如果后续 UserRequest 里又新增了参数,那还得在方法实现里增加校验代码,参数校验和业务代码混在一起。2.可读性差:当参数校验过多时,代码会十分冗长,违背阿里巴巴代码规约。3.不易复用:其他比如更新用户信息的方法,可能也会有类似的参数校验。如果也手动校验的话,会存在很多重复代码。那么该怎么优雅的进行参数校验呢?

2. 实践

咱就是说,有spring boot 自带的spring validation,为啥不用呢?Java在早在2009年就提出了 Bean Validation(JSR)[1]规范,其中定义了一系列的校验注解,比如 @NotEmpty、@NotNull等,支持通过注解的方式对字段进行校验,避免在业务逻辑中耦合冗余的校验逻辑。不过,以上注解本身不做校验,只是能给开发者做个提醒。如果需要达到参数校验的目的,还需要其他配置。话不多说,先往下看使用姿势。


2.1 Controller方法参数校验

2.1.1 效果示例

Spring 提供了相应的 Bean Validation 实现:Java Bean Validation[2],并在 Spring MVC 中添加了自动校验,默认就会对 @Valid/@Validated 修饰的方法参数使用 Validator 来做校验逻辑。举个栗子:第一步,在方法在入参对应元素上配置校验注解:

@Data
public class UserRequest {
    @NotBlank(message = "用户ID不能为空")
    private String userId;
  
    @NotBlank(message = "电话号码不能为空")
    @Pattern(regexp = "^(13[0-9]|14[01456879]|15[0-35-9]|16[2567]|17[0-8]|18[0-9]|19[0-35-9])\\d{8}$", message = "电话号码格式错误")
    private String mobilePhone;

    @Min(message = "年龄必须大于0", value = 0)
    @Max(message = "年龄不能超过150", value = 150)
    private Integer age;


    @NotNull(message = "用户详情不能为空")
    @Valid
    private UserDetail userDetail;
    
    //省略其他参数
}

第二步,在 Controller 相应方法中,使用 @Valid/@Validated 注解开启数据校验功能:

@RestController
public class TestController {

    @RequestMapping(value = "/api/saveUser", method = RequestMethod.POST)
    public ResponseEntity<BaseResult> saveUser(@Validated @RequestBody UserRequest user) {
        // 省略其他业务代码
        return new ResponseEntity<>(HttpStatus.OK);
    }
}

如果数据校验通过,就会继续执行方法里的业务逻辑;否则,就会抛出一个 MethodArgumentNotValidException 异常。默认情况下,Spring 会将该异常及其信息以错误码 400 进行下发,返回结果示例如下:

{
  "timestamp": 1666777674977,
  "status": 400,
  "error": "Bad Request",
  "exception": "org.springframework.web.bind.MethodArgumentNotValidException",
  "errors": [
    {
      "codes": [
        "NotBlank.UserRequest.mobilePhone",
        "NotBlank.mobilePhone",
        "NotBlank.java.lang.String",
        "NotBlank"
      ],
      "arguments": [
        {
          "codes": [
            "UserRequest.mobilePhone",
            "mobilePhone"
          ],
          "arguments": null,
          "defaultMessage": "mobilePhone",
          "code": "mobilePhone"
        }
      ],
      "defaultMessage": "电话号码不能为空",
      "objectName": "UserRequest",
      "field": "mobilePhone",
      "rejectedValue": null,
      "bindingFailure": false,
      "code": "NotBlank"
    }
  ],
  "message": "Validation failed for object='UserRequest'. Error count: 1",
  "path": "/api/saveUser"
}

但是返回的异常结果不是需要的格式,所以再来个全局异常捕获器拦截该异常,就可以得到一个完美的异常结果:

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public BaseResult handlerMethodArgumentNotValidException(MethodArgumentNotValidException e) {
        FieldError fieldError = e.getBindingResult().getFieldErrors().get(0);
        return new BaseResult(CommonResultCode.ILLEGAL_PARAMETERS.getErrorCode(),
                "入参中的" + fieldError.getField() + fieldError.getDefaultMessage(), EagleEye.getTraceId());
    }

}

设置了如上捕获器后,如果数据校验不通过,返回的结果为:

{
  "success": false,
  "errorCode": "ILLEGAL_PARAMETERS",
  "errorMessage": "入参中的mobilePhone电话号码不能为空",
  "traceId": "1ef9749316674663696111017d73c9",
  "extInfo": {}
}

借助Spring和约束注解,就非常简单明了、优雅地完成了方法参数校验。而且,假如以后入参对象里新增了参数,只需要顺便添加一个注解,而不用去改业务代码,稳!

2.1.2 @Valid 和 @Validated

  • @Valid [3]注解,是 Bean Validation 所定义,可以添加在普通方法、构造方法、方法参数、方法返回、成员变量上,表示它们需要进行约束校验。
  • @Validated [4]注解,是 Spring Validation 所定义,可以添加在类、方法参数、普通方法上,表示它们需要进行约束校验。

两者的区别在于 @Validated 有 value 属性,支持分组校验,即根据不同的分组采用不同的校验机制,@Valid 可以添加在成员变量上,支持嵌套校验。所以建议的使用方式就是:启动校验(即 Controller 层)时使用 @Validated 注解,嵌套校验时使用 @Valid 注解,这样就能同时使用分组校验和嵌套校验功能。

2.1.3 分组校验

但是,对于同个参数,不同的场景可能需要不同的校验,这时候就可以用分组校验能力。比如创建 User 时,userId为空;但是更新 User 时,userId值则不能为空。示例如下:

@Data
public class UserRequest {
    @NotBlank(message = "用户ID不能为空", groups = {UpdateUser.class})
    private String userId;
  
    @NotBlank(message = "电话号码不能为空", groups = {UpdateUser.class, InsertUser.class})
    @Pattern(regexp = "^(13[0-9]|14[01456879]|15[0-35-9]|16[2567]|17[0-8]|18[0-9]|19[0-35-9])\\d{8}$", message = "电话号码格式错误")
    private String mobilePhone;

    @Min(message = "年龄必须大于0", value = 0, groups = {UpdateUser.class, InsertUser.class})
    @Max(message = "年龄不能超过150", value = 150, groups = {UpdateUser.class, InsertUser.class})
    private Integer age;


    @NotNull(message = "用户详情不能为空", groups = {UpdateUser.class, InsertUser.class})
    @Valid
    private UserDetail userDetail;
    
    //省略其他参数
}


@RestController
public class TestController {

    @RequestMapping(value = "/api/saveUser", method = RequestMethod.POST)
    public ResponseEntity<BaseResult> saveUser(@Validated(value = InsertUser.class) @RequestBody UserRequest user) {
        // 省略其他业务代码
        return new ResponseEntity<>(HttpStatus.OK);
    }
}

2.1.4 自定义校验注解

还有,如果现有的基础校验注解没法满足校验需求,那就可以使用自定义注解[5]。由两部分组成:

  • 由 @Constraint 注解的注解。
  • 实现了 javax.validation.ConstraintValidator 的 validator。

两者通过 @Constraint 关联到一起。假设有个性别枚举,需要校验用户的性别是否属于此范围内,示例如下:

public enum GenderEnum implements BasicEnum {
    male("male", "男"),
    female("female", "女");

    private String code;

    private String desc;
    // 省略其他
}

第一步,自定义约束注解 InEnum,可以参考 NotNull 的定义:

@Target({ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = InEnumValidator.class)
public @interface InEnum {
    /**
     * 枚举类型
     *
     * @return
     */
    Class<? extends BasicEnum> enumType();

    String message() default "枚举类型不匹配";

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

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

第二步,自定义约束校验器 InEnumValidator。如果校验通过,返回 true;反之返回 false:

public class InEnumValidator implements ConstraintValidator<InEnum, Object> {
    private Class<? extends BasicEnum> enumType;

    @Override
    public void initialize(InEnum inEnum) {
        enumType = inEnum.enumType();
    }

    @Override
    public boolean isValid(Object object, ConstraintValidatorContext constraintValidatorContext) {
        if (object == null) {
            return true;
        }

        if (enumType == null || !enumType.isEnum()) {
            return false;
        }

        for (BasicEnum basicEnum : enumType.getEnumConstants()) {
            if (basicEnum.getCode().equals(object)) {
                return true;
            }
        }
        return false;
    }
}

第三步,参数上增加 @InEnum 注解校验:

@Data
public class UserRequest {
    @InEnum(enumType = GenderEnum.class, message = "用户性别不在枚举范围内")
    private String gender;
    
    //省略其他参数
}

设置了如上校验后,如果数据校验不通过,返回的结果为:

{
  "success": false,
  "errorCode": "ILLEGAL_PARAMETERS",
  "errorMessage": "入参中的gender用户性别不在枚举范围内",
  "traceId": "1ef9749316674663696111017d73c9",
  "extInfo": {}
}

2.1.5 校验原理

1、MethodValidationPostProcessor -- 是 Spring 提供的来实现基于方法的JSR校验的核心处理器,能让约束作用在方法入参、返回值上。关于校验方面的逻辑在切面MethodValidationInterceptor。

public class MethodValidationPostProcessor extends AbstractBeanFactoryAwareAdvisingPostProcessor
    implements InitializingBean {

  private Class<? extends Annotation> validatedAnnotationType = Validated.class;

    // 这个是javax.validation.Validator
  private Validator validator;


  // 可以传入自定义注解
  public void setValidatedAnnotationType(Class<? extends Annotation> validatedAnnotationType) {
    Assert.notNull(validatedAnnotationType, "'validatedAnnotationType' must not be null");
    this.validatedAnnotationType = validatedAnnotationType;
  }

    // 默认情况下,使用LocalValidatorFactoryBean进行校验,也可以传入自定义的Validator
  public void setValidator(Validator validator) {
    // Unwrap to the native Validator with forExecutables support
    if (validator instanceof LocalValidatorFactoryBean) {
      this.validator = ((LocalValidatorFactoryBean) validator).getValidator();
    }
    else if (validator instanceof SpringValidatorAdapter) {
      this.validator = validator.unwrap(Validator.class);
    }
    else {
      this.validator = validator;
    }
  }

    // 可以传入自定义ValidatorFactory
  public void setValidatorFactory(ValidatorFactory validatorFactory) {
    this.validator = validatorFactory.getValidator();
  }


  @Override
  public void afterPropertiesSet() {
    Pointcut pointcut = new AnnotationMatchingPointcut(this.validatedAnnotationType, true);
    this.advisor = new DefaultPointcutAdvisor(pointcut, createMethodValidationAdvice(this.validator));
  }

    // 使用MethodValidationInterceptor切面
  protected Advice createMethodValidationAdvice(Validator validator) {
    return (validator != null ? new MethodValidationInterceptor(validator) : new MethodValidationInterceptor());
  }

}

2、MethodValidationInterceptor -- 用于处理方法的数据校验

public class MethodValidationInterceptor implements MethodInterceptor {

    //xxx

  @Override
  @SuppressWarnings("unchecked")
  public Object invoke(MethodInvocation invocation) throws Throwable {
    // 如果是FactoryBean.getObject() 方法,就不要校验了
    if (isFactoryBeanMetadataMethod(invocation.getMethod())) {
      return invocation.proceed();
    }

        // 获取方法上@Validated注解里的分组信息
    Class<?>[] groups = determineValidationGroups(invocation);

    if (forExecutablesMethod != null) {
      // Standard Bean Validation 1.1 API
      Object execVal;
      try {
        execVal = ReflectionUtils.invokeMethod(forExecutablesMethod, this.validator);
      }
      catch (AbstractMethodError err) {
        Validator nativeValidator = this.validator.unwrap(Validator.class);
        execVal = ReflectionUtils.invokeMethod(forExecutablesMethod, nativeValidator);
        this.validator = nativeValidator;
      }

      Method methodToValidate = invocation.getMethod();
      Set<ConstraintViolation<?>> result;
            
            // 对方法的参数进行验证,验证结果保存在 result 中,如果验证失败,result 不为空,
            // 此时会抛出异常 ConstraintViolationException
      try {
        result = (Set<ConstraintViolation<?>>) ReflectionUtils.invokeMethod(validateParametersMethod,
            execVal, invocation.getThis(), methodToValidate, invocation.getArguments(), groups);
      }
      catch (IllegalArgumentException ex) {
        // Probably a generic type mismatch between interface and impl as reported in SPR-12237 / HV-1011
        // Let's try to find the bridged method on the implementation class...
        methodToValidate = BridgeMethodResolver.findBridgedMethod(
            ClassUtils.getMostSpecificMethod(invocation.getMethod(), invocation.getThis().getClass()));
        result = (Set<ConstraintViolation<?>>) ReflectionUtils.invokeMethod(validateParametersMethod,
            execVal, invocation.getThis(), methodToValidate, invocation.getArguments(), groups);
      }
      if (!result.isEmpty()) {
        throw new ConstraintViolationException(result);
      }

            // 调用目标方法
      Object returnValue = invocation.proceed();

            // 对方法执行的返回值进行验证 ,验证结果保存在 result 中,如果验证失败,result 不为空,
            // 此时会抛出异常 ConstraintViolationException
      result = (Set<ConstraintViolation<?>>) ReflectionUtils.invokeMethod(validateReturnValueMethod,
          execVal, invocation.getThis(), methodToValidate, returnValue, groups);
      if (!result.isEmpty()) {
        throw new ConstraintViolationException(result);
      }
      return returnValue;
    }

    else {
      // Hibernate Validator 4.3's native API
      return HibernateValidatorDelegate.invokeWithinValidation(invocation, this.validator, groups);
    }
  }

  //xxx

}

3、LocalValidatorFactoryBean -- 最终是使用它来执行验证功能的,它也是Spring MVC默认的验证器。默认情况下, LocalValidatorFactoryBean 会配置一个 SpringConstraintValidatorFactory 实例。如果有指定的 ConstraintValidatorFactory,就会使用指定的,因此在遇到自定义约束注解的时候,就会自动实例化 @Constraint指定的关联 Validator,从而完成数据校验过程。

4、SpringValidatorAdapter -- 是javax.validation.Validator到Spring的Validator的适配,通过它就可以对接到Bean Validation来完成校验了。

public class SpringValidatorAdapter implements SmartValidator, javax.validation.Validator {

  // 约束注解必要的三个成员属性
  private static final Set<String> internalAnnotationAttributes = new HashSet<String>(3);

  static {
    // 命中约束的错误提示信息
    internalAnnotationAttributes.add("message"); 
    // 分组校验使用
    internalAnnotationAttributes.add("groups");
    // 负载
    internalAnnotationAttributes.add("payload");
  }

  private javax.validation.Validator targetValidator;


  // 创建一个适配器
  public SpringValidatorAdapter(javax.validation.Validator targetValidator) {
    Assert.notNull(targetValidator, "Target Validator must not be null");
    this.targetValidator = targetValidator;
  }

  SpringValidatorAdapter() {
  }

  void setTargetValidator(javax.validation.Validator targetValidator) {
    this.targetValidator = targetValidator;
  }

  @Override
  public boolean supports(Class<?> clazz) {
    return (this.targetValidator != null);
  }

  // 调用校验器校验目标对象,把Validator校验的结果-ConstraintViolations错误信息,都放在Errors的BindingResult里
  // 总之,就是把失败信息对象转换成spring内部的验证失败信息对象
  @Override
  public void validate(Object target, Errors errors) {
    if (this.targetValidator != null) {
      processConstraintViolations(this.targetValidator.validate(target), errors);
    }
  }
  // 省略其他
}


2.2 Service方法参数校验

2.2.1 效果示例

更多情况下是需要对 Service 层的接口进行参数校验的,那么该怎么配置呢?在校验方法入参的约束时,若是 @Override 父类/接口的方法,那么这个入参约束只能写在父类/接口上面。(至于为什么只能写在接口处,其实是和 Bean Validation 的实现产品有关,可参考此类:OverridingMethodMustNotAlterParameterConstraints)

如果入参是平铺的参数:

首先需要在父类/接口的方法入参里增加注解约束,然后用 @Validated 修饰我们的实现类。

public interface SchedulerServiceClient {
    /**
     * 获取应用不同环境的所有定时任务
     * @param appName 应用名称
     * @param env 环境
     * @param status 任务状态
     * @param userId 用户工号
     * @return
     */
    List<JobConfigInfo> queryJobList(@NotBlank(message = "应用名称不能为空")String appName, 
                                     @NotBlank(message = "环境不能为空")String env, 
                                     Integer status, 
                                     @NotBlank(message = "用户id不能为空")String userId);
}


@Component
@Slf4j(topic = "BIZ-SERVICE")
@HSFProvider(serviceInterface = SchedulerServiceClient.class, clientTimeout = 3000)
@Validated
public class SchedulerServiceClientImpl implements SchedulerServiceClient {

    @Override
    @Log(type = LogSourceEnum.SERVICE)
    public List<JobConfigInfo> queryJobList(String appName, String env, Integer status, String userId) {
        // 省略业务代码
    }

如果数据校验通过,就会继续执行方法里的业务逻辑;否则,就会抛出一个 ConstraintViolationException 异常。

如果入参是对象

在实际开发中,其实大多数情况下我们方法入参是个对象,而不是单单平铺的参数。首先需要在方法入参类里增加 @NotNull 等注解约束,然后在父类/接口的方法入参里增加 @Valid(便于嵌套校验),最后用 @Validated 修饰我们的实现类。

public interface ProcessControlDingService {

    /**
    * 发送钉钉通知
    * @param request
    * @return
    **/
    void createDingNotification(@Valid CreateDingNotificationRequest request);

}


public interface ProcessControlDingService {

    /**
    * 发送钉钉通知
    * @param request
    * @return
    **/
    void createDingNotification(@Valid CreateDingNotificationRequest request);

}


@Component
@HSFProvider(serviceInterface = ProcessControlDingService.class, clientTimeout = 5000)
@Validated
public class ProcessControlDingServiceImpl implements ProcessControlDingService {

    private static final Logger LOGGER = LoggerFactory.getLogger(LoggerNames.BIZ_SERVICE);

    @Autowired
    private ProcessControlTaskService processControlTaskService;

    @Override
    @Log(type = LogSourceEnum.SERVICE)
    public void createDingNotification(CreateDingNotificationRequest request) {
        // 省略业务代码
    }
}

如果需要格式化错误结果,可以再来个异常处理切面,就可以得到一个完美的异常结果。

2.2.2 较简洁的方式-FastValidatorUtils

// 返回 bean 中所有约束违反约束校验结果
Set<ConstraintViolation<T>> violationSet = FastValidatorUtils.validate(bean);

原理见《FastValidator 原理与最佳实践》[6]具体示例如下:自定义注解@RequestValid和对应切面RequestValidAspect。注解在具体的方法上,对于被注解的方法,在 AOP 中会扫描所有入参,对参数进行校验。

@Aspect
@Component
@Slf4j(topic = "BIZ-SERVICE")
public class RequestValidAspect {

    @Around("@annotation(requestValid)")
    public Object around(ProceedingJoinPoint joinPoint, RequestValid requestValid) throws Throwable {
        // 获取方法入参、入参类型、出参类型
        Object[] args = joinPoint.getArgs();
        MethodSignature signature = (MethodSignature) joinPoint.getSignature();
        Class<?>[] parameterTypes = signature.getParameterTypes();
        Class<?> returnType = signature.getMethod().getReturnType();

        // 调用前校验每个入参
        for (Object arg : args) {
            if (arg == null) {
                continue;
            }
            try {
                if (arg instanceof List && ((List<?>) arg).size() > 0) {
                    for (int j = 0; j < ((List<?>) arg).size(); j++) {
                        validate(((List<?>) arg).get(j));
                    }
                } else {
                    validate(arg);
                }
            } catch (AlscBoltBizValidateException e) {
                // 将异常处理为需要的格式返回
            }
        }

        // 方法运行后校验是否有入参约束
        Object result;
        try {
            result = joinPoint.proceed();
        } catch (ConstraintViolationException e) {
            // 将异常处理为需要的格式返回
        }
        return result;
    }

    public static <T> void validate(T t) {
        try {
            Set<ConstraintViolation<T>> res = FastValidatorUtils.validate(t);
            if (!res.isEmpty()) {
                ConstraintViolation<T> constraintViolation = res.iterator().next();
                FastValidatorHelper.throwFastValidateException(constraintViolation);
            }

            LoggerUtil.info(log, "validator,校验成功");
        } catch (FastValidatorException e) {
            LoggerUtil.error(log, "validator,校验报错,request=[{}],result=[{}]", JSON.toJSONString(t),
                    e.getMessage());
            throw new AlscBoltBizValidateException(CommonResultCode.ILLEGAL_PARAMETERS, e.getMessage());
        }
    }
}

最后在父类/接口的方法上加上自定义的注解@RequestValid即可

    @Override
    @RequestValid
    public boolean saveCheckResult(List<CheckResultInfoModel> models) {
        //xxxx
    }

3. 最后

希望大家别再if/else走天下了,代码是我家,优雅靠大家!如果大家有更优雅的处理方式,欢迎指出~



参考链接:

[1]链接一

[2]链接二

[3]链接三

[4]链接四

[5]链接五


来源|阿里云开发者公众号

作者|葳葳

作者介绍
目录