Java Bean Validation（JSR 380 / Hibernate Validator）

🔹 常见校验注解说明与示例

1. @AssertFalse

字段值必须为 false。

@AssertFalse
private boolean active;

✅ 合法：active = false
❌ 非法：active = true

2. @AssertTrue

字段值必须为 true。

@AssertTrue
private boolean agreedToTerms;

✅ 合法：agreedToTerms = true
❌ 非法：agreedToTerms = false

3. @DecimalMax(value = "100")

数值不能超过指定最大值（支持字符串格式）。

@DecimalMax("100")
private BigDecimal price;

✅ 合法：price = 99.99
❌ 非法：price = 101.0

4. @DecimalMin(value = "0")

数值不能小于指定最小值。

@DecimalMin("0")
private BigDecimal discount;

✅ 合法：discount = 5.0
❌ 非法：discount = -1.0

5. @Digits(integer=3, fraction=2)

控制整数和小数位数。

@Digits(integer = 3, fraction = 2)
private BigDecimal amount;

✅ 合法：amount = 123.45
❌ 非法：amount = 1234.56（整数部分超过3位）

6. @Email

验证是否为合法邮箱地址。

@Email
private String email;

✅ 合法：user@example.com
❌ 非法：invalid-email

7. @Future

日期必须是将来的时间。

@Future
private LocalDate eventDate;

✅ 合法：2025-04-01（当前时间后）
❌ 非法：2024-01-01（已过期）

8. @FutureOrPresent

日期必须是未来或当前时间。

@FutureOrPresent
private LocalDate startDate;

✅ 合法：2024-04-01 或 现在
❌ 非法：2023-01-01

9. @Max(value = 100)

数值不能大于指定值。

@Max(100)
private int score;

✅ 合法：score = 99
❌ 非法：score = 101

10. @Min(value = 0)

数值不能小于指定值。

@Min(0)
private int age;

✅ 合法：age = 25
❌ 非法：age = -1

11. @Negative

数值必须为负数（不包括 0）。

@Negative
private int balance;

✅ 合法：balance = -5
❌ 非法：balance = 0, balance = 5

12. @NegativeOrZero

数值必须为负数或零。

@NegativeOrZero
private int quantity;

✅ 合法：quantity = -1, quantity = 0
❌ 非法：quantity = 1

13. @NotBlank

字符串非空且不能为空白字符（如空格、换行等）。

@NotBlank
private String name;

✅ 合法："Alice"
❌ 非法："", " "（空白）

14. @NotEmpty

字符串、集合、数组等不能为空（但允许空白字符）。

@NotEmpty
private List<String> tags;

✅ 合法：["tag1"], " "（字符串）❌ 非法：null, []

⚠️ 注意：@NotBlank 是 @NotEmpty 的子集，只适用于字符串。

15. @NotNull

字段不能为 null。

@NotNull
private String description;

✅ 合法："hello"
❌ 非法：null

16. @Null

字段必须为 null。

@Null
private Integer deletedAt;

✅ 合法：deletedAt = null
❌ 非法：deletedAt = 123

17. @Past

日期必须是过去的时间（不包含今天）。

@Past
private LocalDate birthDate;

✅ 合法：2000-01-01
❌ 非法：今天 或 未来

18. @PastOrPresent

日期必须是过去或今天。

@PastOrPresent
private LocalDate registrationDate;

✅ 合法：昨天, 今天
❌ 非法：明天

19. @Pattern(regexp = "^[A-Za-z]+$")

使用正则表达式校验字符串。

@Pattern(regexp = "^[A-Za-z]+$")
private String firstName;

✅ 合法："John"
❌ 非法："John123", "john@"

20. @Positive

数值必须为正数（> 0）。

@Positive
private int count;

✅ 合法：count = 1
❌ 非法：count = 0, -1

21. @PositiveOrZero

数值必须为正数或零。

@PositiveOrZero
private int credits;

✅ 合法：credits = 0, 10
❌ 非法：-5

22. @Size(min = 2, max = 10)

控制字符串、集合、数组的大小。

@Size(min = 2, max = 10)
private String username;

✅ 合法："abc"（长度3）
❌ 非法："a"（太短），"abcdefghijk"（太长）

✅ 使用建议

• 组合使用：可多个注解共存。
• 自定义消息：可用 message 属性设置提示信息。

@NotNull(message = "姓名不能为空")
@Size(min = 2, max = 20, message = "姓名长度应在2~20之间")
private String name;

• 配合 Spring Boot：在 Controller 中使用 @Valid 或 @Validated 触发校验。

@PostMapping("/users")
public ResponseEntity<?> createUser(@Valid @RequestBody User user) {
    // 校验失败会抛出 MethodArgumentNotValidException
}

📌 总结表格