第18章 SpringBoot集成Validation校验

最新推荐文章于 2025-04-15 11:32:18 发布

不睡觉的程序猿

最新推荐文章于 2025-04-15 11:32:18 发布

阅读量1.2k

点赞数 33

本文链接：https://blog.youkuaiyun.com/richieandndsc/article/details/143499539

版权

Spring Boot 专栏收录该内容

27 篇文章

订阅专栏

在日常的项目开发中，我们需要对用户的请求参数做合法性校验。通常采用的是在代码中手动校验数据。但是手动校验数据会带来代码冗余、错误处理不统一的缺点。Spring Boot 提供了强大的数据验证机制，使开发者能够轻松地执行验证操作。

接下来，我们创建一个 “SpringBootValidationDemo” 工程

然后我们修改编码格式以及Maven仓库地址，我们省略这个过程了。

接下来，我们修改 “pom.xml” 文件，添加Validation依赖，如下所示

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.demo</groupId>
    <artifactId>SpringBootValidationDemo</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>8</maven.compiler.source>
        <maven.compiler.target>8</maven.compiler.target>
    </properties>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.6.13</version>
        <relativePath/>
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-thymeleaf</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>
        <dependency>
            <groupId>org.hibernate.validator</groupId>
            <artifactId>hibernate-validator</artifactId>
            <version>6.0.18.Final</version>
            <scope>compile</scope>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.16</version>
        </dependency>        
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>2.7.18</version>
            </plugin>
        </plugins>
    </build>

</project>

请注意，我们增加了 “spring-boot-starter-validation” 和 “hibernate-validator” 两依赖项。

spring-boot-starter-validation 参数校验功能就是 hibernate-validator 包所提供的。Hibernate Validator是一个基于Bean Validation API的参数验证框架，它提供了丰富的约束注解和自定义验证机制。Hibernate Validator的使用非常简单，只需在用户请求实体类的字段上使用标准的 Bean Validation 注解就能定义数据的验证规则。

接下来，我们继续完善我们的工程，创建 Appliaction 入口类文件

package com.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class Application {

    public static void main(String[] args) {

        SpringApplication.run(Application.class, args);
    }
}

对于web服务来说，我们一般在Controller层一定要做参数校验的，用户请求参数分为如下两种形式：

POST或PUT请求，使用requestBody传递参数

GET请求，使用requestParam/PathVariable传递参数

接下来，我们先创建一个用户请求数据类 StudentRequest

package com.demo.data;

import lombok.Data;

import javax.validation.constraints.Max;
import javax.validation.constraints.Min;
import javax.validation.constraints.NotBlank;

@Data
public class StudentRequest {

    @NotBlank(message = "姓名不能为空")
    private String name;

    @Min(value = 18, message = "年龄最小18岁")
    @Max(value = 28, message = "年龄最大28岁")
    private Integer age;

}

在上面的数据类中，我们给“name”和“age”使用了注解“@NotBlank”，“@Min”和“@Max”。从注解名称来看，我们就能知道，@NotBlank是不能为空的验证规则，而@Min和@Max则是最小值和最大值的验证规则。如果用户请求的数据不符合验证规则的话，就会返回“message”中定义的信息了。

接下来，我们创建 StudentController 控制器

package com.demo.controller;

import com.demo.data.StudentRequest;
import org.springframework.stereotype.Controller;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.GetMapping;

import java.util.Map;

@Controller
public class StudentController {

    @GetMapping("/add")
    public String add(@Validated StudentRequest request, Map map){

        map.put("info", request);
        return "student";
    }

}

注意，这里我们使用 “@Validated” 注解来开启对 “StudentRequest” 的验证。我们还可以使用“@Valid”注解。这个@Valid是Hibernate validation使用的，而@Validated是Spring Validator使用的，可以理解 @Validation 是对@Valid 进行了二次封装。一般情况下，我们使用Spring的 “@Validated” 注解即可。

接下来，我们创建 “resources\static\index.html” 入口文件

<!doctype html>
<html lang="zh-CN">
<head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>index</title>
</head>
<body>

<a href="/add?name=张三&age=20">/add?name=张三&age=20</a>
<br />
<a href="/add?age=20">/add?age=20</a>
<br />
<a href="/add?name=&age=20">/add?name=&age=20</a>
<br />
<a href="/add?name=张三&age=50">/add?name=张三&age=50</a>
<br />

</body>
</html>

最后，我们需要创建 “resources\templates\student.html” 文件

<!doctype html>
<html lang="zh-CN" xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>student</title>
</head>
<body>

<div th:if ="${info}">
    <span th:text="${info.name}"></span>
    <span th:text="${info.age}"></span>
</div>

</body>
</html>

接下来，我们就来运行测试一下吧

我们先点击第一个正确的请求“/add?name=张三&age=20”

显示正确了，接下来点击第二个错误的请求“/add?age=20”（我们没有传递姓名字段）

页面出错了，我们查看控制台输出

显示抛出了 “org.springframework.validation.BindException” 异常。很明显，spring-boot-starter-validation参数校验不通过的结果就是抛出异常。那么我们就做一个全局异常处理器。

关于spring如何处理全局异常，请参考上一个章节：第17章 SpringBoot异常处理-优快云博客

package com.demo.exception;

import org.springframework.validation.BindException;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.servlet.ModelAndView;

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(BindException.class)
    public ModelAndView handler(BindException e) {

        e.printStackTrace();

        ModelAndView mv = new ModelAndView();
        mv.setViewName("exception");
        String message = e.getMessage();
        if (e.getBindingResult() != null &&
                e.getBindingResult().getAllErrors() != null &&
                e.getBindingResult().getAllErrors().size() > 0) {
            // 获取注解中定义的 message 信息
            message = e.getBindingResult().getAllErrors().get(0).getDefaultMessage();
        }
        mv.addObject("message", message);
        return mv;
    }

}

需要注意的是，注解校验不通过时，可能抛出的异常有BindException异常、ValidationException异常(或其子类异常)、MethodArgumentNotValidException异常，我们都要对这些异常做处理。

接下来，我们需要创建 “resources\templates\exception.html” 文件

<!doctype html>
<html lang="zh-CN" xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>exception</title>
</head>
<body>

<div th:text="${message}"></div>

</body>
</html>

最后，我们再来测试一下吧

其实，我们的 “@NotBlank” ，“@Min” 或 “@Max” 注解也可以直接应用到方法的参数上面

package com.demo.controller;

import com.demo.data.StudentRequest;
import org.springframework.stereotype.Controller;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.GetMapping;

import javax.validation.constraints.Max;
import javax.validation.constraints.Min;
import javax.validation.constraints.NotBlank;
import java.util.Map;

@Validated
@Controller
public class StudentController {

    @GetMapping("/add")
    public String add(@Validated StudentRequest request, Map map){

        map.put("info", request);
        return "student";
    }

    @GetMapping("/test")
    public String test(
            @NotBlank(message = "姓名不能为空") String name,
            @Min(value = 18, message = "年龄最小18岁")
            @Max(value = 28, message = "年龄最大28岁") Integer age, Map map){

        StudentRequest request = new StudentRequest();
        request.setName(name);
        request.setAge(age);
        map.put("info", request);
        return "student";
    }

}

注意，我们需要使用“@Validated”注解到控制器 “StudentController” 类上。

接下来，我们修改 “resources\static\index.html” 入口文件

<a href="/add?name=张三&age=20">/add?name=张三&age=20</a>
<br />
<a href="/add?age=20">/add?age=20</a>
<br />
<a href="/add?name=&age=20">/add?name=&age=20</a>
<br />
<a href="/test?name=张三&age=50">/test?name=张三&age=50</a>
<br />

我们测试一下 “/test?name=张三&age=50” 请求接口

页面出错了，我们查看一下控制台日志

我们可以看到抛出了“ConstraintViolationException”异常。我们需要在全局异常处理器GlobalExceptionHandler中来处理这个“ConstraintViolationException”异常。

package com.demo.exception;

import org.springframework.validation.BindException;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.servlet.ModelAndView;

import javax.validation.ConstraintViolation;
import javax.validation.ConstraintViolationException;
import java.util.stream.Collectors;

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(BindException.class)
    public ModelAndView handler(BindException e) {

        e.printStackTrace();

        ModelAndView mv = new ModelAndView();
        mv.setViewName("exception");
        String message = e.getMessage();
        if (e.getBindingResult() != null &&
                e.getBindingResult().getAllErrors() != null &&
                e.getBindingResult().getAllErrors().size() > 0) {
            // 获取注解中定义的 message 信息
            message = e.getBindingResult().getAllErrors().get(0).getDefaultMessage();
        }
        mv.addObject("message", message);
        return mv;
    }

    @ExceptionHandler(ConstraintViolationException.class)
    public ModelAndView handler(ConstraintViolationException e) {

        e.printStackTrace();

        ModelAndView mv = new ModelAndView();
        mv.setViewName("exception");
        String message = e.getConstraintViolations().stream().map(ConstraintViolation::getMessage).collect(Collectors.joining());
        mv.addObject("message", message);
        return mv;
    }
    
}

接下来，我们重新运行测试下

另外，对于 POST或PUT 请求，我们的控制器会使用 @requestBody 接收json类型参数。如果校验失败，会抛出 MethodArgumentNotValidException 异常。我们也一起处理吧。

package com.demo.exception;

import org.springframework.validation.BindException;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.servlet.ModelAndView;

import javax.validation.ConstraintViolation;
import javax.validation.ConstraintViolationException;
import java.util.stream.Collectors;

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(BindException.class)
    public ModelAndView handler(BindException e) {

        e.printStackTrace();

        ModelAndView mv = new ModelAndView();
        mv.setViewName("exception");
        String message = e.getMessage();
        if (e.getBindingResult() != null &&
                e.getBindingResult().getAllErrors() != null &&
                e.getBindingResult().getAllErrors().size() > 0) {
            // 获取注解中定义的 message 信息
            message = e.getBindingResult().getAllErrors().get(0).getDefaultMessage();
        }
        mv.addObject("message", message);
        return mv;
    }

    @ExceptionHandler(ConstraintViolationException.class)
    public ModelAndView handler(ConstraintViolationException e) {

        e.printStackTrace();

        ModelAndView mv = new ModelAndView();
        mv.setViewName("exception");
        String message = e.getConstraintViolations().stream().map(ConstraintViolation::getMessage).collect(Collectors.joining());
        mv.addObject("message", message);
        return mv;
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ModelAndView handler(MethodArgumentNotValidException e) {

        e.printStackTrace();

        ModelAndView mv = new ModelAndView();
        mv.setViewName("exception");
        String message = e.getBindingResult().getFieldError().getDefaultMessage();
        mv.addObject("message", message);
        return mv;
    }

}

还有类似于“HttpRequestMethodNotSupportedException”，“MissingPathVariableException”， “MethodArgumentTypeMismatchException” 等异常，大家也可以处理一起。

接下来，我们介绍一下 spring-boot-starter-validation 提供的常用注解

@NotNull：校验字段值不能为 null。

@NotNull(message = "姓名不存在")
private String name;

@NotBlank：校验字符串值不能为 null 或空字符串。

@NotBlank(message = "姓名不能为空")
private String name;

NotEmpty：校验集合元素或数组元素或者字符串是否非空。

@NotEmpty(message = "列表元素不能为空")
private List<String> items;

@Length：校验字符串元素的长度。

@Length(min = 6, max = 12, message = "密码长度为6-12位")
private String password;

@Size：校验集合元素个数或字符串的长度在指定范围内。

@Size(min = 1, max = 10, message = "集合元素数量必须是1-10位")
private List<String> items;

@Min：校验数字元素的最小值。

@Min(value = 18, message = "年龄最小18岁")
private int age;

@Max：校验数字元素的最大值。

@Max(value = 60, message = "年龄最大60岁")
private int age;

@Pattern：根据正则表达式校验字符串元素的格式。

@Pattern(regexp = "[a-zA-Z0-9]+", message = "用户名必须是数字字母组合")
private String username;

如果官方提供可用的校验注解不能满足我们的需要，我们自己可以定义一个自定义校验器。

package com.demo.validation;

import javax.validation.Constraint;
import javax.validation.Payload;
import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER})
@Retention(RUNTIME)
@Documented
@Constraint(validatedBy = {MyCustomerValidationImpl.class})
public @interface MyCustomerValidation {
    
    String message() default "";
    Class<?>[] groups() default { };
    Class<? extends Payload>[] payload() default { };

}

我们定义了一个 “MyCustomerValidation” 注解

package com.demo.validation;

import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;

public class MyCustomerValidationImpl implements ConstraintValidator<MyCustomerValidation, String> {

    @Override
    public boolean isValid(String param, ConstraintValidatorContext context) {
        
        if(param == null || param.length() <= 0) return false;
        return true;
    }
}

我们定义了校验规则，它的参数是一个字符串类型，如果为空的话，则校验不通过。

当然，我们可以根据自己的修在这里完成复杂的校验规则。

接下来，我们就使用一下这个 “@MyCustomerValidation” 注解。

    @GetMapping("/mytest")
    public String mytest(@MyCustomerValidation(message = "姓名不能为空") String name, Map map){

        StudentRequest request = new StudentRequest();
        request.setName(name);
        request.setAge(20);
        map.put("info", request);
        return "student";
    }

接下来，我们修改 “resources\static\index.html” 入口文件

<a href="/add?name=张三&age=20">/add?name=张三&age=20</a>
<br />
<a href="/add?age=20">/add?age=20</a>
<br />
<a href="/add?name=&age=20">/add?name=&age=20</a>
<br />
<a href="/test?name=张三&age=50">/test?name=张三&age=50</a>
<br />
<a href="/mytest?name=">/mytest?name=</a>
<br />

我们重新运行测试一下