SpringBoot参数校验全指南分享

更新时间：2026年05月25日 10:35:13 作者：Vintanz

这篇文章主要介绍了SpringBoot参数校验全指南,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教

一、参数校验入门：简单数据类型校验

1. 引入依赖

Spring Boot 提供了 spring-boot-starter-validation 起步依赖，内置了参数校验所需的核心组件：

<!-- 参数校验依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

2. 开启参数校验

在控制器类上添加 @Validated 注解，开启参数校验功能：

@Validated // 开启参数校验
@Controller
public class TestController {
    // 接口方法...
}

3. 常用校验注解

对简单数据类型（如字符串、数字）的校验，可直接在方法参数上添加校验注解。

常用注解如下：

注解	作用	示例
@NotBlank	字符串不为 null 且去除空格后不为空串	@NotBlank String username
@NotNull	对象不为 null（适用于包装类）	@NotNull Integer age
@NotEmpty	集合不为 null 且不为空	@NotEmpty List<String> ids
@Min	数字最小值	@Min(0) Integer score
@Max	数字最大值	@Max(150) Integer age
@Email	字符串符合邮箱格式	@Email String email
@Length	字符串长度在指定范围内	@Length(min=2, max=10) String name

4. 简单类型校验示例

@Validated
@Controller
public class TestController {
    @RequestMapping("/user")
    @ResponseBody
    public String addUser(
        @NotBlank(message = "用户名不能为空") String username, // 非空校验
        @NotNull(message = "年龄不能为空") @Min(0) @Max(150) Integer age, // 非空+范围校验
        @Email(message = "邮箱格式不正确") String email // 格式校验
    ) {
        return "参数校验通过：" + username + ", " + age + ", " + email;
    }
}

message 属性用于自定义校验失败时的提示信息。
当参数不符合校验规则时，会抛出 ConstraintViolationException 异常。

二、异常处理：统一响应错误信息

参数校验失败后，Spring Boot 会默认抛出异常并返回 400 错误，但默认的错误信息不够友好。我们可以通过以下两种方式统一处理校验异常：

1. 自定义错误页面（适用于前后端不分离）

Spring Boot 会自动跳转至 src/main/resources/templates/error.html 页面，可在该页面展示友好的错误提示：

<!-- error.html -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>错误提示</title>
</head>
<body>
    <h1>参数错误</h1>
    <p>请检查输入的参数是否符合要求</p>
</body>
</html>

2. 全局异常处理器（适用于前后端分离）

通过 @ControllerAdvice 定义全局异常处理器，捕获校验异常并返回 JSON 格式的错误信息：

@ControllerAdvice
@ResponseBody
public class GlobalExceptionHandler {
    // 处理简单类型参数校验异常
    @ExceptionHandler(ConstraintViolationException.class)
    public Map<String, String> handleConstraintViolationException(ConstraintViolationException e) {
        Map<String, String> errorMap = new HashMap<>();
        // 获取所有校验失败的信息
        e.getConstraintViolations().forEach(violation -> {
            String field = violation.getPropertyPath().toString(); // 参数名
            String message = violation.getMessage(); // 错误信息
            errorMap.put(field, message);
        });
        return errorMap;
    }
}

当参数校验失败时，会返回类似以下的 JSON 响应：

{
  "username": "用户名不能为空",
  "email": "邮箱格式不正确"
}

三、对象类型参数校验

对于复杂业务场景，接口通常接收对象类型的参数（如用户注册信息、订单信息）。

此时需对对象的每个属性进行校验，步骤如下：

1. 定义实体类并添加校验注解

在实体类的字段上添加校验注解，指定校验规则和错误提示：

public class User {
    @NotNull(message = "ID不能为空")
    private Integer id;

    @NotBlank(message = "姓名不能为空")
    @Length(min = 2, max = 10, message = "姓名长度必须在2-10之间")
    private String name;

    @NotNull(message = "年龄不能为空")
    @Min(value = 0, message = "年龄不能为负数")
    @Max(value = 150, message = "年龄不能超过150")
    private Integer age;

    // getter + setter（必须存在，否则校验不生效）
}

2. 在控制器中校验对象

在控制器方法的对象参数前添加 @Validated 注解，并通过 BindingResult 捕获校验结果：

@Controller
public class UserController {
    @RequestMapping("/addUser")
    @ResponseBody
    public String addUser(
        @Validated User user, // 开启对象校验
        BindingResult result // 用于接收校验结果
    ) {
        // 判断是否有校验失败
        if (result.hasErrors()) {
            // 收集所有错误信息
            StringBuilder errorMsg = new StringBuilder();
            result.getAllErrors().forEach(error -> {
                FieldError fieldError = (FieldError) error;
                errorMsg.append(fieldError.getField()).append(":").append(fieldError.getDefaultMessage()).append("; ");
            });
            return "参数错误：" + errorMsg.toString();
        }
        // 校验通过，处理业务逻辑
        return "用户添加成功：" + user.getName();
    }
}

@Validated 用于开启对象的属性校验。
BindingResult 必须紧跟在被校验对象之后，用于接收校验结果，避免异常直接抛出。

四、常见问题与最佳实践

1. 校验注解不生效？

确保已添加 spring-boot-starter-validation 依赖。
控制器类上是否添加 @Validated 注解（简单类型校验必需）。
对象类型校验时，是否在参数前添加 @Validated 注解，且实体类有 getter/setter 方法。

2. 如何自定义校验规则？

除了内置注解，还可通过 @Pattern 注解自定义正则校验，例如校验手机号：

@Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
private String phone;

3. 全局异常处理器的优势

使用 @ControllerAdvice 定义全局异常处理器，可统一处理所有校验异常，避免在每个接口中重复编写错误处理逻辑，提高代码复用性。

总结

Spring Boot 的参数校验机制通过注解化的方式，极大简化了数据合法性校验的实现。

本文介绍了简单类型、对象类型的校验方法，以及异常处理方案，涵盖了从基础到实战的核心场景。合理使用参数校验，不仅能减少手动校验代码，还能提高接口的健壮性和安全性。

以上为个人经验，希望能给大家一个参考，也希望大家多多支持脚本之家。

您可能感兴趣的文章:

selenium+java破解极验滑动验证码的示例代码
本篇文章主要介绍了selenium+java破解极验滑动验证码的示例代码，小编觉得挺不错的，现在分享给大家，也给大家做个参考。一起跟随小编过来看看吧
2018-01-01
解决IDEA删除子模块并重建后MAVEN无法识别的问题
这篇文章主要介绍了解决IDEA删除子模块并重建后MAVEN无法识别的问题，具有很好的参考价值，希望对大家有所帮助。一起跟随小编过来看看吧
2021-02-02
Java Maven settings.xml中私有仓库配置详解
这篇文章主要介绍了详解Maven settings.xml配置，小编觉得挺不错的，现在分享给大家，也给大家做个参考。一起跟随小编过来看看吧
2021-10-10
springboot + jpa实现删除数据的操作代码
这篇文章主要介绍了springboot + jpa实现删除数据的操作代码,本文通过实例代码给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价值,需要的朋友参考下吧
2024-05-05
一文详解Spring 中的顺序问题
本文主要介绍了Spring 中的顺序问题，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
2023-05-05
IDEA 2023创建JSP项目的完整步骤教程
这篇文章主要介绍了IDEA 2023创建JSP项目的完整步骤教程,创建项目需要经过新建项目、设置项目名称和路径、选择JDK版本、添加模块和工件、配置Tomcat服务器等步骤,文中通过图文介绍的非常详细,需要的朋友可以参考下
2024-10-10
用Java进行zip文件压缩与解压缩
这篇文章主要介绍了用Java进行zip文件压缩与解压缩的方法，帮助大家更好的理解和使用Java，感兴趣的朋友可以了解下
2020-12-12
Python中scrapy框架的ltem和scrapy.Request详解
这篇文章主要介绍了Python中scrapy框架的ltem和scrapy.Request详解,Item是保存爬取数据的容器,它的使用方法和字典类似,不过,相比字典,Item提供了额外的保护机制,可以避免拼写错误或者定义字段错误,需要的朋友可以参考下
2023-09-09
java迭代器基础知识点总结
在本篇内容里小编给大家整理了一篇关于java迭代器基础知识点总结内容，有兴趣的朋友们可以学习参考下。
2021-01-01
java提取字符串中数字string以及获取字符串中的整数或小数
这篇文章主要给大家介绍了关于java提取字符串中数字string以及获取字符串中的整数或小数的相关资料,需要的朋友可以参考下
2023-08-08