首页 > 软件编程 > java > javax.validation.constraints说明

关于javax.validation.constraints的超详细说明

2025-07-03 09:39:25 作者：悟能不能悟

这篇文章主要给大家介绍了关于javax.validation.constraints的超详细说明,文中通过代码介绍的非常详细,对大家的学习或者工作具有一定的参考借鉴价值,需要的朋友可以参考下

前言

以下是关于 javax.validation.constraints（现为 Jakarta Bean Validation）的详细说明，涵盖核心注解、使用场景、代码示例及最佳实践：

一、javax.validation.constraints 是什么？

作用：提供一组标准注解，用于对 Java Bean 的字段或方法参数进行数据校验（如非空、长度、范围等）。
规范演进：
- Java EE 时期：包名为 javax.validation.constraints。
- Jakarta EE 9+：包名迁移为 jakarta.validation.constraints（需注意依赖兼容性）。

二、核心注解列表及用法

1. 常用注解

注解	校验规则	支持类型
`@NotNull`	值不能为 `null`	任意类型
`@NotBlank`	字符串不能为空或纯空格	`String`
`@NotEmpty`	集合/数组/字符串不能为空（长度 > 0）	`Collection`, `String` 等
`@Size(min, max)`	元素数量或字符串长度在指定范围内	集合、数组、字符串
`@Min(value)`	数值必须 ≥ 指定最小值	数值类型（`int`, `long` 等）
`@Max(value)`	数值必须 ≤ 指定最大值	同上
`@DecimalMin(value)`	数值必须 ≥ 指定最小值（字符串形式，支持精度）	`BigDecimal`, `String` 等
`@DecimalMax(value)`	数值必须 ≤ 指定最大值（字符串形式，支持精度）	同上
`@Digits(integer, fraction)`	数值整数部分最多 `integer` 位，小数部分最多 `fraction` 位	数值类型
`@Pattern(regexp)`	字符串必须匹配正则表达式	`String`
`@Email`	字符串必须是合法邮箱格式	`String`
`@Positive` / `@PositiveOrZero`	数值必须为正数或零	数值类型
`@Negative` / `@NegativeOrZero`	数值必须为负数或零	数值类型
`@Future` / `@FutureOrPresent`	日期必须在未来（或包含当前）	`Date`, `LocalDate` 等
`@Past` / `@PastOrPresent`	日期必须在过去（或包含当前）	同上

2. 注解示例代码

public class User {
    @NotBlank(message = "用户名不能为空")
    private String username;

    @Email(message = "邮箱格式无效")
    private String email;

    @Size(min = 6, max = 20, message = "密码长度需在6-20位之间")
    private String password;

    @Min(value = 18, message = "年龄必须≥18岁")
    @Max(value = 100, message = "年龄必须≤100岁")
    private Integer age;

    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式无效")
    private String phone;
}

三、集成到 Spring Boot 中的步骤

1. 添加依赖

<!-- Spring Boot 2.x 使用 javax.validation -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

<!-- Jakarta EE 9+ 使用 jakarta.validation -->
<dependency>
    <groupId>jakarta.validation</groupId>
    <artifactId>jakarta.validation-api</artifactId>
    <version>3.0.2</version>
</dependency>

2. 在 Controller 中触发校验

使用 @Valid 或 @Validated 注解触发校验：

@PostMapping("/users")
public ResponseEntity<?> createUser(@RequestBody @Valid User user) {
    // 校验通过后执行业务逻辑
    return ResponseEntity.ok("用户创建成功");
}

3. 处理校验异常

通过 @ExceptionHandler 捕获 MethodArgumentNotValidException：

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<Map<String, String>> handleValidationException(MethodArgumentNotValidException ex) {
        Map<String, String> errors = new HashMap<>();
        ex.getBindingResult().getAllErrors().forEach(error -> {
            String fieldName = ((FieldError) error).getField();
            String errorMessage = error.getDefaultMessage();
            errors.put(fieldName, errorMessage);
        });
        return ResponseEntity.badRequest().body(errors);
    }
}

四、高级用法

1. 分组校验

通过分组接口实现不同场景下的差异化校验：

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

public class User {
    @NotNull(groups = UpdateGroup.class)
    private Long id;

    @NotBlank(groups = {CreateGroup.class, UpdateGroup.class})
    private String name;
}

// 在 Controller 中指定分组
@PostMapping("/users")
public ResponseEntity<?> createUser(@RequestBody @Validated(CreateGroup.class) User user) { ... }

2. 自定义校验注解

实现自定义校验逻辑（如密码强度校验）：

@Target({FIELD})
@Retention(RUNTIME)
@Constraint(validatedBy = PasswordValidator.class)
public @interface StrongPassword {
    String message() default "密码必须包含大小写字母和数字";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

public class PasswordValidator implements ConstraintValidator<StrongPassword, String> {
    @Override
    public boolean isValid(String password, ConstraintValidatorContext context) {
        return password.matches("^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d).+$");
    }
}

3. 级联校验

校验对象内的嵌套对象：

public class Order {
    @Valid
    private List<@Valid Product> products; // 校验每个 Product 的字段
}

五、校验失败的错误消息定制

1. 默认消息模板

每个注解的 message 属性支持占位符：

@Size(min = 6, max = 20, message = "密码长度需在{min}-{max}位之间")
private String password;

2. 国际化消息

在 messages.properties 或 ValidationMessages.properties 中定义：

user.email.invalid=邮箱格式无效

注解中使用：

@Email(message = "{user.email.invalid}")
private String email;

六、常见问题与解决方案

问题	解决方案
校验未生效	检查是否添加了 `@Valid` 或 `@Validated` 注解；确认依赖已正确引入
嵌套对象校验失败	在嵌套对象字段上添加 `@Valid` 注解
分组校验不生效	在 `@Validated` 注解中明确指定分组接口
自定义校验器未触发	确认 `@Constraint(validatedBy = MyValidator.class)` 并实现 `ConstraintValidator`

七、总结

核心价值：通过声明式注解简化数据校验逻辑，减少样板代码。
最佳实践：
- 优先使用标准注解，避免重复造轮子。
- 结合分组校验实现多场景复用。
- 统一处理校验异常，返回清晰的错误信息。
扩展性：通过自定义注解和校验器满足复杂业务需求。

到此这篇关于关于javax.validation.constraints超详细说明的文章就介绍到这了,更多相关javax.validation.constraints说明内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！