Spring Boot 参数校验全指南
Spring Boot 参数校验全指南
在 Web 开发中，参数校验是保障接口安全性和数据合法性的关键环节。手动编写校验逻辑不仅繁琐，还容易遗漏边界情况。Spring Boot 整合了 validation 工具，提供了一套简洁高效的参数校验方案，可快速实现对简单数据类型、对象类型的校验，并支持自定义异常处理。
一、参数校验入门：简单数据类型校验
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")@ResponseBodypublic 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")@ResponseBodypublic 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 的参数校验机制通过注解化的方式，极大简化了数据合法性校验的实现。本文介绍了简单类型、对象类型的校验方法，以及异常处理方案，涵盖了从基础到实战的核心场景。合理使用参数校验，不仅能减少手动校验代码，还能提高接口的健壮性和安全性。