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

jupiter
2023-09-01 / 0 评论 / 119 阅读 / 正在检测是否收录...
温馨提示:
本文最后更新于2023年09月01日,已超过287天没有更新,若内容或图片失效,请留言反馈。

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 代码实现

  • vo
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对象,ValidCreateVOValidEditVO来处理这种场景,这样确实也能实现效果,但是会造成类膨胀,而且极其容易被开发老鸟们嘲笑。

其实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 验证测试

  • vo
@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

参考资料

  1. SpringBoot 如何进行参数校验,老鸟们都这么玩的!-阿里云开发者社区 (aliyun.com)
  2. SpringBoot 的请求参数校验注解_springboot 校验长度注解_千筠Wyman的博客-CSDN博客
  3. BindException、ConstraintViolationException、MethodArgumentNotValidException入参验证异常分析和全局异常处理解决方法_wzq_55552的博客-CSDN博客
  4. Spring的全局(统一)异常处理_spring全局异常处理_第1缕阳光的博客-CSDN博客
  5. Spring Boot之Validation自定义实现总结(亲测,好用)_spring boot validation 自定义_HD243608836的博客-CSDN博客
0

评论 (0)

打卡
取消