spring boot 校验注解 springboot参数校验注解

转载

冷月星 2023-07-28 19:11:46

文章标签 spring boot 校验注解异常处理添加用户自定义 文章分类 spring boot 后端开发

平时在开发接口的时候，经常会需要对参数进行校验，这里提供两种处理校验逻辑的方式。一种是使用Hibernate Validator来处理，另一种是使用全局异常来处理，下面我们讲下这两种方式的用法。

Hibernate Validator

Hibernate Validator是SpringBoot内置的校验框架，只要集成了SpringBoot就自动集成了它，就可以在对象上面使用它提供的注解来完成参数校验。

常用注解

我们先来了解下常用的注解，对Hibernate Validator所提供的校验功能有个印象。

@Null：被注释的属性必须为null；
@NotNull：被注释的属性不能为null；
@AssertTrue：被注释的属性必须为true；
@AssertFalse：被注释的属性必须为false；
@Min：被注释的属性必须大于等于其value值；
@Max：被注释的属性必须小于等于其value值；
@Size：被注释的属性必须在其min和max值之间；
@Pattern：被注释的属性必须符合其regexp所定义的正则表达式；
@NotBlank：被注释的字符串不能为空字符串；
@NotEmpty：被注释的属性不能为空；
@Email：被注释的属性必须符合邮箱格式。

使用方式

接下来以添加用户接口的参数校验为例来讲解下Hibernate Validator的使用方法，其中涉及到一些AOP的知识，没有接触过的同学可以去SpringBoot官网查看文档

首先我们需要在添加用户接口的参数UserParam中添加校验注解，用于确定属性的校验规则及校验失败后需要返回的信息；

/**
 * 用户传递参数
 */
public class UserParam {
    @ApiModelProperty(value = "用户名称",required = true)
    @NotEmpty(message = "用户名称不能为空")
    private String username;
    @ApiModelProperty(value = "密码", required = true)
    @NotEmpty
    private String password;    
    @ApiModelProperty(value = "年龄")
    @Min(value = 0, message = "年龄最小为0")
    private Integer age;
    @ApiModelProperty(value = "用户头像",required = true)
    @NotEmpty(message = "用户头像不能为空")
    private String icon;

   //省略Getter和Setter方法...
}

然后在添加用户的接口中添加@Validated注解，并注入一个BindingResult参数；

/**
 * 用户功能Controller
 */
@Controller
@Api(tags = "UserController", description = "用户管理")
@RequestMapping("/user")
public class  UserController {
    @Autowired
    private UserServiceuserService;

    @ApiOperation(value = "添加用户")
    @RequestMapping(value = "/create", method = RequestMethod.POST)
    @ResponseBody
    public CommonResult create(@Validated @RequestBody UserParam user, BindingResult result) {
        CommonResult commonResult;
        int count = userService.createUser(user);
        if (count == 1) {
            commonResult = CommonResult.success(count);
        } else {
            commonResult = CommonResult.failed();
        }
        return commonResult;
    }
}

然后在整个Controller层创建一个切面，在其环绕通知中获取到注入的BindingResult对象，通过hasErrors方法判断校验是否通过，如果有错误信息直接返回错误信息，验证通过则放行；

/**
 * HibernateValidator错误结果处理切面
 */
@Aspect
@Component
@Order(2)
public class BindingResultAspect {
    @Pointcut("execution(public * com.demo.test.controller.*.*(..))")
    public void BindingResult() {
    }

    @Around("BindingResult()")
    public Object doAround(ProceedingJoinPoint joinPoint) throws Throwable {
        Object[] args = joinPoint.getArgs();
        for (Object arg : args) {
            if (arg instanceof BindingResult) {
                BindingResult result = (BindingResult) arg;
                if (result.hasErrors()) {
                    FieldError fieldError = result.getFieldError();
                    if(fieldError!=null){
                        return CommonResult.validateFailed(fieldError.getDefaultMessage());
                    }else{
                        return CommonResult.validateFailed();
                    }
                }
            }
        }
        return joinPoint.proceed();
    }
}

使用切面的话，由于每个校验方法中都需要注入BindingResult对象，这样会导致很多重复工作，其实当校验失败时，SpringBoot默认会抛出MethodArgumentNotValidException或BindException异常，我们只要全局处理该异常依然可以得到校验失败信息。

/**
 * 全局异常处理
 */
@ControllerAdvice
public class GlobalExceptionHandler {

   @ResponseBody
   @ExceptionHandler(value = MethodArgumentNotValidException.class)
   public R handleValidException(MethodArgumentNotValidException e) {
       BindingResult bindingResult = e.getBindingResult();
       String message = null;
       if (bindingResult.hasErrors()) {
           FieldError fieldError = bindingResult.getFieldError();
           if (fieldError != null) {
               message = fieldError.getField()+fieldError.getDefaultMessage();
           }
       }
       return CommonResult.failed(message);
   }

    @ResponseBody
    @ExceptionHandler(value = BindException.class)
    public R handleValidException(BindException e) {
        BindingResult bindingResult = e.getBindingResult();
        String message = null;
        if (bindingResult.hasErrors()) {
            FieldError fieldError = bindingResult.getFieldError();
            if (fieldError != null) {
                message = fieldError.getField()+fieldError.getDefaultMessage();
            }
        }
        return Response.failed(message);
    }   
}

由于SpringBoot 2.3版本默认移除了校验功能，如果想要开启的话需要添加如下依赖。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

自定义注解

有时候框架提供的校验注解并不能满足我们的需要，此时我们就需要自定义校验注解。比如还是上面的添加品牌，此时有个参数showStatus，我们希望它只能是0或者1，不能是其他数字，此时可以使用自定义注解来实现该功能。

首先自定义一个校验注解类FlagValidator，然后添加@Constraint注解，使用它的validatedBy属性指定校验逻辑的具体实现类；

/**
 * 用户验证状态是否在指定范围内的注解
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD,ElementType.PARAMETER})
@Constraint(validatedBy = FlagValidatorClass.class)
public @interface FlagValidator {
    String[] value() default {};

    String message() default "flag is not found";

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

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

然后创建FlagValidatorClass作为校验逻辑的具体实现类，实现ConstraintValidator接口，这里需要指定两个泛型参数，第一个需要指定为你自定义的校验注解类，第二个指定为你要校验属性的类型，isValid方法中就是具体的校验逻辑。

/**
 * 状态标记校验器
 */
public class FlagValidatorClass implements ConstraintValidator<FlagValidator,Integer> {
    private String[] values;
    @Override
    public void initialize(FlagValidator flagValidator) {
        this.values = flagValidator.value();
    }

    @Override
    public boolean isValid(Integer value, ConstraintValidatorContext constraintValidatorContext) {
        boolean isValid = false;
        if(value==null){
            //当状态为空时使用默认值
            return true;
        }
        for(int i=0;i<values.length;i++){
            if(values[i].equals(String.valueOf(value))){
                isValid = true;
                break;
            }
        }
        return isValid;
    }
}

接下来就能在传参对象中使用该注解了；

/**
 * 用户传递参数
 */
public class UserParam {

    @ApiModelProperty(value = "用户账户状态是否正常")
    @FlagValidator(value = {"0","1"}, message = "账户状态不正常，请联系管理员")
    private Integer Status;

   //省略Getter和Setter方法...
}

优缺点

这种方式的优点是可以使用注解来实现参数校验，不需要一些重复的校验逻辑，但也有一些缺点，比如需要在Controller的方法中额外注入一个BindingResult对象，只支持一些简单的校验，涉及到要查询数据库的校验就无法满足。

全局异常处理

使用全局异常处理来处理校验逻辑的思路很简单，首先我们需要通过@ControllerAdvice注解定义一个全局异常的处理类，然后自定义一个校验异常，当我们在Controller中校验失败时，直接抛出该异常，这样就能达到校验失败返回错误信息的目的。

使用到的注解

@ControllerAdvice：类似于@Component注解，可以指定一个组件，这个组件主要用于增强@Controller注解修饰的类的功能，比如说进行全局异常处理。
@ExceptionHandler：用来修饰全局异常处理的方法，可以指定异常的类型。

使用方式

首先我们需要自定义一个异常类ApiException，当我们校验失败时抛出该异常：

/**
 * 自定义API异常
 */
public class ApiException extends RuntimeException {
    private IErrorCode errorCode;

    public ApiException(IErrorCode errorCode) {
        super(errorCode.getMessage());
        this.errorCode = errorCode;
    }

    public ApiException(String message) {
        super(message);
    }

    public ApiException(Throwable cause) {
        super(cause);
    }

    public ApiException(String message, Throwable cause) {
        super(message, cause);
    }

    public IErrorCode getErrorCode() {
        return errorCode;
    }
}

然后创建一个断言处理类Asserts，用于抛出各种ApiException；

/**
 * 断言处理类，用于抛出各种API异常
 */
public class Asserts {
    public static void fail(String message) {
        throw new ApiException(message);
    }

    public static void fail(IErrorCode errorCode) {
        throw new ApiException(errorCode);
    }
}

然后再创建我们的全局异常处理类GlobalExceptionHandler，用于处理全局异常，并返回封装好的CommonResult对象；

/**
 * 全局异常处理
 */
@ControllerAdvice
public class GlobalExceptionHandler {

    @ResponseBody
    @ExceptionHandler(value = ApiException.class)
    public CommonResult handle(ApiException e) {
        if (e.getErrorCode() != null) {
            return CommonResult.failed(e.getErrorCode());
        }
        return CommonResult.failed(e.getMessage());
    }
}

这里以添加用户为例，我们先对比下改进前后的代码，首先看Controller层代码。改进后只要Service中的方法执行成功就表示添加用户成功，因为添加不成功的话会直接抛出ApiException从而返回错误信息；

/**
 * 用户管理Controller
 */
@Controller
@Api(tags = "UserController", description = "用户管理")
@RequestMapping("/user")
public class UserController {
    @Autowired
    private UserService userService;

    //改进前
    @ApiOperation("添加用户")
    @RequestMapping(value = "/add/{username}", method = RequestMethod.POST)
    @ResponseBody
    public CommonResult add(@PathVariable String username) {
        return userService.add(username);
    }

    //改进后
    @ApiOperation("添加用户")
    @RequestMapping(value = "/add/{username}", method = RequestMethod.POST)
    @ResponseBody
    public CommonResult add(@PathVariable String username) {
        user.add(username);
        return CommonResult.success(null,"添加成功");
    }    
}

再看下Service接口中的代码，区别在于返回结果，改进后返回的是void。其实CommonResult的作用本来就是为了把Service中获取到的数据封装成统一返回结果，改进前的做法违背了这个原则，改进后的做法解决了这个问题；

/**
 * 用户管理Service
 */
public interface UserService {
    /**
     * 添加用户（改进前）
     */
    @Transactional
    CommonResult add(String username);

    /**
     * 添加用户（改进后）
     */
    @Transactional
    void add(String username);
}