Spring Boot整合参数校验的技术学习
引言
在软件开发中，数据校验是一个非常重要的环节，它确保了数据的完整性和安全性。Spring Boot作为一款流行的Java框架，提供了非常方便的参数校验功能。本文将详细介绍如何在Spring Boot中整合参数校验，并通过示例代码演示其使用方法。
一、依赖管理
在Spring Boot中整合参数校验的依赖管理相对简单，因为Spring Boot默认集成了Hibernate Validator作为其参数校验的支持库，对于大多数场景，无需额外配置即可直接使用。
Maven依赖示例：
org.springframework.boot
spring-boot-starter-web
org.springframework.boot
spring-boot-starter-validation
Gradle依赖示例：
// 对于Spring Boot 2.3.x及以前版本
implementation 'org.springframework.boot:spring-boot-starter-web'
// 对于Spring Boot 2.4及以上版本
implementation 'org.springframework.boot:spring-boot-starter-validation'
详细讲解：
1.默认集成：
- Spring Boot 2.x 早期版本中，spring-boot-starter-web 包含了对 spring-boot-starter-validation 的依赖，因此如果你的项目包含 web 功能，一般情况下验证功能会自动启用。
- 从 Spring Boot 2.4 开始，为了减少不必要的依赖，spring-boot-starter-web 不再默认包含验证模块，所以若你需要使用参数校验功能，需要单独引入 spring-boot-starter-validation。
2.作用：
- 引入上述依赖后，你可以在Java Bean的属性上使用JSR-303/JSR-349/JSR-380标准的注解进行参数校验，例如@NotNull、@Size、@Min等。
3.使用示例：
public class UserForm {
@NotNull(message = "用户名不能为空")
private String username;
@Size(min = 6, max = 16, message = "密码长度应在6至16个字符之间")
private String password;
// 其他属性和getter/setter...
}
@RestController
public class UserController {
@PostMapping("/register")
public ResponseEntity register(@Valid @RequestBody UserForm userForm) {
// 如果UserForm中的任何一个字段没有通过校验，Spring Boot会自动抛出MethodArgumentNotValidException异常
// 此处省略正常的注册逻辑...
return ResponseEntity.ok("注册成功");
}
}
二、注解使用
在Spring Boot中整合参数校验，注解的使用是关键部分。以下是一些常用的注解以及它们如何应用于一个简单的Java Bean（用户实体类）的例子，以及在Controller中如何使用@Valid注解触发校验的示例：
import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Size;
public class User {
// 必须存在，且不能为null
@NotNull(message = "用户名不能为空")
private String username;
// 必须存在，长度至少为3个字符，最多为20个字符
@NotBlank(message = "密码不能为空")
@Size(min = 3, max = 20, message = "密码长度应在3至20个字符之间")
private String password;
// 电子邮件地址，需符合电子邮件格式
@NotBlank(message = "邮箱不能为空")
@Email(message = "邮箱格式不正确")
private String email;
// ... getters and setters ...
}
@RestController
@RequestMapping("/users")
public class UserController {
@PostMapping("/create")
public ResponseEntity createUser(@Valid @RequestBody User user, BindingResult bindingResult) {
if (bindingResult.hasErrors()) { // 检查是否有任何校验错误
List errors = bindingResult.getAllErrors();
// 处理错误信息，例如构建一个错误响应返回给客户端
// 这里仅做示例，实际操作中可能使用全局异常处理器处理
for (ObjectError error : errors) {
System.out.println(error.getDefaultMessage());
}
return new ResponseEntity<>("Invalid input data", HttpStatus.BAD_REQUEST);
} else {
// 如果所有校验都通过，则执行用户的创建逻辑
// ...
return new ResponseEntity<>("User created successfully", HttpStatus.CREATED);
}
}
}
注解详解：
- @NotNull: 确保所标注的属性不为null。
- @NotBlank: 适用于字符串类型，除了检查空值外，还检查空白字符，确保字符串有一定的实质内容。
- @Size: 限制字符串或集合类型的大小，可以指定最小和最大长度。
- @Email: 验证字符串是否符合电子邮件地址的基本格式。
在上述例子中，@Valid 注解用于在Controller方法参数前，告诉Spring在调用方法之前先对传入的JSON请求体映射成的User对象进行参数校验。如果校验失败，BindingResult参数将会记录所有的校验错误信息，然后可以根据这些错误信息做出相应的处理。
三、分组校验 (@Validated)
在Spring Boot中，我们可以使用@Validated配合分组校验来进行更加精细的参数校验控制。分组校验允许我们根据不同的业务场景，定义不同的校验规则，并在执行校验时选择需要应用的规则集。
下面是一个分组校验的示例：
import javax.validation.groups.Default;
import javax.validation.constraints.Min;
import javax.validation.constraints.NotNull;
public class User {
// 假设在创建用户时必须提供姓名和密码
@NotNull(groups = {CreateGroup.class})
private String name;
@NotNull(groups = {CreateGroup.class})
@Min(value = 6, groups = {CreateGroup.class}) // 密码至少6位
private String password;
// 更新用户时，密码可选更新，但邮箱必须提供
@NotNull(groups = {UpdateGroup.class})
private String email;
// ... getters and setters ...
interface CreateGroup {}
interface UpdateGroup {}
}
@RestController
@Validated
public class UserController {
@PostMapping("/users")
public ResponseEntity createUser(@Validated(CreateGroup.class) @RequestBody User user) {
// 用户创建逻辑...
}
@PutMapping("/users/{id}")
public ResponseEntity updateUser(@PathVariable Long id, @Validated(UpdateGroup.class) @RequestBody User user) {
// 用户更新逻辑...
}
}
详细讲解：
- 定义了两个接口 CreateGroup 和 UpdateGroup，分别代表创建用户和更新用户的校验分组。
- 在 User 类的属性上使用 @NotNull 和 @Min 注解，并指定了它们在哪些分组中生效。例如，name 和 password 属性在 CreateGroup 分组中要求不为空且密码长度至少为6位；而 email 属性在 UpdateGroup 分组中要求不为空。
- 在 UserController 控制器类上添加 @Validated 注解，表示这个类的方法参数支持校验。
- 在具体的 createUser 和 updateUser 方法中，通过在 @Validated 注解内指定分组，来决定应该按照哪个分组的规则去校验传入的 User 实体。例如，创建用户时会执行 CreateGroup 中定义的校验规则，更新用户时则执行 UpdateGroup 中的规则。
这样，当我们发起 POST 请求创建用户时，只会校验 name 和 password 是否符合要求；而在 PUT 请求更新用户时，只会校验 email 是否有效。每个操作只执行与之相关联的校验规则。
四、自定义注解与验证器
在Spring Boot中，我们可以创建自定义的校验注解和对应的验证器，以满足特定业务场景下的参数校验需求。以下是一个自定义注解和验证器的示例：
首先，定义一个自定义注解：
import javax.validation.Constraint;
import javax.validation.Payload;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Target({ElementType.FIELD, ElementType.ANNOTATION_TYPE, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = PasswordStrengthValidator.class)
public @interface PasswordStrength {
String message() default "密码强度不够";
Class[] groups() default {};
Class[] payload() default {};
// 自定义的参数，比如密码最小长度、最少特殊字符数量等
int minLength() default 8;
int minSpecialChars() default 1;
}
接下来，创建对应的验证器类：
import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;
import java.util.regex.Pattern;
public class PasswordStrengthValidator implements ConstraintValidator {
private int minLength;
private int minSpecialChars;
private Pattern specialCharPattern = Pattern.compile("[!@#$%^&*(),.?\":{}|<>]");
@Override
public void initialize(PasswordStrength constraintAnnotation) {
minLength = constraintAnnotation.minLength();
minSpecialChars = constraintAnnotation.minSpecialChars();
}
@Override
public boolean isValid(String password, ConstraintValidatorContext context) {
// 校验密码长度
if (password == null || password.length() < minLength) {
return false;
}
// 校验特殊字符数量
int specialCharCount = (int) password.chars().filter(c -> specialCharPattern.matcher(Character.toString((char)c)).matches()).count();
return specialCharCount >= minSpecialChars;
}
}
现在，您可以在实体类中使用这个自定义注解：
public class User {
@NotBlank
private String username;
@PasswordStrength(minLength = 10, minSpecialChars = 2)
private String password;
// ... getters and setters ...
}
当进行参数校验时，Spring Boot会自动查找与注解关联的验证器类（这里是PasswordStrengthValidator），并调用其isValid方法进行验证。如果密码不符合指定的强度要求，验证器会返回false，从而触发校验失败。
请注意，自定义注解通常需要遵循Java Bean Validation规范，并实现ConstraintValidator接口来定义实际的验证逻辑。在这个例子中，我们定义了一个针对密码强度的校验，它检查密码的最小长度和最少特殊字符数。
五、方法级别校验
在Spring Boot中，方法级别的参数校验通常是指在Controller层针对HTTP请求的参数进行验证，确保传入的参数满足业务需求。
下面是一个方法级别参数校验的示例：
假设我们有一个用户登录的API接口，需要验证传入的用户名和密码是否为空：
import org.springframework.http.ResponseEntity;
import org.springframework.validation.BindingResult;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class LoginController {
@PostMapping("/login")
public ResponseEntity login(@Validated @RequestBody LoginRequest loginRequest, BindingResult bindingResult) {
if (bindingResult.hasErrors()) {
// 如果有校验错误，返回错误信息
StringBuilder errorMessage = new StringBuilder();
bindingResult.getAllErrors().forEach(error -> errorMessage.append(error.getDefaultMessage()).append(", "));
return ResponseEntity.badRequest().body(errorMessage.toString());
}
// 如果所有参数校验通过，这里继续执行登录逻辑...
// ...
return ResponseEntity.ok("Login successful");
}
}
class LoginRequest {
@NotBlank(message = "Username is required")
private String username;
@NotBlank(message = "Password is required")
private String password;
// getters and setters
}
详细讲解：
- @Validated 注解放在方法参数前，表示Spring应该对这个参数对象进行验证。这里的参数对象是LoginRequest。
- @RequestBody 表明请求体会被转换并绑定到LoginRequest对象上。
- 在LoginRequest类中，我们使用了@NotBlank注解来保证username和password字段均不为空。这些注解都是JSR-303/JSR-349/JSR-380标准的一部分，由Hibernate Validator等验证库实现。
- BindingResult 参数紧跟在需要验证的对象之后，Spring会在执行方法前尝试对前面的@RequestBody对象进行验证，并将验证结果放入BindingResult对象中。
- 在方法体内，我们检查bindingResult.hasErrors()来判断是否存在校验错误。如果有错误，就从bindingResult.getAllErrors()中获取所有的错误消息并返回给客户端。
通过这样的方式，Spring Boot可以在方法级别自动完成参数校验，提高了代码的整洁度和安全性。如果参数校验失败，Spring MVC会自动将HTTP请求的状态码设置为400 Bad Request，并将错误信息返回给客户端。
六、全局异常处理
在Spring Boot中，全局异常处理机制可以用来捕获包括参数校验失败在内的各种异常，并统一处理，返回格式化的错误信息。当参数校验失败时，Spring MVC会抛出MethodArgumentNotValidException异常，我们可以创建一个全局异常处理器来捕获并处理这个异常。
以下是一个全局异常处理类的示例：
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
@ControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity> handleValidationExceptions(MethodArgumentNotValidException ex) {
Map responseBody = new HashMap<>();
List fieldErrors = ex.getBindingResult().getFieldErrors();
responseBody.put("status", HttpStatus.BAD_REQUEST.value());
responseBody.put("message", "Validation failed");
responseBody.put("errors", fieldErrors.stream()
.collect(Collectors.toMap(
FieldError::getField,
FieldError::getDefaultMessage
))
);
return new ResponseEntity<>(responseBody, HttpStatus.BAD_REQUEST);
}
}
详细讲解：
- @ControllerAdvice 是一个用于全局处理异常的注解，它可以应用于任意类上，使得该类中的异常处理方法能够跨多个控制器处理异常。
- @ExceptionHandler(MethodArgumentNotValidException.class) 指定了该方法用于处理MethodArgumentNotValidException异常，这种异常就是当参数校验失败时抛出的。
- 在方法内部，我们首先创建了一个HashMap来存储响应体的信息，其中包括HTTP状态码（这里是400 Bad Request）、错误消息和具体的错误详情。
- 通过ex.getBindingResult().getFieldErrors()获取到所有参数校验失败的字段错误信息，将其转化为键值对形式，键是字段名称，值是默认的错误消息。
- 最后，构造一个ResponseEntity对象，其中包含格式化的错误响应，并设定状态码为400 Bad Request，然后返回。
这样一来，每当发生参数校验失败的情况，都会触发这个全局异常处理器，将错误信息格式化后返回给客户端，而不是抛出未处理的异常导致程序崩溃或显示不友好的错误信息。
七、验证流程集成
Spring Boot整合参数校验的验证流程集成主要包括三个核心步骤：定义带有校验注解的实体类、在Controller中应用@Valid注解以及处理校验失败后的异常。以下是一个完整的示例：
第一步：定义带有校验注解的实体类
import javax.validation.constraints.NotBlank;
import javax.validation.constraints.Size;
public class UserDto {
@NotBlank(message = "用户名不能为空")
private String username;
@Size(min = 6, max = 20, message = "密码长度应在6至20个字符之间")
private String password;
// 构造函数、getter和setter方法...
// 示例构造函数
public UserDto(String username, String password) {
this.username = username;
this.password = password;
}
}
第二步：在Controller中应用@Valid注解
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.validation.annotation.Validated;
import javax.validation.Valid;
@RestController
public class UserController {
@PostMapping("/users")
public ResponseEntity createUser(@Valid @RequestBody UserDto userDto, BindingResult bindingResult) {
if (bindingResult.hasErrors()) {
return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(bindingResult.getAllErrors());
}
// 如果校验通过，执行用户创建逻辑...
// userService.createUser(userDto);
return ResponseEntity.ok("User created successfully");
}
}
详细讲解：
- 在UserDto实体类中，我们使用了javax.validation包下的注解，如@NotBlank和@Size，来约束参数的合法性。
- 在UserController中，我们使用@Valid注解修饰@RequestBody的UserDto参数，这样在请求到达Controller时，Spring MVC就会自动调用验证器对传入的JSON对象进行校验。
- BindingResult参数紧跟在待校验的参数之后，Spring会将校验结果绑定到此对象上。
- 在方法体内，我们首先检查bindingResult.hasErrors()来判断是否出现校验错误。如果有错误，就返回一个包含错误详情的HTTP 400 Bad Request响应；否则，继续执行正常的业务逻辑。
第三步：处理全局校验失败的异常（可选）
虽然在上面的示例中我们在Controller方法内处理了校验失败，但也可以选择创建一个全局异常处理器来统一处理所有参数校验失败的情况：
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity handleValidationException(MethodArgumentNotValidException ex) {
// 获取错误详情
List allErrors = ex.getBindingResult().getAllErrors();
// 返回错误信息
return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(allErrors);
}
}
这样，无论在哪一个Controller中发生参数校验失败，都会被全局异常处理器捕获并返回统一格式的错误响应。
总结
通过整合Spring Boot的参数校验功能，我们可以方便地对请求参数进行校验，确保数据的完整性和安全性。在实际开发中，我们还可以根据需求自定义校验规则，提高代码的灵活性和可维护性。