前言
在日常的开发工作中,为了程序的健壮性,大部分方法都需要进行入参数据校验。最直接的当然是在相应方法内对数据进行手动校验,但是这样代码里就会有很多冗余繁琐的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.不易复用:其他比如更新用户信息的方法,可能也会有类似的参数校验。如果也手动校验的话,会存在很多重复代码。
实践
咱就是说,有spring boot 自带的spring validation,为啥不用呢?
Java在早在2009年就提出了 Bean Validation(JSR)[1]规范,其中定义了一系列的校验注解,比如 @NotEmpty、@NotNull等,支持通过注解的方式对字段进行校验,避免在业务逻辑中耦合冗余的校验逻辑。
不过,以上注解本身不做校验,只是能给开发者做个提醒。如果需要达到参数校验的目的,还需要其他配置。话不多说,先往下看使用姿势。
Controller方法参数校验
效果示例
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和约束注解,就非常简单明了、优雅地完成了方法参数校验。
而且,假如以后入参对象里新增了参数,只需要顺便添加一个注解,而不用去改业务代码,稳!
@Valid 和 @Validated
-
@Valid [3]注解,是 Bean Validation 所定义,可以添加在普通方法、构造方法、方法参数、方法返回、成员变量上,表示它们需要进行约束校验。
-
@Validated [4]注解,是 Spring Validation 所定义,可以添加在类、方法参数、普通方法上,表示它们需要进行约束校验。
两者的区别在于 @Validated 有 value 属性,支持分组校验,即根据不同的分组采用不同的校验机制,@Valid 可以添加在成员变量上,支持嵌套校验。所以建议的使用方式就是:启动校验(即 Controller 层)时使用 @Validated 注解,嵌套校验时使用 @Valid 注解,这样就能同时使用分组校验和嵌套校验功能。
分组校验
但是,对于同个参数,不同的场景可能需要不同的校验,这时候就可以用分组校验能力。
比如创建 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);
}
}
自定义校验注解
还有,如果现有的基础校验注解没法满足校验需求,那就可以使用自定义注解[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": {}
}
校验原理
太长了,看不明白了~~~~
有兴趣的可以打开原文学习,我自己也做个记录,下次再来看看@!!@
摘自“阿里技术”公众号,原文地址:每天一个摆脱if-else工程师的技巧——优雅的参数校验