Springboot优雅的参数校验(一)

超、凢脫俗 2024-03-31 14:46 84阅读 0赞

**目录**

前言

1. 依赖引入

2. 参数形式

3. 常用到的约束注解

4. 参数基础校验

4.1 @RequestBody参数

4.2 @RequestParam参数/@PathVariable参数

4.3 异常统一处理

5. 嵌套校验

6. 分组校验

--------------------

## 前言 ##

在后端的接口开发过程，实际上每一个接口都或多或少有不同规则的参数校验，有一些是基础校验，如非空校验、长度校验、大小校验、格式校验；也有一些校验是业务校验，如学号不能重重复、手机号不能重复注册等；对于业务校验，是需要和数据库交互才能知道校验结果；对于参数的基础校验，是有一些共有特征可以抽象出来，可以做成一个通用模板（java就是一种面向对象的编程语言，还记得天天快要说烂问烂的面向对象的三大特性吗？）。基于实际场景的需要，java API中定义了一些Bean校验的规范标准（JSR303:validation-api），但是没有具体实现，不过hibernate validation和spring validation都提供了一些比较优秀的实现。如果在项目里，你还是像类似这样的方式来进行参数校验就太low了，活该加班到天亮（当然如果你所在公司目前仍然用统计代码量来考核你的工作，就算我没说，你可以继续使用这种方式）。

@PostMapping("/add")
    public String add(Student student) {
        if (null == student) {
            throw new RuntimeException("学生不为空");
        }
        if ("".equals(student.getStuCode())) {
            throw new RuntimeException("学号不能为空");
        }
        if ("".equals(student.getStuName())) {
            throw new RuntimeException("学生姓名不能为空");
        }
        if (null == student.getTeacher()) {
            throw new RuntimeException("学生的老师的不能为空");
        }
        if ("".equals(student.getTeacher().getTecName())) {
            throw new RuntimeException("学生的老师的姓名不能为空");
        }
        if ("".equals(student.getTeacher().getSubject())) {
            throw new RuntimeException("学生的老师的所授科目不为能空");
        }
        return "success";
    }

## 1. 依赖引入 ##

分享的这篇文章里的校验参数注解使用方法，我是在一个springboot项目里亲自重新测试验证过的，springboot的版本是2.3.9.RELEASE，另外也引入了关于参数校验的starter包，这样就不用额外去引关于参数校验的其他包了；

<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter</artifactId>
 </dependency>
 <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>
 <version>2.3.9.RELEASE</version>
 </dependency>

## 2. 参数形式 ##

在java项目中，前端请求后端的接口中，常用的请求类型主要是post和get。

在post请求中，通常使用requestBody传递参数，即前端以json报文的格式传递到后端controller层，spring会把json报文自动映射到@RequestBody修饰的形参实例；

在get请求中，通常使用requestParam/PathVariable传递参数，其中requestParam是指前端以key-value的形式把参数传递到后端，spring会把参数自动映射到@RequestParam修饰的形参数实例对象（@RequestParam可以，也可以没有，只要参数key与controller层方法内形参类型的属性名称可以对应的上）；@PathVariable是指spring可以将请求URL中占位符参数绑定到controller层方法的形参上；

## 3. 常用到的约束注解 ##

<table> 
 <tbody> 
 <tr> 
 <td> @Null </td> 
 <td> 被注释的元素必须为 null </td> 
 </tr> 
 <tr> 
 <td> @NotNull </td> 
 <td> 被注释的元素必须不为 null </td> 
 </tr> 
 <tr> 
 <td> @AssertTrue </td> 
 <td> 被注释的元素必须为 true </td> 
 </tr> 
 <tr> 
 <td> @AssertFalse </td> 
 <td> 被注释的元素必须为 false </td> 
 </tr> 
 <tr> 
 <td> @Min(value) </td> 
 <td> 被注释的元素必须是一个数字，其值必须大于等于指定的最小值 </td> 
 </tr> 
 <tr> 
 <td> @Max(value) </td> 
 <td> 被注释的元素必须是一个数字，其值必须小于等于指定的最大值 </td> 
 </tr> 
 <tr> 
 <td> @DecimalMin(value) </td> 
 <td> 被注释的元素必须是一个数字，其值必须大于等于指定的最小值 </td> 
 </tr> 
 <tr> 
 <td> @DecimalMax(value) </td> 
 <td> 被注释的元素必须是一个数字，其值必须小于等于指定的最大值 </td> 
 </tr> 
 <tr> 
 <td> @Size(max, min) </td> 
 <td> 被注释的元素的大小必须在指定的范围内 </td> 
 </tr> 
 <tr> 
 <td> @Digits (integer, fraction) </td> 
 <td> 被注释的元素必须是一个数字，其值必须在可接受的范围内 </td> 
 </tr> 
 <tr> 
 <td> @Past </td> 
 <td> 被注释的元素必须是一个过去的日期 </td> 
 </tr> 
 <tr> 
 <td> @Future </td> 
 <td> 被注释的元素必须是一个将来的日期 </td> 
 </tr> 
 <tr> 
 <td> @Pattern(value) </td> 
 <td> 被注释的元素必须符合指定的正则表达式 </td> 
 </tr> 
 </tbody> 
</table>

Hibernate Validator 附加的 constraint

<table> 
 <tbody> 
 <tr> 
 <td> 注解 </td> 
 <td> 作用 </td> 
 </tr> 
 <tr> 
 <td> @Email </td> 
 <td> 被注释的元素必须是电子邮箱地址 </td> 
 </tr> 
 <tr> 
 <td> @Length(min=, max=) </td> 
 <td> 被注释的字符串的大小必须在指定的范围内 </td> 
 </tr> 
 <tr> 
 <td> @NotEmpty </td> 
 <td> 被注释的字符串的必须非空 </td> 
 </tr> 
 <tr> 
 <td> @Range(min=, max=) </td> 
 <td> 被注释的元素必须在合适的范围内 </td> 
 </tr> 
 </tbody> 
</table>

## 4. 参数基础校验 ##

参数的基础校验，通常是指的非空、长度、最大值、最小值、格式（数字、邮箱、正则）等这些场景的校验。

### 4.1 @RequestBody参数 ###

1.在controller层的方法的形参数前面加一个@Valid或@Validated的注解；

2.在用@RequestBody修饰的类的属性上加上约束注解，如@NotNull、@Length、@NotBlank；

3.@RequestBody参数在触发校验规则时，会抛出MethodArgumentNotValidException，这里使用统一的异常处理机制来处理异常；

总结：第1步的valid的作用就是一个标记，标明这个参数需要进行校验；第2步的约束注解的上注明校验的规则；第3步的统一校验机制是前后台请求后台接口时，如果校验参数的校验规则后会抛出异常，异常附带有约束注解上的提示信息，那么通过异常统一处理机制就可以统一处理异常信息，并以合适的方式返回给前台（所谓合适的方式是指异常信息的格式可以自行制定）。

@PostMapping("/add")
    public Student add( @Valid@RequestBody Student student){
        System.out.println(student.getStuName());
        return student;
    }

@Data
    public class Student  {
        @NotNull(message = "学号不能为空")
        @Length(min = 2, max = 4, message = "学号的长度范围是(2,4)")
        private String stuCode;
        @NotNull(message = "姓名不能为空")
        @Length(min = 2, max = 3, message = "姓名的长度范围是(2,3)")
        private String stuName;
    }

### 4.2 @RequestParam参数/@PathVariable参数 ###

1.在controller层的控制类上添加@Validated注解；

2.在controller层方法的校验参数上添加约束注解，如@NotNull、@Pattern；

3.@RequestParam参数/@PathVariable参数在触发校验规则时，会抛出ConstraintViolationException类型的异常，所以在统一异常处理机制中添加对这种类型异常的处理机制；

@RestController
    @RequestMapping("/student")
    @Validated
    public class StudentController {
        @GetMapping("/{sex}/info")
        public String getBySex(@PathVariable("sex") @Pattern(regexp = "boy||girl",message = "学生性别只能是boy或girl") String sex) {
            System.out.println("学生性别:" + sex);
        return "success";
        }
        @GetMapping("/getOne")
        public String getOne(@NotNull(message = "学生姓名不能为空") String stuName, @NotNull(message = "学生学号不能为空") String stuCode) {
            System.out.println("stuName:" + stuName + ",stuCode:" + stuCode);
        return "success";
        }
    }

### 4.3 异常统一处理 ###

@RestControllerAdvice
 public class CommonExceptionHandler {
 
 /**
 * 用于捕获@RequestBody类型参数触发校验规则抛出的异常
 *
 * @param e
 * @return
 */
 @ExceptionHandler(value = MethodArgumentNotValidException.class)
 public String handleValidException(MethodArgumentNotValidException e) {
 StringBuilder sb = new StringBuilder();
 List<ObjectError> allErrors = e.getBindingResult().getAllErrors();
 if (!CollectionUtils.isEmpty(allErrors)) {
 for (ObjectError error : allErrors) {
 sb.append(error.getDefaultMessage()).append(";");
 }
 }
 return sb.toString();
 }
 
 /**
 * 用于捕获@RequestParam/@PathVariable参数触发校验规则抛出的异常
 *
 * @param e
 * @return
 */
 @ExceptionHandler(value = ConstraintViolationException.class)
 public String handleConstraintViolationException(ConstraintViolationException e) {
 StringBuilder sb = new StringBuilder();
 Set<ConstraintViolation<?>> conSet = e.getConstraintViolations();
 for (ConstraintViolation<?> con : conSet) {
 String message = con.getMessage();
 sb.append(message).append(";");
 }
 return sb.toString();
 }
 }

## 5. 嵌套校验 ##

在实际项目中有这样一种场景，用来接收参数的类的属性字段也是一个对象，属性对象的字段也需要进行必要的参数校验，这个时候可以使用嵌套校验来解决这个问题，hibernate-validator提供了具体的解决方式。

1.在controller层方法的形参数前添加@Validated注解，如果有分组校验的场景，则注明分组信息；如果校验不需要分组，可以不注明分组信息；

2.在接收参数的类的属性是对象的字段上添加@Valide注解，这里需要注意的是一定是@Valid，不是@Validated，因为@Valid的实现是由hibernate-validator提供，有嵌套校验的能力，而@Validated是由spring-validation提供的具体实现方式，@Validated有分组校验的能力，但是没有嵌套校验的能力；（java API规范（JSR303）定义了Bean的校验标准validation-api，但是没有具体的实现，所以各有各的实现，在功能上也是有区别的）

3.嵌套属性类上的约束注解的用法，与用来接收参数的对象属性上的约束注解的用法是一样的；

总结：@Valid的实现是由hibernate-validator提供，有嵌套校验的能力，但是没有分组校验的能力，@Validated是由spring-validation提供的具体实现方式，@Validated有分组校验的能力，但是没有嵌套校验的能力，在使用的过程须特别注意，要根据实际需要进行剪裁。

@PostMapping("/addStuaAndTeach")
    public String addStuaAndTeach(@Validated(AddStuAndTeach.class) @RequestBody Student student){
        System.out.println("学生的工号:"+student.getStuCode()+",学生的老师的姓名:"+student.getTeacher().getTecName());
        return "success";
    }

@Data
    public class Student {
       
        @NotNull(message = "学生id不能为空",groups = QueryDetail.class)
        private Integer id;
        @NotNull(message = "学号不能为空",groups = AddStudent.class)
        @Length(min = 2, max = 4, message = "学号的长度范围是(2,4)")
        private String stuCode;
        @NotNull(message = "姓名不能为空",groups = AddStudent.class)
        @Length(min = 2, max = 3, message = "姓名的长度范围是(2,3)",groups = AddStudent.class)
        private String stuName;
        @Valid
        @NotNull(message = "学生的老师不能为空",groups = AddStuAndTeach.class)
        private Teacher teacher;
    }

@Data
    public class Teacher {
        @NotNull(message = "学生的老师姓名不能为空",groups = AddStuAndTeach.class)
        private String tecName;
        @NotNull(message = "学生的老师教授科目不能为空",groups = AddStuAndTeach.class)
        private String subject;
    }

public interface AddStuAndTeach {
    }

## 6. 分组校验 ##

在实际的项目中，可能多个方法使用同一个类来接收参数，但是不同的方法的校验规则又是不同的，这个时候就可以使用分组校验的方式来解决这个问题了，spring-validation提供了具体的实现方式。

1.声明分组用的接口，比如添加和查询详情的时候，校验的规则肯定是不一样的，添加的时候一般不用传id，由后台自增长生成，查询详情的时候id是必须传的；

2.在controller层方法的校验参数上添加@Validated参数，同时注解里要注明校验参数的分组信息；

3.在校验参数的类上的线束注解上，也要注明校验参数的分组信息；

总结：在接口的入口方法参数上、校验参数上都注明了分组的信息，那么接口被用的时候，就可以根据不同的分组信息执行不同约束注解的校验逻辑了，这个能力是spring-validation提供的，所以这种场景下，controller层方法的上注解要用@Validated，@Valid注解没有这种能力。

//用于添加场景参数校验分组
    public interface AddStudent {
    }

//用于查询详情场景参数校验分组
    public interface QueryDetail {
    }

@PostMapping("/add")
    public Student add(@Validated(AddStudent.class) @RequestBody Student student) {
        System.out.println(student.getStuName());
        return student;
    }
    
    @PostMapping("/detail")
    public String detail(@Validated(QueryDetail.class)@RequestBody Student student){
        System.out.println("学生id:"+student.getId());
        return "success";
    }

@Data
    public class Student {
     
        @NotNull(message = "学生id不能为空",groups = QueryDetail.class)
        private Integer id;
        @NotNull(message = "学号不能为空",groups = AddStudent.class)
        @Length(min = 2, max = 4, message = "学号的长度范围是(2,4)")
        private String stuCode;
        @NotNull(message = "姓名不能为空",groups = AddStudent.class)
        @Length(min = 2, max = 3, message = "姓名的长度范围是(2,3)",groups = AddStudent.class)
        private String stuName;

> Springboot扩展点系列实现方式、工作原理集合：
> 
> [Springboot扩展点之ApplicationContextInitializer][Springboot_ApplicationContextInitializer]
> 
> [Springboot扩展点之BeanDefinitionRegistryPostProcessor][Springboot_BeanDefinitionRegistryPostProcessor]
> 
> [Springboot扩展点之BeanFactoryPostProcessor][Springboot_BeanFactoryPostProcessor]
> 
> [Springboot扩展点之BeanPostProcessor][Springboot_BeanPostProcessor]
> 
> [Springboot扩展点之InstantiationAwareBeanPostProcessor][Springboot_InstantiationAwareBeanPostProcessor]
> 
> [Springboot扩展点之SmartInstantiationAwareBeanPostProcessor][Springboot_SmartInstantiationAwareBeanPostProcessor]
> 
> [Springboot扩展点之ApplicationContextAwareProcessor][Springboot_ApplicationContextAwareProcessor]
> 
> [Springboot扩展点之@PostConstruct][Springboot_PostConstruct]
> 
> [Springboot扩展点之InitializingBean][Springboot_InitializingBean]
> 
> [Springboot扩展点之DisposableBean][Springboot_DisposableBean]
> 
> [Springboot扩展点之SmartInitializingSingleton][Springboot_SmartInitializingSingleton]
> 
> Springboot核心功能工作原理：
> 
> [Springboot实现调度任务的工作原理][Springboot]
> 
> [Springboot事件监听机制的工作原理][Springboot 1]

[Springboot_ApplicationContextInitializer]: https://blog.csdn.net/fox9916/article/details/128522598
[Springboot_BeanDefinitionRegistryPostProcessor]: https://blog.csdn.net/fox9916/article/details/128538625
[Springboot_BeanFactoryPostProcessor]: https://blog.csdn.net/fox9916/article/details/128823328
[Springboot_BeanPostProcessor]: https://blog.csdn.net/fox9916/article/details/128917992
[Springboot_InstantiationAwareBeanPostProcessor]: https://blog.csdn.net/fox9916/article/details/128941464
[Springboot_SmartInstantiationAwareBeanPostProcessor]: https://blog.csdn.net/fox9916/article/details/128976944
[Springboot_ApplicationContextAwareProcessor]: https://blog.csdn.net/fox9916/article/details/128990305
[Springboot_PostConstruct]: https://blog.csdn.net/fox9916/article/details/128998846
[Springboot_InitializingBean]: https://blog.csdn.net/fox9916/article/details/129016083
[Springboot_DisposableBean]: https://blog.csdn.net/fox9916/article/details/129026156?spm=1001.2014.3001.5501
[Springboot_SmartInitializingSingleton]: https://blog.csdn.net/fox9916/article/details/129042652
[Springboot]: https://blog.csdn.net/fox9916/article/details/128483069
[Springboot 1]: https://blog.csdn.net/fox9916/article/details/128225155