SpringBoot集成参数校验@Validated学习笔记|内含SpringBoot全局异常处理

1.为什么需要参数校验

在日常的接口开发中，为了防止非法参数对业务造成影响，经常需要对接口的参数做校验，例如登录的时候需要校验用户名密码是否为空，创建用户的时候需要校验邮件、手机号码格式是否准确。靠代码对接口参数一个个校验的话就太繁琐了，代码可读性极差。

Validator框架就是为了解决开发人员在开发的时候少写代码，提升开发效率；Validator专门用来进行接口参数校验，例如常见的必填校验，email格式校验，用户名必须位于6到12之间等等...

Validator校验框架遵循了JSR-303验证规范（参数校验规范）, JSR是Java Specification Requests的缩写。

2.SpringBoot中集成参数校验

2.1 添加依赖

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

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

注：从springboot-2.3开始，校验包被独立成了一个starter组件，所以需要引入validation和web，而springboot-2.3之前的版本只需要引入 web 依赖就可以了。

2.2 定义要参数校验的实体类

在实际开发中对于需要校验的字段都需要设置对应的业务提示，即message属性。

常见的约束注解如下：

注解	功能
@AssertFalse	可以为null,如果不为null的话必须为false
@AssertTrue	可以为null,如果不为null的话必须为true
@DecimalMax	设置不能超过最大值
@DecimalMin	设置不能超过最小值
@Digits	设置必须是数字且数字整数的位数和小数的位数必须在指定范围内
@Future	日期必须在当前日期的未来
@Past	日期必须在当前日期的过去
@Max	最大不得超过此最大值
@Min	最大不得小于此最小值
@NotNull	不能为null，可以是空
@Null	必须为null
@Pattern	必须满足指定的正则表达式
@Size	集合、数组、map等的size()值必须在指定范围内
@Email	必须是email格式
@Length	长度必须在指定范围内
@NotBlank	字符串不能为null,字符串trim()后也不能等于“”
@NotEmpty	不能为null，集合、数组、map等size()不能为0；字符串trim()后可以等于“”
@Range	值必须在指定范围内
@URL	必须是一个URL

@Data
public class ValidVO {
    private String id;

    @Length(min = 6,max = 12,message = "appId长度必须位于6到12之间")
    private String appId;

    @NotBlank(message = "名字为必填项")
    private String name;

    @Email(message = "请填写正确的邮箱地址")
    private String email;

    private String sex;

    @NotEmpty(message = "级别不能为空")
    private String level;

}

2.3 定义Controller类进行测试

$\color{red}{注意，当使用单参数校验时需要在Controller上加上@Validated注解，否则不生效。}$

@RestController
@Slf4j
@Validated
public class ValidController {
    /**
     * RequestBody校验,使用了@RequestBody注解，用于接受前端发送的json数据
     * @param validVO
     * @return
     */
    @PostMapping("/valid/test1")
    public String test1(@Validated @RequestBody ValidVO validVO){
        log.info("validEntity is {}", validVO);
        return "test1 valid success";
    }

    /**
     * Form校验,模拟表单提交
     * @param validVO
     * @return
     */
    @PostMapping(value = "/valid/test2")
    public String test2(@Validated ValidVO validVO){
        log.info("validEntity is {}", validVO);
        return "test2 valid success";
    }

    /**
     * 单参数校验,模拟单参数提交,注意，当使用单参数校验时需要在Controller上加上@Validated注解，否则不生效。
     * @param email
     * @return
     */
    @PostMapping(value = "/valid/test3")
    public String test3(@Email String email){
        log.info("email is {}", email);
        return "email valid success";
    }
}

2.4 调用测试

2.4.1 test1

请求参数

POST http://localhost:8080/valid/test1
Content-Type: application/json

{
  "id": 1,
  "appId": "add3",
  "email": "3131243242",
  "level": "12"
}

返回结果

{
    "timestamp": "2023-09-01T02:10:41.310+00:00",
    "status": 400,
    "error": "Bad Request",
    "path": "/valid/test1"
}

控制台输出

2023-09-01T10:10:41.310+08:00  WARN 9016 --- [io-8080-exec-10] .w.s.m.s.DefaultHandlerExceptionResolver : Resolved [org.springframework.web.bind.MethodArgumentNotValidException: Validation failed for argument [0] in public java.lang.String com.example.validatedstudy.domain.controller.ValidController.test1(com.example.validatedstudy.domain.vo.ValidVO) with 3 errors: [Field error in object 'validVO' on field 'name': rejected value [null]; codes [NotBlank.validVO.name,NotBlank.name,NotBlank.java.lang.String,NotBlank]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [validVO.name,name]; arguments []; default message [name]]; default message [名字为必填项]] [Field error in object 'validVO' on field 'email': rejected value [3131243242]; codes [Email.validVO.email,Email.email,Email.java.lang.String,Email]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [validVO.email,email]; arguments []; default message [email],[Ljakarta.validation.constraints.Pattern$Flag;@4115d833,.*]; default message [请填写正确的邮箱地址]] [Field error in object 'validVO' on field 'appId': rejected value [add3]; codes [Length.validVO.appId,Length.appId,Length.java.lang.String,Length]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [validVO.appId,appId]; arguments []; default message [appId],12,6]; default message [appId长度必须位于6到12之间]] ]

2.4.2 test2

请求参数

POST http://localhost:8080/valid/test2
Content-Type: application/x-www-form-urlencoded

id=1&level=12&email=21434242341&appId=dsad

返回结果

{
    "timestamp": "2023-09-01T02:13:52.296+00:00",
    "status": 400,
    "error": "Bad Request",
    "path": "/valid/test2"
}

控制台输出

2023-09-01T10:14:16.059+08:00  WARN 9016 --- [nio-8080-exec-2] .w.s.m.s.DefaultHandlerExceptionResolver : Resolved [org.springframework.web.bind.MethodArgumentNotValidException: Validation failed for argument [0] in public java.lang.String com.example.validatedstudy.domain.controller.ValidController.test2(com.example.validatedstudy.domain.vo.ValidVO) with 3 errors: [Field error in object 'validVO' on field 'email': rejected value [21434242341]; codes [Email.validVO.email,Email.email,Email.java.lang.String,Email]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [validVO.email,email]; arguments []; default message [email],[Ljakarta.validation.constraints.Pattern$Flag;@4115d833,.*]; default message [请填写正确的邮箱地址]] [Field error in object 'validVO' on field 'name': rejected value [null]; codes [NotBlank.validVO.name,NotBlank.name,NotBlank.java.lang.String,NotBlank]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [validVO.name,name]; arguments []; default message [name]]; default message [名字为必填项]] [Field error in object 'validVO' on field 'appId': rejected value [dsad]; codes [Length.validVO.appId,Length.appId,Length.java.lang.String,Length]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [validVO.appId,appId]; arguments []; default message [appId],12,6]; default message [appId长度必须位于6到12之间]] ]

2.4.3 test3

请求参数

POST http://localhost:8080/valid/test3
Content-Type: application/x-www-form-urlencoded

email=476938977

返回结果

{
    "timestamp": "2023-09-01T01:46:03.227+00:00",
    "status": 500,
    "error": "Internal Server Error",
    "path": "/valid/test3"
}

控制台输出

akarta.validation.ConstraintViolationException: test3.email: 不是一个合法的电子邮件地址
    at org.springframework.validation.beanvalidation.MethodValidationInterceptor.invoke(MethodValidationInterceptor.java:138) ~[spring-context-6.0.10.jar:6.0.10]
    at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed(ReflectiveMethodInvocation.java:184) ~[spring-aop-6.0.10.jar:6.0.10]
    at org.
    ······

2.5 增加全局异常处理（★★★）

2.5.1 代码实现

package com.example.validatedstudy.domain.vo;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@AllArgsConstructor
@NoArgsConstructor
public class ResultDataVO<T> {
    // 状态码
    private int code;
    // 错误消息
    private String errorMsg;
    // 消息体数据
    private T data;


    /**
     * 返回默认的调用成功的响应
     */
    public static <T> ResultDataVO<T> success(){
        ResultDataVO<T> resultDataVO = new ResultDataVO<>();
        resultDataVO.setCode(200);
        return resultDataVO;
    }

    /**
     * 调用成功返回T类型的对象数据响应
     * @param data
     */
    public static <T> ResultDataVO<T> success(T data){
        return new ResultDataVO<T>(200,"",data);
    }


    /**
     * 返回默认的调用失败的响应
     */
    public static <T> ResultDataVO<T> error( ){
        return error(400, "操作失败");
    }

    /**
     * 返回带msg的调用失败的响应
     */
    public static <T> ResultDataVO<T> error( String msg){
        return error(400, msg);
    }

    /**
     * 返回指定code带msg的调用失败的响应
     */
    public static <T> ResultDataVO<T> error(int code,String msg){
        return new ResultDataVO<>(code,msg,null);
    }
}

exception

/**
 * 全局异常处理类
 */
@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler{
    /**
     * 处理所有不可知的异常
     * @param e
     * @return
     */
    @ExceptionHandler(RuntimeException.class)
    @ResponseBody
    public ResultDataVO handle(Exception e) {
        log.error("系统未知异常>>>:" + e.getMessage(), e);
        return ResultDataVO.error(e.getMessage());
    }

    /**
     * 处理参数对象javax注解异常
     */
    @ResponseBody
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResultDataVO<Object> exceptionHandler(MethodArgumentNotValidException e) {
        log.error("参数错误>>>:" + e.getMessage(), e);
        return ResultDataVO.error( e.getBindingResult().getFieldError().getDefaultMessage());
    }

    /**
     * 处理controller的@Validated注解异常
     */
    @ResponseBody
    @ExceptionHandler(ConstraintViolationException.class)
    public ResultDataVO<Object> exceptionHandler(ConstraintViolationException e) {
        log.error("参数错误>>>:" + e.getMessage(), e);
        Set<ConstraintViolation<?>> violations = e.getConstraintViolations();
        String message = violations.stream()
                .map(ConstraintViolation::getMessage)
                .collect(Collectors.joining(";"));
        return ResultDataVO.error("参数错误:" + message);
    }
}

2.5.2 调用测试

test1

请求参数

POST http://localhost:8080/valid/test1
Content-Type: application/json

{
  "id": 1,
  "appId": "add3",
  "email": "3131243242",
  "level": "12"
}

返回结果

{
    "code": 400,
    "errorMsg": "请填写正确的邮箱地址",
    "data": null
}

test2

请求参数

POST http://localhost:8080/valid/test2
Content-Type: application/x-www-form-urlencoded

id=1&level=12&email=21434242341&appId=dsad

返回结果

{
    "code": 400,
    "errorMsg": "请填写正确的邮箱地址",
    "data": null
}

test3

请求参数

POST http://localhost:8080/valid/test3
Content-Type: application/x-www-form-urlencoded

email=476938977

返回结果

{
    "code": 400,
    "errorMsg": "参数错误:不是一个合法的电子邮件地址",
    "data": null
}

3.分组校验

一个VO对象在新增的时候某些字段为必填，在更新的时候又非必填。如上面的ValidVO中 id 和 appId 属性在新增操作时都是非必填，而在编辑操作时都为必填，name在新增操作时为必填，面对这种场景你会怎么处理呢？

在实际开发中我见到很多同学都是建立两个VO对象，ValidCreateVO，ValidEditVO来处理这种场景，这样确实也能实现效果，但是会造成类膨胀，而且极其容易被开发老鸟们嘲笑。

其实Validator校验框架已经考虑到了这种场景并且提供了解决方案，就是分组校验。要使用分组校验，只需要三个步骤：

3.1 定义分组接口

定义一个分组接口ValidGroup让其继承javax.validation.groups.Default，再在分组接口中定义出多个不同的操作类型，Create，Update，Query，Delete。

public interface ValidGroup extends Default {
  
    interface Crud extends ValidGroup{
        interface Create extends Crud{

        }

        interface Update extends Crud{

        }

        interface Query extends Crud{

        }

        interface Delete extends Crud{

        }
    }
}

3.2 在模型中给参数分配分组

@Data
public class ValidVO {
    @Null(groups = ValidGroup.Crud.Create.class)
    @NotNull(groups = ValidGroup.Crud.Update.class, message = "id不能为空")
    private String id;

    @NotBlank(groups = ValidGroup.Crud.Create.class,message = "名字为必填项")
    private String name;

    @Email(message = "请填写正确的邮箱地址")
    private String email;

    private String sex;
}

3.3 给需要参数校验的方法指定分组

@RestController
@Slf4j
@Validated
public class ValidController {
    /**
     * 参数分组校验-add
     * @param validVO
     * @return
     */
    @PostMapping(value = "/valid/add")
    public String add(@Validated(value = ValidGroup.Crud.Create.class) ValidVO validVO){
        log.info("validEntity is {}", validVO);
        return "test4 valid success";
    }

    /**
     * 参数分组校验-update
     * @param validVO
     * @return
     */
    @PostMapping(value = "/valid/update")
    public String update(@Validated(value = ValidGroup.Crud.Update.class) ValidVO validVO){
        log.info("validEntity is {}", validVO);
        return "test5 valid success";
    }
}

3.4 调用测试

add

在Create时我们没有传递appId参数，校验通过。

POST http://localhost:8080/valid/add
Content-Type: application/x-www-form-urlencoded
name=javadaily&email=522246447@qq.com&sex=M

test4 valid success

update

当我们使用同样的参数调用update方法时则提示参数校验错误。

POST http://localhost:8080/valid/add
Content-Type: application/x-www-form-urlencoded
name=javadaily&email=522246447@qq.com&sex=M

{
    "code": 400,
    "errorMsg": "id不能为空",
    "data": null
}

注意事项:eg-email校验

由于email属于默认分组，而分组接口ValidGroup已经继承了Default分组，所以也是可以对email字段作参数校验的。如：

POST http://localhost:8080/valid/add
Content-Type: application/x-www-form-urlencoded
name=javadaily&email=522246447&sex=M

{
    "code": 400,
    "errorMsg": "请填写正确的邮箱地址",
    "data": null
}

但是如果ValidGroup没有继承Default分组，那在代码属性上就需要加上@Validated(value = {ValidGroup.Crud.Create.class, Default.class}才能让email字段的校验生效。

4.自定义参数校验

虽然Spring Validation 提供的注解基本上够用，但是面对复杂的定义，还是需要自己定义相关注解来实现自动校验。比如IP地址校验如何实现呢？

4.1 自定义的注解（@interface）

主要需要初始化三个参数和指定执行验证的类

message
定制化的提示信息，主要是从ValidationMessages.properties里提取，也可以依据实际情况进行定制
groups
这里主要进行将validator进行分类，不同的类group中会执行不同的validator操作
payload
主要是针对bean的，使用不多。

@Target({ElementType.FIELD})
@Retention(RUNTIME)
@Documented
@Constraint(validatedBy = IPAddressValidator.class) // 指定验证实现类
public @interface IPAddress {
    String message() default "{ipaddress is invalid}";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

4.2 自定义Validator，这个是真正进行验证的逻辑代码

主要是需要实现ConstraintValidator这个接口，以及其中的两个泛型参数，第一个为注解名称，第二个为实际字段的数据类型。

package com.example.validatedstudy.validation;
import jakarta.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidatorContext;
import java.util.regex.Pattern;

public class IPAddressValidator implements ConstraintValidator<IPAddress, String> {
    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        if ((value != null) && (!value.isEmpty())) {
            return Pattern.matches("^([1-9]|[1-9]\\d|1\\d{2}|2[0-4]\\d|25[0-5])(\\.(\\d|[1-9]\\d|1\\d{2}|2[0-4]\\d|25[0-5])){3}$", value);
        }
        return false;
    }
}

4.3 验证测试

@Data
public class IPAddressVO {
    @IPAddress
    private String ip;
}

controller

@RestController
@Slf4j
@Validated
public class ValidController {
    /**
     * 自定义参数校验 - ip校验
     * @param ipAddressVO
     * @return
     */
    @PostMapping(value = "/valid/ip")
    public String update(@Validated IPAddressVO ipAddressVO){
        log.info("validEntity is {}", ipAddressVO);
        return "test ip Validated  success";
    }
}

调用测试-失败

POST http://localhost:8080/valid/ip
Content-Type: application/x-www-form-urlencoded
ip=2.45.6

{
    "code": 400,
    "errorMsg": "{ipaddress is invalid}",
    "data": null
}

调用测试-成功

POST http://localhost:8080/valid/ip
Content-Type: application/x-www-form-urlencoded
ip=127.0.0.1

test ip Validated  success