当前位置：首页 > news >正文

Spring Boot 参数校验：@Valid 与 @Validated

news 2025/7/18 11:04:17

在这里插入图片描述

在日常开发中，参数校验是保障接口健壮性与数据安全的第一道防线。Spring Boot 为我们提供了基于 JSR-303/JSR-380 的强大校验机制，通过注解与 AOP 实现了灵活且高效的数据校验方式。本篇博客将详细介绍 Spring Boot 中 @Valid、@Validated 注解的使用方法，并深入解析其背后的原理与扩展能力。

一、引入依赖

Spring Boot 项目中默认支持 javax.validation，但建议显式引入：

<!-- Hibernate Validator 是实现规范最广的一个实现 -->
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-validation</artifactId>
</dependency>

二、基础注解使用

在 Java Bean 上添加注解，示例：

public class UserDTO {@NotBlank(message = "用户名不能为空")private String username;@Email(message = "邮箱格式不正确")private String email;@Min(value = 18, message = "年龄必须 >= 18")@Max(value = 100, message = "年龄必须 <= 100")private Integer age;// Getter / Setter
}

三、在 Controller 中启用校验

1. 使用 `@Valid`（javax.validation）注解：

@RestController
@RequestMapping("/user")
public class UserController {@PostMapping("/create")public ResponseEntity<String> createUser(@Valid @RequestBody UserDTO user) {return ResponseEntity.ok("创建成功");}
}

2. 使用 `@Validated`（Spring 提供）支持分组校验：

public class UserDTO {@NotBlank(message = "用户名不能为空", groups = Create.class)private String username;public interface Create {}
}

@PostMapping("/create")
public ResponseEntity<String> createUser(@Validated(UserDTO.Create.class) @RequestBody UserDTO user) {return ResponseEntity.ok("按分组校验通过");
}

四、校验嵌套对象

public class OrderDTO {@NotNull@Valid // 注意：嵌套对象必须加 @Valid 才能触发其内部校验private UserDTO user;
}

五、处理校验失败异常

Spring Boot 默认抛出 MethodArgumentNotValidException（@Valid）或 ConstraintViolationException（@Validated）。

可以通过全局异常处理捕获并格式化返回：

@RestControllerAdvice
public class GlobalExceptionHandler {@ExceptionHandler(MethodArgumentNotValidException.class)public ResponseEntity<?> handleValidException(MethodArgumentNotValidException ex) {String errorMsg = ex.getBindingResult().getAllErrors().stream().map(DefaultMessageSourceResolvable::getDefaultMessage).collect(Collectors.joining("; "));return ResponseEntity.badRequest().body("参数错误：" + errorMsg);}
}

六、自定义校验注解

1. 自定义注解：

@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = {PhoneValidator.class})
public @interface Phone {String message() default "手机号格式不正确";Class<?>[] groups() default {};Class<? extends Payload>[] payload() default {};
}

2. 编写校验器：

public class PhoneValidator implements ConstraintValidator<Phone, String> {private static final Pattern PATTERN = Pattern.compile("^1[3-9]\\d{9}$");@Overridepublic boolean isValid(String value, ConstraintValidatorContext context) {return value != null && PATTERN.matcher(value).matches();}
}

3. 使用：

@Phone
private String phone;

七、常用校验注解速查表

注解	功能说明
`@NotNull`	不能为 null
`@NotEmpty`	不能为 null 且长度 > 0
`@NotBlank`	不能为 null 且去空格后长度 > 0
`@Email`	邮箱格式
`@Min`	最小值限制
`@Max`	最大值限制
`@Pattern`	正则校验
`@Size`	长度范围校验
`@Future`	必须是未来时间
`@Past`	必须是过去时间