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

Spring的 @Validate注解详细分析

news 来源：原创 2025/5/15 9:43:40

在 Spring Boot 中，参数校验是保证数据合法性的重要手段。除了前面提到的@NotNull、@Size等基础注解外，JSR-303（Bean Validation 1.0）、JSR-349（Bean Validation 1.1）和 JSR-380（Bean Validation 2.0）规范还提供了大量常用的校验注解。下面详细介绍这些注解及其应用场景：

一、基础校验注解

1. 空值校验

注解	作用
@NotNull	验证对象不为null，但允许为空字符串（""）或空集合。
@Null	验证对象必须为null。
@NotEmpty	验证字符串、集合、数组、Map 等不为null且长度 / 大小大于 0（忽略空白字符）。
@NotBlank	验证字符串不为null且至少包含一个非空白字符（如" "会校验失败）。

示例：

public class User {

@NotNull(message = "ID不能为空")

private Long id;

@NotEmpty(message = "姓名不能为空")

private String name;

@NotBlank(message = "用户名不能为空")

private String username;

}

2. 数值校验

注解	作用
@Min(value)	验证数值（包括基本类型和包装类）必须大于或等于指定最小值。
@Max(value)	验证数值必须小于或等于指定最大值。
@DecimalMin(value)	验证 BigDecimal 或字符串表示的数值必须大于或等于指定值（支持精确小数）。
@DecimalMax(value)	验证 BigDecimal 或字符串表示的数值必须小于或等于指定值（支持精确小数）。
@Digits(integer=, fraction=)	验证数值的整数部分和小数部分的位数是否符合要求。
@Positive	验证数值必须为正数（不包括 0）。
@PositiveOrZero	验证数值必须为正数或 0。
@Negative	验证数值必须为负数（不包括 0）。
@NegativeOrZero	验证数值必须为负数或 0。

示例：

public class Product {

@Min(value = 1, message = "价格不能低于1")

private double price;

@DecimalMax(value = "1000.00", message = "价格不能超过1000")

private BigDecimal maxPrice;

@Digits(integer = 3, fraction = 2, message = "折扣必须为最多3位整数和2位小数")

private double discount;

}

3. 长度 / 大小校验

注解	作用
@Size(min=, max=)	验证字符串、集合、数组、Map 等的长度或大小必须在指定范围内。
@Length(min=, max=)	验证字符串长度必须在指定范围内（常用于 Hibernate Validator）。

示例：

public class User {

@Size(min = 6, max = 20, message = "密码长度必须在6-20位之间")

private String password;

@Size(max = 5, message = "爱好不能超过5个")

private List<String> hobbies;

}

4. 格式校验

注解	作用
@Email	验证字符串是否为合法的邮箱格式（默认正则较宽松，可通过regexp参数自定义）。
@Pattern(regexp=)	验证字符串是否符合指定的正则表达式。
@URL	验证字符串是否为合法的 URL 格式。

示例：

public class Contact {

@Email(message = "邮箱格式不正确")

private String email;

@Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")

private String phone;

@URL(message = "网址格式不正确")

private String website;

}

二、高级校验注解

1. 日期 / 时间校验

注解	作用
@Past	验证日期 / 时间必须是过去的时间（如.util.Date、LocalDate等）。
@PastOrPresent	验证日期 / 时间必须是过去或当前时间。
@Future	验证日期 / 时间必须是未来的时间。
@FutureOrPresent	验证日期 / 时间必须是未来或当前时间。

示例：

public class Event {

@Past(message = "创建时间必须是过去的时间")

private LocalDateTime createTime;

@Future(message = "活动开始时间必须是未来的时间")

private LocalDate startTime;

}

2. 条件校验

注解	作用
@AssertTrue	验证布尔值必须为true。
@AssertFalse	验证布尔值必须为false。

示例：

public class Agreement {

@AssertTrue(message = "必须同意用户协议")

private boolean agreed;

}

3. 自定义校验

当内置注解无法满足需求时，可以通过@Constraint自定义校验注解：

// 自定义注解

@Target({ElementType.FIELD, ElementType.PARAMETER})

@Retention(RetentionPolicy.RUNTIME)

@Constraint(validatedBy = PasswordValidator.class)public

@interface ValidPassword {

String message() default "密码必须包含大小写字母和数字，长度8-20位";

Class<?>[] groups() default {};

Class<? extends Payload>[] payload() default {};

}

// 校验器实现

public class PasswordValidator implements ConstraintValidator<ValidPassword, String> {

private static final Pattern PASSWORD_PATTERN =

Pattern.compile("^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d).{8,20}$");

@Override

public boolean isValid(String password, ConstraintValidatorContext context) {

return password != null && PASSWORD_PATTERN.matcher(password).matches();

}

三、分组校验与级联校验

1. 分组校验

通过定义分组接口，为不同场景（如创建、更新）应用不同的校验规则：

// 定义分组接口

public interface CreateGroup {}

public interface UpdateGroup {}

// 实体类中指定分组

public class User {

@NotNull(groups = UpdateGroup.class) // 更新时ID不能为空

private Long id;

@NotBlank(groups = {CreateGroup.class, UpdateGroup.class}) // 创建和更新时都需要

private String username;

}

// 控制器方法中指定分组

@PostMappingpublic User createUser(@Validated(CreateGroup.class) @RequestBody User user) {

return userService.createUser(user);

}

2. 级联校验

当对象包含嵌套属性时，使用@Valid触发嵌套校验：

public class Order {

@NotNull

private Long id;

@Valid // 触发嵌套校验

@NotNull

private User user;

}

四、Hibernate Validator 扩展注解

Hibernate Validator 是 JSR 规范的常用实现，提供了一些额外的校验注解：

注解	作用
@CreditCardNumber	验证字符串是否为合法的信用卡号（通过 Luhn 算法校验）。
@Currency	验证货币金额是否符合指定的货币代码（如@Currency("CNY")）。
@EAN	验证字符串是否为合法的商品条形码（如 EAN-13）。
@ISBN	验证字符串是否为合法的 ISBN 编号。
@Range(min=, max=)	验证数值是否在指定范围内（类似于@Min+@Max）。