Java JDK Validation 注解解析与使用方法验证_Java

jakarta validation（原 jsr-380，也称为 bean validation 2.0）是 java 中用于验证对象数据的标准 api。

它提供了一套注解和接口，用于声明和执行验证规则。

位于 jakarta.validation。

核心概念

1. 主要注解

基本约束注解

注解	作用
`@notnull`	验证值不为 null
`@null`	验证值必须为 null
`@asserttrue`	验证布尔值为 true
`@assertfalse`	验证布尔值为 false
`@min(value)`	验证数字不小于指定值
`@max(value)`	验证数字不大于指定值
`@decimalmin(value)`	验证数字不小于指定值（字符串形式）
`@decimalmax(value)`	验证数字不大于指定值（字符串形式）
`@size(min, max)`	验证集合/数组/字符串大小在范围内
`@digits(integer, fraction)`	验证数字格式
`@past`	验证日期是过去的
`@pastorpresent`	验证日期是过去或现在
`@future`	验证日期是将来的
`@futureorpresent`	验证日期是将来或现在
`@pattern(regex)`	验证字符串匹配正则表达式
`@email`	验证字符串是有效的电子邮件格式

其他常用注解

注解	作用
`@valid`	级联验证对象中的属性
`@notempty`	验证字符串/集合不为 null 且不为空
`@notblank`	验证字符串不为 null 且至少包含一个非空白字符
`@positive`	验证数字为正数
`@positiveorzero`	验证数字为正数或零
`@negative`	验证数字为负数
`@negativeorzero`	验证数字为负数或零

2. 核心接口

validator: 执行验证的主要接口
constraintvalidator: 自定义约束验证器接口
constraintviolation: 表示验证失败的结果
constraintvalidatorcontext: 自定义验证器的上下文

使用方法

1. 基本使用

添加依赖 (maven)

<dependency>
    <groupid>jakarta.validation</groupid>
    <artifactid>jakarta.validation-api</artifactid>
    <version>3.0.2</version>
</dependency>
<!-- 实现 (如 hibernate validator) -->
<dependency>
    <groupid>org.hibernate.validator</groupid>
    <artifactid>hibernate-validator</artifactid>
    <version>8.0.1.final</version>
</dependency>

定义验证对象

public class user {
    @notnull(message = "用户名不能为空")
    @size(min = 3, max = 20, message = "用户名长度必须在3-20之间")
    private string username;
    @email(message = "邮箱格式不正确")
    private string email;
    @min(value = 18, message = "年龄必须大于18岁")
    private int age;
    // getters and setters
}

执行验证

validatorfactory factory = validation.builddefaultvalidatorfactory();
validator validator = factory.getvalidator();
user user = new user();
user.setusername("ab"); // 太短
user.setemail("invalid-email");
user.setage(17);
set<constraintviolation<user>> violations = validator.validate(user);
for (constraintviolation<user> violation : violations) {
    system.out.println(violation.getpropertypath() + ": " + violation.getmessage());
}

2. 在 spring boot 中使用

spring boot 自动集成了 bean validation，可以直接使用：

控制器验证

@restcontroller
@requestmapping("/users")
public class usercontroller {
    @postmapping
    public responseentity<string> createuser(@valid @requestbody user user) {
        // 如果验证失败，会抛出methodargumentnotvalidexception
        return responseentity.ok("用户创建成功");
    }
}

全局异常处理

@controlleradvice
public class globalexceptionhandler {
    @exceptionhandler(methodargumentnotvalidexception.class)
    public responseentity<map<string, string>> handlevalidationexceptions(
        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);
    }
}

3. 自定义验证注解

定义注解

@target({elementtype.field, elementtype.parameter})
@retention(retentionpolicy.runtime)
@constraint(validatedby = phonenumbervalidator.class)
public @interface phonenumber {
    string message() default "无效的电话号码";
    class<?>[] groups() default {};
    class<? extends payload>[] payload() default {};
}

实现验证器

public class phonenumbervalidator implements constraintvalidator<phonenumber, string> {
    private static final pattern phone_pattern = pattern.compile("^1[3-9]\\d{9}$");
    @override
    public boolean isvalid(string value, constraintvalidatorcontext context) {
        if (value == null) {
            return true; // 使用@notnull处理null值
        }
        return phone_pattern.matcher(value).matches();
    }
}

使用自定义注解

public class contactinfo {
    @phonenumber
    private string phone;
    // getter and setter
}

高级特性

1. 分组验证

public interface basicinfo {}
public interface advancedinfo {}
public class user {
    @notnull(groups = basicinfo.class)
    private string username;
    @email(groups = advancedinfo.class)
    private string email;
}
// 使用分组验证
set<constraintviolation<user>> violations = validator.validate(user, basicinfo.class);

2. 级联验证

public class order {
    @valid
    private list<orderitem> items;
}
public class orderitem {
    @notnull
    private string productid;
    @min(1)
    private int quantity;
}

3. 自定义消息

可以使用表达式和el表达式：

@size(min = 6, max = 20, message = "密码长度必须在 {min} 到 {max} 之间")
private string password;

4. 方法验证

验证方法参数和返回值：

public class userservice {
    @validated
    public void createuser(@valid user user) {
        // ...
    }
    @valid
    public user getuser(@notnull long id) {
        // ...
    }
}

最佳实践

合理选择验证级别：在dto层进行基本验证，在业务层进行复杂验证
使用适当的消息：提供清晰、用户友好的错误消息
组合使用注解：如@notnull + @size比单独使用更安全
避免过度验证：只在必要的地方添加验证
考虑性能：大量验证可能影响性能，特别是在批量操作中

jakarta validation 提供了一种声明式、标准化的方式来验证java对象，与框架无关，可以方便地集成到各种java应用中。

到此这篇关于java jdk validation 注解解析与使用的文章就介绍到这了,更多相关java jdk validation 注解内容请搜索代码网以前的文章或继续浏览下面的相关文章希望大家以后多多支持代码网！

Java JDK Validation 注解解析与使用方法验证

2025年09月25日 • Java •我要评论