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

SpringBoot参数校验：@Valid 与 @Validated 详解

news 来源：原创 2025/5/15 1:40:13

SpringBoot参数校验：@Valid 与 @Validated 详解

一、案例（参数校验的必要性）

传统方式（无注解）的缺点：

// 需要手动校验每个字段，代码冗余且易出错
public String register(User user) {
    // 手动校验每个字段
    if (user.getEmail() == null || !isValidEmail(user.getEmail())) {
        throw new IllegalArgumentException("邮箱格式错误");
    }
    if (user.getPassword().length() < 8) {
        throw new IllegalArgumentException("密码长度需≥8位");
    }
    // 校验逻辑与业务代码耦合，难以复用
}

问题总结：

代码冗余：相同校验逻辑重复编写
维护困难：校验规则分散，修改成本高
可读性差：业务逻辑被大量if-else淹没

注解方式的优势：

public class User {
    @Email(message = "邮箱格式不合法")  // 一行注解替代复杂校验
    private String email;
    
    @Size(min = 8, message = "密码长度需≥8位")
    private String password;
}

@PostMapping("/register")
public String register(@Valid @RequestBody User user) { 
    // 校验逻辑由框架自动处理
    return "success";
}

核心优势：

声明式校验：通过注解自动完成参数验证
代码简洁：减少冗余的if-else判断
统一规范：标准化校验规则，降低维护成本

二、@Valid 注解

简介

Java标准注解（javax.validation）
用于触发 Bean Validation 校验机制
可校验方法参数和成员属性

SpringBoot配置

<!-- pom.xml 必须依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

使用示例

public class User {
    @NotNull(message = "用户名不能为空")
    private String name;
    
    @Min(value = 18, message = "年龄必须≥18岁")
    private Integer age;
}

@PostMapping("/users")
public String createUser(@Valid @RequestBody User user) { // 触发校验
    return "success";
}

全局异常处理（核心实践）

@RestControllerAdvice
public class GlobalExceptionHandler {
    
    // 处理@Valid/@Validated抛出的校验异常
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<Map<String, String>> handleValidationException(MethodArgumentNotValidException ex) {
        Map<String, String> errors = new HashMap<>();
        ex.getBindingResult().getFieldErrors().forEach(error -> 
            errors.put(error.getField(), error.getDefaultMessage()));
        return ResponseEntity.badRequest().body(errors);
    }
}

效果：自动返回结构化错误信息（字段名+错误描述）

三、@Validated 注解

简介

Spring框架注解（org.springframework.validation.annotation）(@Validated是Spring框架提供的，导入springboot的依赖就会自动导入这个依赖)
支持分组校验（Group Validation）
可标注在类、方法、参数上

核心功能

// 分组接口定义
public interface CreateGroup {} 
public interface UpdateGroup {}

public class User {
    @NotBlank(groups = CreateGroup.class)
    private String name;
    
    @NotNull(groups = {CreateGroup.class, UpdateGroup.class})
    private Integer age;
}

// 使用分组校验
@PostMapping("/users")
public String createUser(@Validated(CreateGroup.class) @RequestBody User user) {
    return "success";
}

四、常用校验注解

最常用的注解：

注解	说明	示例
`@NotNull`	值不能为null	`@NotNull(message="字段必填")`
`@NotBlank`	字符串非空（trim后）	适用于用户名、密码等
`@Min/@Max`	数值范围限制	`@Min(18)`
`@Pattern`	正则表达式校验	`@Pattern(regexp="^1[3-9]\\d{9}$")`
`@Valid`	嵌套对象校验	用于对象内的子对象属性

比较常用的注解：

注解	适用类型	说明	示例
`@Future`	Date	日期必须在未来	`@Future(message="截止时间无效")`
`@Digits`	数值类型	整数位和小数位限制	`@Digits(integer=3, fraction=2)`
`@Negative`	数值类型	必须为负数	常用于财务系统
`@NotEmpty`	集合/字符串	集合非空或字符串长度>0	比`@NotBlank`更宽松

组合注解（自定义）

// 自定义手机号校验注解
@Documented
@Constraint(validatedBy = PhoneValidator.class)
@Target({FIELD, PARAMETER})
@Retention(RUNTIME)
public @interface Phone {
    String message() default "手机号格式不合法";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

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

使用场景：复用企业特定校验规则（如公司内部员工编号）

五、@Valid 与 @Validated 区别

特性	@Valid	@Validated
标准规范	JSR-303/JSR-349 标准	Spring 框架扩展
分组校验	不支持	支持
嵌套校验	需要显式添加@Valid	不自动支持嵌套校验
作用位置	方法参数、成员属性	类、方法、参数

六.高频问题与最佳实践

常见问题排查

注解不生效：
- 检查是否忘记添加@Valid/@Validated
- 确保校验对象未被@RequestBody等注解错误包裹
嵌套校验失败：
- 确认在嵌套对象属性上添加了@Valid

性能优化建议

避免过度校验：在Controller层做基础校验，复杂逻辑放到Service层
使用分组校验：减少不必要的校验开销

高级技巧

// 动态分组校验（根据请求参数决定校验组）
@Validated
@RestController
public class UserController {
    
    @PostMapping("/users")
    public String createUser(
        @RequestParam String type,
        @Validated({Default.class, type.equals("vip") ? VipGroup.class : Default.class}) 
        @RequestBody User user
    ) {
        return "success";
    }
}

实现原理：利用Spring EL表达式动态选择校验组

七、重点总结

优先使用场景：
- 优先使用@Valid的场景：嵌套对象校验、与非Spring框架整合
- 优先使用@Validated的场景：需要分组校验、校验Service层方法参数
配置要点：
- 要想使用@Valid必须添加spring-boot-starter-validation依赖
- 校验失败会抛出MethodArgumentNotValidException
最佳实践：

// 嵌套校验示例
public class Order {
    @Valid  // 必须显式添加
    private User user;
}

// 分组校验示例
@Validated(UpdateGroup.class)
public void updateUser(@RequestBody User user) {}