摄影手机网站模板海南网站设计

在日常开发中，参数校验是保障接口健壮性与数据安全的第一道防线。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	必须是过去时间

---

八、注意事项与最佳实践

• 嵌套校验字段必须加 @Valid。
• @Validated 支持分组、@Valid 不支持。
• 实体类字段建议使用包装类型（如 Integer 而非 int），避免 null 时校验器报错。
• 参数校验推荐配合统一响应结构，提升开发与调试体验。

---