ValidX为中国业务场景设计的 Java 验证库,提供 90+ 个常用验证器

0 阅读1小时+

ValidX

为中国业务场景设计的 Java 验证库,提供 90+ 个常用验证器


📑 目录


介绍

ValidX 是一个专注于中国业务场景的 Java 验证库。基于 JSR-380 标准构建,提供 90+ 个常用验证注解,包括身份证、手机号、银行卡等。

💡 为什么创作 ValidX?

在开发面向中国用户的应用时,我们经常遇到这样的场景:

痛点一:Java 内置验证规则太少,远不如其他语言框架丰富

如果你用过其他语言的 Web 框架,比如 PHP 的 ThinkPHP、JavaScript 的 Validator.js,你会发现它们内置了非常丰富的验证规则:mobileidcardzipalphaNum 等等,开箱即用,简单方便。

但在 Java 世界里,标准的 Bean Validation 只提供了 @Email@Pattern 等少量通用验证注解。对于中国业务场景中常见的身份证、手机号、银行卡、统一社会信用代码等,却完全没有支持。

这导致每个 Java 项目都在重复造轮子:

  • 自己编写复杂的正则表达式
  • 实现 Luhn 算法验证银行卡
  • 处理身份证的校验位计算
  • 复制粘贴网上找到的验证代码

为什么 Java 验证不能像其他框架那样开箱即用 这就是 ValidX 的目标。

痛点二:验证逻辑分散难以维护

随着项目发展,验证逻辑可能散落在:

  • Controller 层的手动校验
  • Service 层的业务校验
  • 工具类中的静态方法
  • 各个模块重复实现的验证代码

这导致代码重复、维护困难、容易出错。

痛点三:缺乏中文错误提示和多语言支持

使用标准注解时,错误消息通常是英文的,或者需要手动配置资源文件。对于中国用户,我们需要:

  • 友好的中文错误提示
  • 支持多语言切换
  • 可自定义的错误消息模板

ValidX 提供以下功能:

  1. 90+ 验证器 - 身份证、手机号、银行卡、快递单号、车牌号等
  2. 两种使用方式 - 注解式和链式 API
  3. 多语言支持 - 支持 8 种语言
  4. 测试完善 - 1300+ 单元测试
  5. 轻量级 - 仅依赖 Bean Validation API

✨ 为什么选择 ValidX

🇨🇳 中国业务场景

  • 90+ 验证器:身份证、手机号、银行卡、统一社会信用代码、车牌号等
  • 支持 8 种语言:简体中文、英语、日语、韩语、法语、德语、西班牙语、俄语
  • 本土业务:快递单号、QQ、微信等

🚀 使用便捷

  • 两种使用方式:注解式或链式 API
  • 开箱即用:集成 Spring Boot 和标准 Bean Validation
  • 灵活配置:支持全局/局部的 null 和空字符串策略

🎯 可靠性

  • 类型安全:注解方式提供编译时检查
  • 错误消息:支持国际化和自定义字段标签
  • 测试覆盖:1300+ 单元测试

📦 轻量高效

  • 单一依赖:除 Bean Validation API 外无额外依赖
  • 体积小:约 300KB
  • 性能优化:最小化性能开销

🚀 5 分钟快速开始

第一步:添加依赖

<dependency>
    <groupId>io.github.vipxieliang</groupId>
    <artifactId>validx</artifactId>
    <version>1.0.0</version>
</dependency>

第二步:选择使用方式

方式 A:注解方式(推荐用于 DTO)

适合 Spring Boot 控制器请求验证:

public class UserRegistrationDTO {
    @NotBlank(message = "邮箱不能为空")
    @Email
    private String email;

    @NotBlank(message = "手机号不能为空")
    @ChinesePhone
    private String phone;

    @ChineseIdCard
    private String idCard;

    @Password(minLength = 8)
    private String password;

    // getters and setters...
}

@RestController
public class UserController {
    @PostMapping("/register")
    public Result register(@Valid @RequestBody UserRegistrationDTO dto) {
        // Spring 自动验证,失败返回 400
        return userService.register(dto);
    }
}
方式 B:链式调用方式(推荐用于业务逻辑)

适合服务层动态验证:

@Service
public class UserService {
    public void validateUserData(Map<String, Object> userData) {
        ValidaX validator = ValidaX.init()
            .config(ValidXConfig.GLOBAL_NOT_EMPTY)  // 全局拒绝 null/空值
            .field("邮箱").isEmail(userData.get("email"))
            .field("手机号").isChinesePhone(userData.get("phone"))
            .field("身份证").isChineseIdCard(userData.get("idCard"))
            .field("QQ(可选)").allowNull().isQQ(userData.get("qq"));  // 可选字段允许空值

        if (!validator.passed()) {
            throw new ValidationException(validator.getErrors());
        }
    }
}

第三步:运行应用

就这么简单。ValidX 与现有 Spring Boot 设置无缝协作。错误消息会根据 Accept-Language 请求头自动适配用户语言。

多语言支持

ValidX 支持多语言错误消息,可以通过以下方式使用:

// 使用系统默认语言
ValidaX chain1 = ValidaX.init()
        .isEmail("invalid-email");

// 使用中文
ValidaX chain2 = ValidaX.init()
        .withLocale(Locale.SIMPLIFIED_CHINESE)
        .isEmail("invalid-email");

// 使用英文
ValidaX chain3 = ValidaX.init()
        .withLocale(Locale.ENGLISH)
        .isEmail("invalid-email");

注解方式也支持多语言,错误消息会根据系统语言环境自动切换。要使用特定语言环境,可以配置Hibernate Validator:

// 配置英文消息的语言环境
ValidatorFactory englishFactory = Validation.byDefaultProvider()
    .configure()
    .messageInterpolator(new ResourceBundleMessageInterpolator())
    .buildValidatorFactory();
Validator englishValidator = englishFactory.getValidator();

// 配置中文消息的语言环境
ValidatorFactory chineseFactory = Validation.byDefaultProvider()
    .configure()
    .messageInterpolator(new ResourceBundleMessageInterpolator())
    .buildValidatorFactory();
Validator chineseValidator = chineseFactory.getValidator();
public class UserDTO {
    // 错误消息会根据当前语言环境自动切换为中文或英文
    @Email 
    private String email;
    
    @ChineseIdCard
    private String idCard;
}

自动语言环境切换

ValidX 还支持自动语言环境切换,无需显式指定语言环境:

// 全局设置语言环境(影响当前线程的所有验证操作)
MessageManager.setCurrentLocale(Locale.SIMPLIFIED_CHINESE);

// 验证操作会自动使用设置的语言环境
ValidaX chain = ValidaX.init()
        .isEmail("invalid-email");

// 清除全局语言环境设置
MessageManager.clearCurrentLocale();

目前支持的语言:

  • 简体中文 (默认)
  • 英文
  • 日语
  • 韩语
  • 法语
  • 德语
  • 西班牙语
  • 俄语

重要说明:Null/空字符串处理

所有的验证注解和链式校验方法对 null 和空字符串("")都会返回通过(true,这遵循 Bean Validation (JSR 380) 规范的设计原则。

这是为了实现关注点分离

  • @NotNull / @NotEmpty / @NotBlank:负责检查"字段是否存在"
  • 格式验证注解/方法(如 @EmailisEmail() 等):负责检查"如果字段有值,格式是否正确"

1. 注解方式的 Null/空字符串处理

如何使用?

根据业务需求组合使用:

public class UserDTO {
    // 必填字段:不能为 null 且格式必须正确
    @NotNull(message = "邮箱不能为空")
    @Email
    private String email;

    // 必填字段:不能为 null、不能为空字符串,且格式必须正确
    @NotBlank(message = "手机号不能为空")
    @ChinesePhone
    private String phone;

    // 可选字段:可以为 null 或空字符串,但如果有值则格式必须正确
    @QQ
    private String qq;

    // 可选字段:可以为 null,但不能为空字符串,如果有值则格式必须正确
    @NotEmpty(message = "如果填写微信号,不能为空字符串")
    @WeChat
    private String wechat;
}
常用组合示例
需求注解组合说明
必填且格式正确@NotBlank + @Email最常用:不能为 null、空字符串、空白字符
必填且格式正确@NotNull + @ChineseIdCard不能为 null,但允许空字符串(较少用)
可选但格式正确@QQ可以为 null/空,但如果有值必须正确
可选但非空@NotEmpty + @WeChat可以为 null,但不能是空字符串
Bean Validation 标准注解说明
  • @NotNull:字段不能为 null(但可以是空字符串 ""
  • @NotEmpty:字段不能为 null 且不能为空(字符串不能是 "",集合不能是空集合)
  • @NotBlank:字符串不能为 null""" "(空白字符)
适用场景

注解方式适用于 Controller 层的接口参数校验

@RestController
public class UserController {
    @PostMapping("/register")
    public Result register(@Valid @RequestBody UserDTO dto) {
        // Spring 自动校验,失败返回 400
        return userService.register(dto);
    }
}

2. 链式调用的 Null/空字符串处理

链式校验(ValidaX.init())的默认行为与注解方式一致:null 和空字符串会通过验证

为什么这样设计?

链式校验主要用于业务逻辑层的动态校验场景,特别是处理 Map/JSON 数据时,字段可能不存在(返回 null)是正常情况。

例如:

  • 解析外部 API 返回的 JSON 数据
  • 处理前端传递的动态表单数据
  • 校验数据库查询返回的 Map 结果

在这些场景中,某个字段为 null 通常表示"该字段不存在"或"不需要校验该字段",而不是错误。

适用场景

链式方式适用于业务逻辑层的动态校验

@Service
public class UserService {
    public void process(Map<String, Object> data) {
        ValidaX validator = ValidaX.init();

        // Map 中的字段可能不存在(null),这是正常情况
        // 链式校验会自动跳过 null 值
        validator.isEmail(data.get("email"))
                 .isChinesePhone(data.get("phone"));

        if (!validator.passed()) {
            throw new BusinessException(validator.getErrors());
        }
    }
}
链式验证配置 API

ValidaX 现在支持通过全局配置和局部状态控制来灵活处理 null/空值。

全局配置

你可以使用 ValidXConfig 设置全局验证要求:

// 创建带有全局 NOT_NULL 要求的验证器
ValidaX validator = ValidaX.init()
    .config(ValidXConfig.GLOBAL_NOT_NULL);

// 所有验证方法现在都会拒绝 null 值
validator.isEmail(email)  // 如果 email 为 null 则失败
         .isPhone(phone); // 如果 phone 为 null 则失败

// 创建带有全局 NOT_EMPTY 要求的验证器
ValidaX validator2 = ValidaX.init()
    .config(ValidXConfig.GLOBAL_NOT_EMPTY);

// 所有验证方法现在都会拒绝 null 和空字符串
validator2.isEmail(email)  // 如果 email 为 null 或 "" 则失败
          .isPhone(phone); // 如果 phone 为 null 或 "" 则失败

可用的全局配置:

  • ValidXConfig.DEFAULT - 允许 null 和空字符串(默认行为)
  • ValidXConfig.GLOBAL_NOT_NULL - 所有字段不能为 null
  • ValidXConfig.GLOBAL_NOT_EMPTY - 所有字段不能为 null 或空字符串

最佳实践: 建议只在验证链的开头调用一次 config() 方法,以保持清晰和可维护性。

// ✅ 推荐:在开头设置一次配置
ValidaX validator = ValidaX.init()
    .config(ValidXConfig.GLOBAL_NOT_NULL)
    .isEmail(email)
    .isPhone(phone)
    .allowNull().isQQ(qq);  // 例外情况使用局部方法

// ⚠️ 不推荐:在中间多次调用 config()
ValidaX validator = ValidaX.init()
    .config(ValidXConfig.GLOBAL_NOT_NULL)
    .isEmail(email)
    .config(ValidXConfig.DEFAULT)  // 令人困惑:难以跟踪配置变化
    .isPhone(phone);

// ✅ 如果需要不同配置,创建多个验证器实例
ValidaX strictValidator = ValidaX.init()
    .config(ValidXConfig.GLOBAL_NOT_NULL)
    .isEmail(email1)
    .isPhone(phone1);

ValidaX lenientValidator = ValidaX.init()
    .config(ValidXConfig.DEFAULT)
    .isEmail(email2)
    .isPhone(phone2);
局部状态控制

你可以使用局部状态方法来覆盖特定字段的全局配置:

ValidaX validator = ValidaX.init()
    .config(ValidXConfig.GLOBAL_NOT_NULL);  // 全局:拒绝 null

// 覆盖特定字段
validator.field("可选邮箱").allowNull().isEmail(optionalEmail)  // 此字段允许 null
         .field("必填手机").notEmpty().isPhone(phone)           // 要求非空
         .field("用户ID").isChineseIdCard(idCard);             // 使用全局 NOT_NULL

可用的局部状态方法:

  • .notNull() - 字段不能为 null(但可以是空字符串)
  • .notEmpty() - 字段不能为 null 或空字符串
  • .allowNull() - 允许 null 值(如果为 null 则跳过验证)
  • .allowEmpty() - 允许空字符串(但不允许 null)
  • .field("标签") - 为错误消息设置自定义字段标签
优先级规则

局部状态始终优先于全局配置:

ValidaX validator = ValidaX.init()
    .config(ValidXConfig.GLOBAL_NOT_EMPTY);  // 全局:拒绝 null 和空字符串

validator.allowNull().isEmail(email);  // 局部 allowNull() 覆盖全局配置

优先级: 局部状态 > 全局配置 > 默认行为

实际示例

示例 1:API 请求验证

public void validateUserRegistration(Map<String, Object> request) {
    ValidaX validator = ValidaX.init()
        .config(ValidXConfig.GLOBAL_NOT_EMPTY);  // 大部分字段必填

    validator.field("邮箱").isEmail(request.get("email"))
             .field("手机").isChinesePhone(request.get("phone"))
             .field("可选QQ").allowNull().isQQ(request.get("qq"))  // 可选字段
             .field("身份证").isChineseIdCard(request.get("idCard"));

    if (!validator.passed()) {
        throw new ValidationException(validator.getErrors());
    }
}

示例 2:表单更新(部分更新)

public void updateUserProfile(String userId, Map<String, Object> updates) {
    // 只验证正在更新的字段
    ValidaX validator = ValidaX.init();  // 默认:允许 null/空

    // 只验证更新 Map 中存在的字段
    if (updates.containsKey("email")) {
        validator.field("邮箱").notEmpty().isEmail(updates.get("email"));
    }

    if (updates.containsKey("phone")) {
        validator.field("手机").notEmpty().isChinesePhone(updates.get("phone"));
    }

    if (!validator.passed()) {
        throw new ValidationException(validator.getErrors());
    }
}

示例 3:混合要求

public void validateComplexForm(FormData data) {
    ValidaX validator = ValidaX.init()
        .config(ValidXConfig.GLOBAL_NOT_NULL);  // 大部分字段必填

    validator.field("邮箱").notEmpty().isEmail(data.getEmail())        // 必填且非空
             .field("手机").isChinesePhone(data.getPhone())            // 必填(使用全局)
             .field("QQ").allowNull().isQQ(data.getQq())               // 可选
             .field("微信").allowEmpty().isWeChat(data.getWeChat())    // 可以为空但不能为 null
             .field("网站").allowNull().isUrl(data.getWebsite());      // 可选

    if (!validator.passed()) {
        // 错误消息包含自定义字段标签
        throw new ValidationException(validator.getErrors());
    }
}
状态重置行为

重要: 局部状态(notNull/notEmpty/allowNull/allowEmpty)在每次验证方法调用后自动重置。这确保每个字段的验证是独立的。

ValidaX validator = ValidaX.init();

validator.notNull().isEmail(email1)   // notNull 应用于 email1
         .isEmail(email2)              // email2 使用默认行为(状态已重置)
         .notEmpty().isPhone(phone);   // notEmpty 仅应用于 phone
带字段标签的错误消息

使用 .field("标签") 时,错误消息将包含自定义标签:

ValidaX validator = ValidaX.init();

validator.field("用户邮箱").notEmpty().isEmail("")
         .field("联系电话").notNull().isChinesePhone(null);

if (!validator.passed()) {
    List<String> errors = validator.getErrors();
    // 错误: ["用户邮箱: 值不能是空字符串",
    //       "联系电话: 值不能为null"]
}

注意: 此配置 API 为链式验证中的 null/空值处理提供了细粒度控制,使其适用于复杂的业务场景,同时保持向后兼容性。

线程安全

ValidaX 实例不是线程安全的。 每次校验都应该创建新实例:

// ❌ 错误:跨线程共享实例
private static final ValidaX VALIDATOR = ValidaX.init();

public void validate(User user) {
    VALIDATOR.isEmail(user.getEmail());  // 线程不安全!
}

// ✅ 正确:每次校验创建新实例
public void validate(User user) {
    ValidaX validator = ValidaX.init()
        .isEmail(user.getEmail())
        .isPhone(user.getPhone());

    if (!validator.isValid()) {
        throw new ValidationException(validator.getErrorMessage());
    }
}

为什么? ValidaX 内部使用可变状态(局部要求标志、字段标识、错误列表),这些状态在校验链执行过程中会被修改。跨线程共享实例会导致竞态条件和不正确的校验结果。

线程安全的组件:

  • ValidXConfig 对象是不可变的,可以安全共享
  • 各个验证器类(如 ChineseIdCardValidator)是无状态的,可以复用

这种设计遵循与其他流式 API 相同的模式,如 StringBuilder、Java 8 Stream 和 Lombok Builder - 它们都采用"创建-使用-丢弃"的使用模式。

支持的验证注解

ValidX 提供了丰富的验证注解,涵盖多种场景。以下是目前支持的所有验证注解及其功能说明:

快速查询表

点击注解名称可快速跳转到详细文档。

分类注解说明
基础验证@Alpha纯英文字母验证
基础验证@AlphaDash字母数字下划线横线组合
基础验证@AlphaNumber字母数字组合验证
基础验证@Chinese纯中文字符验证
基础验证@ChineseAlpha中文字符和字母组合
基础验证@ChineseAlphaNum中文字符、字母和数字组合
基础验证@ChineseAlphaDash中文、字母、数字、下划线、横线组合
基础验证@Lower小写字符验证
基础验证@Upper大写字符验证
基础验证@Xdigit十六进制字符串验证
基础验证@Longitude经度验证(-180到180)
基础验证@Latitude纬度验证(-90到90)
基础验证@GeoPoint地理坐标对验证
基础验证@FutureDate未来日期验证
基础验证@PastDate过去日期验证
基础验证@HourMinute时分格式(HH:mm)
基础验证@HourMinuteSecond时分秒格式(HH:mm:ss)
基础验证@TimestampUnix时间戳验证
基础验证@CronExpressionCron表达式验证
基础验证@Duration时间段格式验证
基础验证@ExpressNumber快递单号验证
基础验证@StartsWith字符串前缀验证
基础验证@Contains字符串包含子串验证
基础验证@EndsWith字符串后缀验证
基础验证@In值必须在指定列表中
基础验证@NotIn值不能在指定列表中
基础验证@Enum枚举值验证
基础验证@Color颜色格式(HEX/RGB/RGBA)
基础验证@Password密码强度验证
基础验证@UUIDUUID格式验证
基础验证@Base64Base64编码验证
基础验证@JSONJSON格式验证
基础验证@JWTJWT令牌格式验证
基础验证@SemVer语义化版本验证
基础验证@FileExtension文件扩展名验证
基础验证@FileSize文件大小范围验证
基础验证@Age年龄验证(从出生日期或身份证)
基础验证@Port端口号验证(0-65535)
身份验证相关@ChineseIdCard中国身份证验证
身份验证相关@ChinesePassport中国护照验证
身份验证相关@ChineseMilitaryOfficer军官证验证
身份验证相关@ChineseSoldier士兵证验证
身份验证相关@ForeignerPermanentResidenceIdentity外国人永久居留身份证
身份验证相关@HKMacauResidence港澳居民居住证
身份验证相关@HKMacauPass港澳居民来往内地通行证
身份验证相关@TaiwanResidence台湾居民居住证
身份验证相关@TaiwanPass台湾居民来往大陆通行证
身份验证相关@ForeignerWorkPermit外国人工作许可证
身份验证相关@UnifiedSocialCreditCode统一社会信用代码
身份验证相关@ChinesePhone中国手机号验证
身份验证相关@ChineseLandline中国座机号验证
身份验证相关@ChinesePhoneOrLandline中国手机号或座机号
身份验证相关@PhoneNumber国际电话号码验证
身份验证相关@Email电子邮箱验证
金融验证相关@BankCard银行卡号验证(Luhn算法)
金融验证相关@CVVCVV/CVC安全码验证
金融验证相关@IBANIBAN账号验证
金融验证相关@SWIFTSWIFT/BIC代码验证
金融验证相关@StockCode股票代码验证
金融验证相关@TradeOrderNumber交易订单号验证
金融验证相关@FinancialProductCode金融产品代码验证
教育/职业资格验证@DegreeCertificate学位证书编号
教育/职业资格验证@Doctor医师资格证书
教育/职业资格验证@Teacher教师资格证书
教育/职业资格验证@Lawyer法律职业资格证书
教育/职业资格验证@PMPPMP证书验证
教育/职业资格验证@Constructor建造师证书
教育/职业资格验证@Accountant会计资格证书
网络相关@Domain域名验证
网络相关@IpIP地址验证(IPv4/IPv6)
网络相关@MacMAC地址验证
网络相关@UrlURL地址验证
网络相关@SubnetMask子网掩码验证
中国特定验证@ChineseLicensePlate中国车牌号验证
中国特定验证@ChinesePatent中国专利号验证
中国特定验证@ChineseTrademark中国商标注册号
中国特定验证@SoftwareCopyright软件著作权登记号
中国特定验证@WorkCopyright一般作品著作权登记号
中国特定验证@ChineseZipCode中国邮政编码验证
中国特定验证@DrugApproval药品批准文号验证
中国特定验证@DrugCode药品本位码验证
中国特定验证@MedicalDeviceRegistration医疗器械注册证号
中国特定验证@QQQQ号验证
中国特定验证@WeChat微信号验证
汽车相关验证@VIN车辆识别代码
汽车相关验证@VehicleEngine车辆发动机号验证
图书相关验证@ISBNISBN书号验证
图书相关验证@ISSNISSN期刊号验证
图书相关验证@DOIDOI标识符验证
图书相关验证@CLC中图分类号
图书相关验证@DDC杜威十进分类法
图书相关验证@ORCIDORCID研究者ID验证
图书相关验证@IPC国际专利分类号
手机相关验证@IMEIIMEI设备号验证

基础验证

@Alpha
  • 校验规则:纯英文字母验证,只允许大小写英文字母(a-z、A-Z)。
  • 示例格式:abcDEF
  • 使用示例:
    // 注解方式使用
    @Alpha
    private String code;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isAlpha("abcDEF");
    

↑ 返回快速查询表

@AlphaDash
  • 校验规则:字母数字下划线破折号验证,允许英文字母、数字、下划线和破折号。
  • 示例格式:abc-123_def
  • 使用示例:
    // 注解方式使用
    @AlphaDash
    private String code;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isAlphaDash("abc-123_def");
    

↑ 返回快速查询表

@AlphaNumber
  • 校验规则:字母和数字组合验证,只允许英文字母和数字。
  • 示例格式:abc123
  • 使用示例:
    // 注解方式使用
    @AlphaNumber
    private String code;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isAlphaNumber("abc123");
    

↑ 返回快速查询表

@Chinese
  • 校验规则:纯汉字验证,只允许中文字符(Unicode中文字符)。
  • 示例格式:汉字
  • 使用示例:
    // 注解方式使用
    @Chinese
    private String name;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isChinese("汉字");
    

↑ 返回快速查询表

@ChineseAlpha
  • 校验规则:汉字字母验证,允许中文字符和英文字母。
  • 示例格式:汉字abc
  • 使用示例:
    // 注解方式使用
    @ChineseAlpha
    private String name;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isChineseAlpha("汉字abc");
    

↑ 返回快速查询表

@ChineseAlphaNum
  • 校验规则:汉字字母数字验证,允许中文字符、英文字母和数字。
  • 示例格式:汉字abc123
  • 使用示例:
    // 注解方式使用
    @ChineseAlphaNum
    private String code;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isChineseAlphaNum("汉字abc123");
    

↑ 返回快速查询表

@ChineseAlphaDash
  • 校验规则:汉字字母数字下划线破折号验证,允许中文字符、英文字母、数字、下划线和破折号。
  • 示例格式:汉字abc-123_def
  • 使用示例:
    // 注解方式使用
    @ChineseAlphaDash
    private String code;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isChineseAlphaDash("汉字abc-123_def");
    

↑ 返回快速查询表

@Longitude
  • 校验规则:经度验证,验证经度值是否在-180到180之间。
  • 示例格式:0, 116.4074, -116.4074, 180, -180
  • 使用示例:
    // 注解方式使用
    @Longitude
    private String longitude;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isLongitude("116.4074");
    

↑ 返回快速查询表

@Latitude
  • 校验规则:纬度验证,验证纬度值是否在-90到90之间。
  • 示例格式:0, 39.9042, -39.9042, 90, -90
  • 使用示例:
    // 注解方式使用
    @Latitude
    private String latitude;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isLatitude("39.9042");
    

↑ 返回快速查询表

@GeoPoint
  • 校验规则:地理坐标对验证(经纬度),验证坐标格式是否正确且数值在有效范围内。
  • 支持格式:
    • 逗号分隔:"116.4074,39.9042" (经度,纬度)
    • 空格分隔:"116.4074 39.9042"
    • 逗号+空格:"116.4074, 39.9042"
  • 校验规则:
    • 经度范围:-180 到 180
    • 纬度范围:-90 到 90
    • 必须包含两个有效数值
  • 配置选项:
    • latitudeFirst:坐标顺序,false(默认)表示经度在前,true 表示纬度在前
    • separator:分隔符类型 - ANY(默认)、COMMASPACE
  • 使用示例:
    // 注解方式使用 - 默认(经度,纬度)
    @GeoPoint
    private String location;  // "116.4074,39.9042"
    
    // 纬度在前
    @GeoPoint(latitudeFirst = true)
    private String position;  // "39.9042,116.4074"
    
    // 仅逗号分隔
    @GeoPoint(separator = GeoPoint.SeparatorType.COMMA)
    private String gps;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isGeoPoint("116.4074,39.9042");  // 默认:经度在前
    validator.isGeoPoint("39.9042,116.4074", true);  // 纬度在前
    validator.isGeoPoint("116.4074,39.9042", false, GeoPoint.SeparatorType.COMMA);  // 指定分隔符
    

↑ 返回快速查询表

@FutureDate
  • 校验规则:未来日期验证,验证日期是否为未来日期。
  • 示例格式:2025-12-31, 2025-12-31 12:00:00
  • 使用示例:
    // 注解方式使用
    @FutureDate
    private String date;
    // 或包含今天
    @FutureDate(includeToday = true)
    private String deadline;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isFutureDate("2025-12-31");
    // 或包含今天
    validator.isFutureDate("2025-12-31", true);
    

↑ 返回快速查询表

@PastDate
  • 校验规则:过去日期验证,验证日期是否为过去日期。
  • 示例格式:2020-01-01, 2020-01-01 12:00:00
  • 使用示例:
    // 注解方式使用
    @PastDate
    private String date;
    // 或包含今天
    @PastDate(includeToday = true)
    private String birthDate;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isPastDate("2020-01-01");
    // 或包含今天
    validator.isPastDate("2020-01-01", true);
    

↑ 返回快速查询表

@HourMinute
  • 校验规则:小时分钟时间格式验证,验证时间格式是否为HH:mm。
  • 示例格式:23:20, 09:30
  • 使用示例:
    // 注解方式使用
    @HourMinute
    private String time;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isHourMinute("23:20");
    

↑ 返回快速查询表

@HourMinuteSecond
  • 校验规则:时分秒时间格式验证,验证时间格式是否为HH:mm:ss。
  • 示例格式:23:50:29, 09:30:05
  • 使用示例:
    // 注解方式使用
    @HourMinuteSecond
    private String time;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isHourMinuteSecond("23:50:29");
    

↑ 返回快速查询表

@In
  • 校验规则:单个元素、或者多个元素匹配验证,验证值是否在指定的值列表中。
  • 示例格式:任意指定值
  • 使用示例:
    // 注解方式使用 - 单个值验证
    @In({"value1", "value2"})
    private String status;
    
    // 注解方式使用 - 集合/数组验证(每个元素都必须在指定值列表中)
    @In({"admin", "user", "guest"})
    private List<String> roles;
    
    // 链式调用方式使用 - 单个值验证
    ValidaX validator = ValidaX.init();
    validator.isIn("value1", new String[]{"value1", "value2"});
    
    // 链式调用方式使用 - 集合验证
    List<String> roles = Arrays.asList("admin", "user");
    validator.isIn(roles, new String[]{"admin", "user", "guest"});
    

↑ 返回快速查询表

@NotIn
  • 校验规则:单个元素、或者多个元素不匹配验证,验证值是否不在指定的值列表中。
  • 示例格式:任意指定值之外的值
  • 使用示例:
    // 注解方式使用 - 单个值验证
    @NotIn({"value1", "value2"})
    private String status;
    
    // 注解方式使用 - 集合/数组验证(每个元素都不能在指定值列表中)
    @NotIn({"admin", "root", "superuser"})
    private List<String> forbiddenRoles;
    
    // 链式调用方式使用 - 单个值验证
    ValidaX validator = ValidaX.init();
    validator.isNotIn("value3", new String[]{"value1", "value2"});
    
    // 链式调用方式使用 - 集合验证
    List<String> roles = Arrays.asList("user", "guest");
    validator.isNotIn(roles, new String[]{"admin", "root", "superuser"});
    

↑ 返回快速查询表

@FileExtension
  • 校验规则:文件后缀名验证,验证文件名的后缀是否在指定的后缀列表中。
  • 示例格式:指定的文件后缀名
  • 使用示例:
    // 注解方式使用 不忽略大小写 默认是false
    @FileExtension(value = {"xls", "xlsx"})
    private String fileName;
    // 注解方式使用 忽略大小写
    @FileExtension(value = {"xls", "xlsx"}, ignoreCase = true)
    private String documentName;
    
  • 使用链式调用时也可以指定是否忽略大小写:
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    
    // 默认忽略大小写
    validator.isFileExtension("document.xls", new String[]{"XLS"});
    
    // 明确指定忽略大小写
    validator.isFileExtension("document.xls", new String[]{"XLS"}, true);
    
    // 不忽略大小写
    validator.isFileExtension("document.xls", new String[]{"XLS"}, false);
    

↑ 返回快速查询表

@FileSize
  • 校验规则:文件大小验证,验证文件大小是否在指定范围内。
  • 支持的类型:
    • java.io.File - File 对象
    • java.nio.file.Path - NIO Path 对象
    • byte[] - 字节数组
    • org.springframework.web.multipart.MultipartFile - Spring 文件上传对象(需要 Spring 依赖)
  • 配置选项:
    • min:最小文件大小(人性化格式,如 "1KB"、"10MB"),默认为 "0B"
    • max:最大文件大小(人性化格式,如 "1KB"、"10MB"),默认不限制
    • allowedTypes:允许的 MIME 类型(仅对 MultipartFile 有效)
  • 示例格式:带单位的文件大小,如 "10KB"、"5MB"、"1GB"
  • 使用示例:
    // 指定最小和最大值
    @FileSize(min = "1KB", max = "10MB")
    private File document;
    
    // 只指定最大值
    @FileSize(max = "5MB")
    private Path filePath;
    
    // 使用字节数组
    @FileSize(max = "1MB")
    private byte[] imageData;
    
    // 使用 MultipartFile(Spring)- 并限制 MIME 类型
    @FileSize(min = "100KB", max = "5MB", allowedTypes = {"image/jpeg", "image/png"})
    private MultipartFile avatar;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    
    // 只指定最大值
    validator.isFileSize(file, "10MB");
    
    // 指定最小和最大值
    validator.isFileSize(file, "1KB", "10MB");
    
  • 注意事项:
    • 支持的大小单位:B(字节)、KB(千字节)、MB(兆字节)、GB(千兆字节)、TB(太字节)
    • 1KB = 1024 字节(二进制单位)
    • 支持小数值:"1.5GB"、"0.5MB"
    • MIME 类型验证仅对 MultipartFile 有效
    • MultipartFile 支持使用反射实现,不需要强依赖 Spring

↑ 返回快速查询表

@Lower
  • 校验规则:小写字符验证,只允许小写英文字母。
  • 示例格式:abcdef
  • 使用示例:
    // 注解方式使用
    @Lower
    private String text;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isLower("abcdef");
    

↑ 返回快速查询表

@Upper
  • 校验规则:大写字符验证,只允许大写英文字母。
  • 示例格式:ABCDEF
  • 使用示例:
    // 注解方式使用
    @Upper
    private String text;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isUpper("ABCDEF");
    

↑ 返回快速查询表

@Xdigit
  • 校验规则:十六进制字符串验证,只允许十六进制字符(0-9, a-f, A-F)。
  • 示例格式:0a1B2c3D
  • 使用示例:
    // 注解方式使用
    @Xdigit
    private String hex;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isXdigit("0a1B2c3D");
    

↑ 返回快速查询表

@Password
  • 校验规则:密码强度验证,验证密码是否满足指定的强度要求。
  • 验证规则:
    • 最小长度--默认8位
    • 是否包含字母(大写)、字母(小写)、数字和特殊符号(默认都必须有)
    • requireUppercase:是否包含大写字母(默认值是)
    • requireLowercase:是否包含小写字母(默认值是)
    • requireDigit:是否包含数字(默认值是)
    • requireSpecialChar:是否包含特殊字符(默认值是)
  • 使用示例:
    // 使用默认规则(最小长度8位,必须包含大小写字母、数字和特殊字符)
    @Password
    private String password;
    
    // 指定最小长度
    @Password(minLength = 6)
    private String simplePassword;
    
    // 指定最小长度,并且不要求特殊字符
    @Password(minLength = 6, requireSpecialChar = false)
    private String customPassword;
    
  • 使用链式调用时也可以指定密码强度要求:
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    
    // 使用默认规则(最小长度8位,必须包含大小写字母、数字和特殊字符)
    validator.isPassword("MyPassword123!");
    
    // 指定最小长度
    validator.isPassword("mypassword123", 8);
    
    // 完全自定义规则(最小长度8位,不要求大写字母,要求小写字母、数字,不要求特殊字符)
    validator.isPassword("mypassword123", 8, false, true, true, false);
    

↑ 返回快速查询表

@UUID
  • 校验规则:UUID(通用唯一识别码)格式验证,支持标准格式(带连字符)和紧凑格式(不带连字符)。
  • 支持的格式:
    • 标准格式(带连字符):550e8400-e29b-41d4-a716-446655440000
    • 紧凑格式(不带连字符):550e8400e29b41d4a716446655440000(当 allowWithoutHyphens = true 时)
  • 配置选项:
    • allowWithoutHyphens:是否允许不带连字符的格式,默认为 false(仅允许标准格式)
  • 使用示例:
    // 只允许标准格式(带连字符)
    @UUID
    private String id;
    
    // 允许两种格式(带连字符和不带连字符)
    @UUID(allowWithoutHyphens = true)
    private String transactionId;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    
    // 验证标准格式
    validator.isUUID("550e8400-e29b-41d4-a716-446655440000");
    
    // 允许紧凑格式
    validator.isUUID("550e8400e29b41d4a716446655440000", true);
    
  • 注意事项:
    • UUID验证不区分大小写(大小写十六进制字符都允许)
    • 标准格式必须在特定位置包含恰好4个连字符
    • 紧凑格式必须是恰好32个十六进制字符
    • 支持所有常见的UUID版本(v1、v4等)

↑ 返回快速查询表

@Base64
  • 校验规则:Base64编码格式验证,支持标准Base64和URL-safe Base64格式。
  • 支持的格式:
    • 标准格式:A-Z, a-z, 0-9, +, / 加上填充符(=)
    • URL-safe格式:A-Z, a-z, 0-9, -, _ 加上填充符(=)
  • 配置选项:
    • urlSafe:是否使用URL-safe格式,默认为 false(使用标准格式)
    • allowNoPadding:是否允许不带填充符的格式,默认为 false(必须有填充)
  • 使用示例:
    // 只允许标准Base64格式
    @Base64
    private String data;
    
    // URL-safe Base64格式
    @Base64(urlSafe = true)
    private String urlSafeData;
    
    // 允许不带填充符的格式
    @Base64(allowNoPadding = true)
    private String noPaddingData;
    
    // URL-safe + 允许不带填充符
    @Base64(urlSafe = true, allowNoPadding = true)
    private String jwtPayload;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    
    // 验证标准格式
    validator.isBase64("SGVsbG8gV29ybGQ=");
    
    // 验证URL-safe格式
    validator.isBase64("SGVsbG8gV29ybGQ=", true);
    
    // 允许不带填充符的格式
    validator.isBase64("SGVsbG8gV29ybGQ", false, true);
    
  • 注意事项:
    • 标准Base64使用+/字符,URL-safe使用-_字符
    • 填充符=只能出现在末尾,最多2个
    • 字符串长度必须是4的倍数(除非启用allowNoPadding)
    • 常见应用场景:文件上传、JWT令牌、图片数据传输

↑ 返回快速查询表

@Age
  • 校验规则:基于出生日期或身份证号码的年龄验证,支持最小年龄和最大年龄限制。
  • 支持的类型:
    • java.time.LocalDate - 出生日期
    • java.util.Date - 出生日期
    • String - 出生日期字符串或身份证号码
  • 配置选项:
    • min:最小年龄(包含),0表示不限制,默认为0
    • max:最大年龄(包含),0表示不限制,默认为0
    • fromIdCard:是否从身份证号码中提取出生日期,默认为 false
    • dateFormat:日期格式(仅当字段类型为String且fromIdCard=false时有效),默认为"yyyy-MM-dd"
  • 使用示例:
    // 验证年龄在18到65岁之间
    @Age(min = 18, max = 65)
    private LocalDate birthDate;
    
    // 只验证最小年龄
    @Age(min = 18)
    private String birthDateStr;  // "1990-01-01"
    
    // 从身份证号提取年龄验证
    @Age(min = 18, max = 65, fromIdCard = true)
    private String idCard;
    
    // 指定日期格式
    @Age(min = 18, dateFormat = "yyyy/MM/dd")
    private String birthDate;  // "1990/01/01"
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    
    // 只验证最小年龄
    validator.isAge(LocalDate.now().minusYears(25), 18);
    
    // 验证年龄范围
    validator.isAge("1990-01-01", 18, 65);
    
    // 从身份证提取
    validator.isAge("11010119900101001X", 18, 65, true);
    
    // 自定义日期格式
    validator.isAge("1990/06/15", 18, 65, false, "yyyy/MM/dd");
    
  • 注意事项:
    • 年龄按周岁计算(从出生日期到当前日期的完整年数)
    • 支持15位和18位中国身份证号码格式
    • null或空值通过验证(由@NotNull/@NotEmpty处理)
    • 未来的出生日期视为0岁
    • 自动尝试常见日期格式:yyyy-MM-dd、yyyy/MM/dd、yyyyMMdd

↑ 返回快速查询表

@JSON
  • 校验规则:JSON格式验证,支持标准JSON语法,可配置类型限制、深度限制和长度限制。
  • 支持的类型:
    • OBJECT:仅JSON对象(如:{"key":"value"}
    • ARRAY:仅JSON数组(如:[1,2,3]
    • ANY:对象和数组都允许(默认)
  • 配置选项:
    • type:JSON类型限制(ANY/OBJECT/ARRAY),默认为ANY
    • strict:是否强制严格JSON语法,默认为 true
    • maxDepth:最大嵌套深度(0表示不限制),默认为0
    • maxLength:最大字符串长度(0表示不限制),默认为0
  • 示例格式:{"name":"John","age":30}, [1,2,3], {"users":[{"id":1}]}
  • 使用示例:
    // 只允许有效的JSON(任意类型)
    @JSON
    private String data;
    
    // 只允许JSON对象
    @JSON(type = JSON.JSONType.OBJECT)
    private String config;
    
    // 只允许JSON数组
    @JSON(type = JSON.JSONType.ARRAY)
    private String items;
    
    // 限制嵌套深度以防止深度嵌套结构
    @JSON(maxDepth = 5)
    private String jsonData;
    
    // 限制字符串长度以防止超大JSON
    @JSON(maxLength = 1000)
    private String jsonPayload;
    
    // 组合多个限制
    @JSON(type = JSON.JSONType.OBJECT, strict = true, maxDepth = 10, maxLength = 5000)
    private String apiRequest;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    
    // 验证任意JSON类型
    validator.isJSON("{\"name\":\"John\",\"age\":30}");
    
    // 验证特定类型
    validator.isJSON("[1,2,3]", JSON.JSONType.ARRAY);
    
    // 控制严格模式
    validator.isJSON("{\"key\":\"value\"}", JSON.JSONType.OBJECT, true);
    
    // 完全控制所有选项
    validator.isJSON("{\"data\":{\"nested\":true}}", JSON.JSONType.OBJECT, true, 5, 1000);
    
  • 注意事项:
    • 使用轻量级内置JSON解析器,无需外部依赖
    • 支持所有JSON类型:对象、数组、字符串、数字、布尔值、null
    • 处理转义序列(\n, \t, ", \等)和Unicode转义(\uXXXX)
    • 严格模式强制执行正确的JSON语法(无尾随逗号、引号键名)
    • 深度限制有助于防止深度嵌套结构导致的栈溢出
    • 长度限制有助于防止大型JSON字符串导致的内存问题
    • 常见应用场景:API请求/响应验证、配置文件验证、数据序列化

↑ 返回快速查询表

@PhoneNumber
  • 校验规则:国际电话号码验证,支持多种国际电话号码格式,包括E.164标准格式。
  • 支持的格式:
    • E.164格式:+8613812345678, +14155552671
    • 带空格:+86 138 1234 5678, +1 415 555 2671
    • 带连字符:+1-415-555-2671
    • 带括号:+1 (415) 555-2671, (555) 123-4567
    • 本地格式:13812345678, 138 1234 5678
    • 带分机号:+1-415-555-2671 ext. 123, +14155552671 x123, +14155552671#456
  • 配置选项:
    • countryCode:限制特定国家代码(如 "+86", "+1"),默认为空(接受所有国家)
    • allowExtension:是否允许分机号(ext., x, #),默认为 true
    • strict:严格模式要求必须包含国家代码(以+开头),默认为 false
  • 示例格式:+8613812345678, +1-415-555-2671, (555) 123-4567 ext. 123
  • 使用示例:
    // 允许任何有效的国际电话号码
    @PhoneNumber
    private String phoneNumber;
    
    // 只允许特定国家代码(中国)
    @PhoneNumber(countryCode = "+86")
    private String chinaPhone;
    
    // 只允许特定国家代码(美国)
    @PhoneNumber(countryCode = "+1")
    private String usaPhone;
    
    // 不允许分机号
    @PhoneNumber(allowExtension = false)
    private String directPhone;
    
    // 严格模式:必须包含国家代码
    @PhoneNumber(strict = true)
    private String internationalPhone;
    
    // 组合多个限制
    @PhoneNumber(countryCode = "+1", allowExtension = true, strict = true)
    private String companyPhone;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    
    // 验证任意电话号码
    validator.isPhoneNumber("+8613812345678");
    
    // 验证特定国家代码
    validator.isPhoneNumber("+14155552671", "+1");
    
    // 控制分机号
    validator.isPhoneNumber("+1-415-555-2671 ext. 123", "", true);
    
    // 完全控制所有选项
    validator.isPhoneNumber("+1-415-555-2671 ext. 123", "+1", true, true);
    
  • 注意事项:
    • 支持E.164国际标准格式(+后跟4-15位数字)
    • 接受多种格式字符:空格、连字符、括号、点号
    • 分机号格式:ext., extension, x, #
    • 国家代码长度:1-3位数字
    • 电话号码长度(仅数字):4-15个字符
    • 严格模式强制执行国际格式(必须以+开头)
    • 常见应用场景:用户注册、联系人管理、国际通信

↑ 返回快速查询表

@JWT
  • 校验规则:JWT(JSON Web Token)格式验证,验证JWT Token的基本格式是否正确。
  • JWT格式说明:
    • JWT由三部分组成,用点(.)分隔:header.payload.signature
    • Header:Base64URL编码的JSON对象,描述令牌类型和签名算法
    • Payload:Base64URL编码的JSON对象,包含声明(claims)
    • Signature:签名,用于验证令牌的完整性
    • 每部分都使用Base64URL编码(A-Z, a-z, 0-9, -, _)
  • 示例格式:
    • eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
  • 使用示例:
    // 注解方式使用
    @JWT
    private String token;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isJWT("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U");
    
  • 注意事项:
    • 此验证器只验证JWT的基本格式(三部分结构和Base64URL编码)
    • 不验证签名的有效性(需要密钥)
    • 不验证过期时间等声明
    • 常见应用场景:API认证、单点登录(SSO)、信息交换

↑ 返回快速查询表

@SemVer
  • 校验规则:语义化版本号(Semantic Versioning)格式验证,验证版本号是否符合SemVer 2.0.0规范。
  • 版本号格式说明:
    • 基础格式:MAJOR.MINOR.PATCH(主版本号.次版本号.修订号)
    • MAJOR:主版本号,不兼容的API修改时递增
    • MINOR:次版本号,向下兼容的功能性新增时递增
    • PATCH:修订号,向下兼容的问题修正时递增
    • 预发布版本:MAJOR.MINOR.PATCH-prerelease(如:1.0.0-alpha, 1.0.0-beta.1)
    • 构建元数据:MAJOR.MINOR.PATCH+build(如:1.0.0+20130313144700)
    • 完整格式:MAJOR.MINOR.PATCH-prerelease+build
  • 示例格式:
    • 基础版本:1.0.0, 2.1.3, 10.20.30
    • 预发布版本:1.0.0-alpha, 1.0.0-beta.1, 2.1.0-rc.2
    • 带构建元数据:1.0.0+20130313144700, 1.0.0+001
    • 完整格式:1.0.0-alpha+001, 1.0.0-beta+exp.sha.5114f85
    • 带v前缀(需开启):v1.0.0, v2.1.3-beta
  • 使用示例:
    // 注解方式使用 - 标准格式
    @SemVer
    private String version;
    
    // 注解方式使用 - 允许v前缀
    @SemVer(allowVPrefix = true)
    private String versionWithPrefix;
    
    // 链式调用方式使用 - 标准格式
    ValidaX validator = ValidaX.init();
    validator.isSemVer("1.0.0");
    validator.isSemVer("2.1.3-beta.1");
    
    // 链式调用方式使用 - 允许v前缀
    ValidaX validator2 = ValidaX.init();
    validator2.isSemVer("v1.0.0", true);
    validator2.isSemVer("v2.1.3-rc.1", true);
    
  • 注意事项:
    • 严格遵循SemVer 2.0.0规范( semver.org/
    • 版本号各部分不能有前导零(0除外),如:01.0.0是无效的
    • 版本号必须包含三个部分,如:1.0是无效的
    • 预发布标识符由字母数字和连字符组成,用点号分隔
    • 构建元数据不影响版本优先级,仅用于标识构建信息
    • 默认不允许v前缀,需要时通过allowVPrefix=true开启
    • 常见应用场景:软件版本管理、npm包版本、API版本控制、Git标签

↑ 返回快速查询表

@Timestamp
  • 校验规则:Unix时间戳格式验证,验证值是否为有效的Unix时间戳(支持秒和毫秒)。
  • 时间戳格式说明:
    • 秒级时间戳:10位数字字符串或Long值(如:1700000000
    • 毫秒级时间戳:13位数字字符串或Long值(如:1700000000000
    • 支持String和Long两种类型进行校验
  • 参数说明:
    • unit:指定时间戳单位,默认为ANY(同时接受秒和毫秒)
      • TimestampUnit.SECONDS — 仅接受10位(秒级)时间戳
      • TimestampUnit.MILLISECONDS — 仅接受13位(毫秒级)时间戳
      • TimestampUnit.ANY — 同时接受10位(秒级)和13位(毫秒级)时间戳
  • 使用示例:
    // 注解方式使用 - 同时接受秒和毫秒
    @Timestamp
    private String createTime;
    
    // 注解方式使用 - 仅接受秒级
    @Timestamp(unit = Timestamp.TimestampUnit.SECONDS)
    private String createTimeSec;
    
    // 注解方式使用 - 仅接受毫秒级
    @Timestamp(unit = Timestamp.TimestampUnit.MILLISECONDS)
    private Long createTimeMs;
    
    // 链式调用方式使用 - 默认ANY模式
    ValidaX validator = ValidaX.init();
    validator.isTimestamp("1700000000");
    validator.isTimestamp("1700000000000");
    
    // 链式调用方式使用 - 指定单位
    ValidaX validator2 = ValidaX.init();
    validator2.isTimestamp("1700000000", Timestamp.TimestampUnit.SECONDS);
    validator2.isTimestamp(1700000000000L, Timestamp.TimestampUnit.MILLISECONDS);
    
  • 注意事项:
    • 秒级时间戳必须恰好为10位数字(范围:0 ~ 9999999999)
    • 毫秒级时间戳必须恰好为13位数字(范围:0 ~ 99999999999)
    • 不接受负数值(Unix时间戳为非负数)
    • 不接受非数字字符(字母、特殊字符、小数、空格等)
    • null值不由本注解校验(需要null检查请搭配@NotNull使用)
    • 任何模式下,位数不正确的值(如9位、11位、12位)都会被拒绝
    • 常见应用场景:API时间戳参数、数据库时间字段、消息队列时间戳

↑ 返回快速查询表

@CronExpression
  • 校验规则:Cron表达式格式验证,验证值是否为有效的Cron表达式。
  • 支持的格式:
    • 6位格式:秒 分 时 日 月 周(如:0 0 12 * * ?
    • 7位格式:秒 分 时 日 月 周 年(如:0 0 12 * * ? 2025
  • 支持的特殊字符:
    • * : 匹配任意值
    • ? : 不指定值(仅用于日和周字段)
    • - : 范围(例如:1-5
    • , : 列举(例如:1,3,5
    • / : 步长(例如:0/15
    • L : 最后(例如:L表示月的最后一天)
    • W : 工作日(例如:15W
    • # : 第几个星期几(例如:6#3表示第3个星期五)
  • 示例格式:0 0 12 * * ?
  • 使用示例:
    // 注解方式使用
    @CronExpression
    private String schedule;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isCronExpression("0 0 12 * * ?");
    validator.isCronExpression("0 0/15 * * * ?");
    validator.isCronExpression("0 0 9 ? * MON-FRI");
    
  • 注意事项:
    • 日和周字段不能同时为非?
    • 支持月份英文缩写(JAN-DEC)和星期英文缩写(SUN-SAT)
    • 秒、分:0-59;时:0-23;日:1-31;月:1-12;周:0-7(0和7都代表周日)
    • 年份范围:1970-2099(可选字段)
    • 常见应用场景:定时任务、作业调度、定时器触发

↑ 返回快速查询表

@Duration
  • 校验规则:时间段格式验证,验证值是否为有效的时间段格式。
  • 支持的格式:
    • ISO 8601格式:以P开头的标准格式(例如:PT2H30MP1Y2M3DP1DT12H
    • 简化格式:数字+单位组合(例如:2h30m1y2mo3d1d12h
  • 支持的时间单位:
    • y/Y - 年(例如:P1Y1y
    • mo/MO - 月(简化格式使用"mo"以区分分钟"m")(例如:P2M2mo
    • d/D - 天(例如:P3D3d
    • h/H - 小时(例如:PT4H4h
    • m/M - 分钟(例如:PT30M30m
    • s/S - 秒(例如:PT45S45s
  • 配置选项:
    • format:指定时间段格式类型 - ISO_8601SIMPLEANY(默认)
  • 示例格式:
    • ISO 8601:PT2H30M(2小时30分钟)、P1Y2M3D(1年2月3天)、P1DT12H(1天12小时)
    • 简化格式:2h30m(2小时30分钟)、1y2mo3d(1年2月3天)、1d12h(1天12小时)
  • 使用示例:
    // 注解方式使用 - 接受任意格式
    @Duration
    private String duration;
    
    // 仅接受ISO 8601格式
    @Duration(format = Duration.DurationFormat.ISO_8601)
    private String isoDuration;
    
    // 仅接受简化格式
    @Duration(format = Duration.DurationFormat.SIMPLE)
    private String simpleDuration;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    
    // 验证任意格式
    validator.isDuration("PT2H30M");
    validator.isDuration("2h30m");
    validator.isDuration("P1Y2M3D");
    validator.isDuration("1y2mo3d");
    
    // 指定格式类型
    validator.isDuration("PT2H30M", Duration.DurationFormat.ISO_8601);
    validator.isDuration("2h30m", Duration.DurationFormat.SIMPLE);
    
  • 注意事项:
    • ISO 8601格式:P[nY][nM][nD][T[nH][nM][nS]] 其中P是必需的,T用于分隔日期和时间部分
    • 简化格式使用"mo"表示月份,以避免与"m"(分钟)混淆
    • 两种格式都不区分大小写
    • 必须至少指定一个时间单位
    • 年是ISO 8601标准支持的最大单位
    • 常见应用场景:任务持续时间、时间段配置、超时设置

↑ 返回快速查询表

@ExpressNumber
  • 校验规则:快递单号格式验证,验证值是否为有效的快递单号。
  • 支持的快递公司:
    • 顺丰速运 (SF_EXPRESS):12位数字
    • 圆通速递 (YTO_EXPRESS):YT开头+11-13位数字,或10-13位纯数字
    • 申通快递 (STO_EXPRESS):12位数字
    • 中通快递 (ZTO_EXPRESS):12位数字或字母+数字组合
    • 韵达快递 (YUNDA_EXPRESS):13位数字
    • 邮政EMS (EMS):E字母+9位数字+CN,或2位字母+9位数字+CN
    • 京东物流 (JD_LOGISTICS):JD开头+13-15位数字
    • 德邦快递 (DEPPON):8-9位数字
    • 天天快递 (TTKD_EXPRESS):12-14位数字
    • 百世快递 (BEST_EXPRESS):10-12位数字或字母
  • 配置选项:
    • companies:指定快递公司类型(默认为所有支持的公司)
  • 示例格式:
    • 顺丰速运:123456789012
    • 圆通速递:YT12345678901231234567890
    • 邮政EMS:E123456789CNEA123456789CN
    • 京东物流:JD1234567890123
    • 德邦快递:12345678123456789
  • 使用示例:
    // 注解方式使用 - 接受所有支持的快递公司
    @ExpressNumber
    private String trackingNumber;
    
    // 仅接受顺丰速运
    @ExpressNumber(companies = {ExpressNumber.ExpressCompany.SF_EXPRESS})
    private String sfNumber;
    
    // 接受顺丰速运或圆通速递
    @ExpressNumber(companies = {ExpressNumber.ExpressCompany.SF_EXPRESS, ExpressNumber.ExpressCompany.YTO_EXPRESS})
    private String mixedNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    
    // 验证任意支持的快递公司
    validator.isExpressNumber("123456789012");
    validator.isExpressNumber("E123456789CN");
    validator.isExpressNumber("JD1234567890123");
    
    // 指定快递公司类型
    validator.isExpressNumber("123456789012", ExpressNumber.ExpressCompany.SF_EXPRESS);
    validator.isExpressNumber("E123456789CN", ExpressNumber.ExpressCompany.EMS);
    
    // 多个快递公司
    validator.isExpressNumber("123456789012", ExpressNumber.ExpressCompany.SF_EXPRESS, ExpressNumber.ExpressCompany.STO_EXPRESS);
    
  • 注意事项:
    • 格式验证基于各快递公司的常见模式
    • 验证不会检查快递单号是否在快递公司系统中真实存在
    • 某些格式可能在不同快递公司之间重叠(例如12位数字)
    • EMS格式不区分大小写
    • 常见应用场景:电商订单管理、物流跟踪、发货验证

↑ 返回快速查询表

@StartsWith
  • 校验规则:前缀验证,验证字符串是否以指定的前缀开头。
  • 示例格式:以指定字符串开头
  • 使用示例:
    // 注解方式使用
    @StartsWith(startsWith = "prefix")
    private String code;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isStartsWith("prefix_string", new String[]{"prefix"});
    

↑ 返回快速查询表

@Contains
  • 校验规则:包含验证,验证字符串是否包含指定的子字符串。支持多种匹配模式(OR/AND)和忽略大小写。
  • 示例格式:"hello world" 包含 "hello""test@example.com" 同时包含 "@""."
  • 配置选项:
    • value:要匹配的子字符串数组
    • ignoreCase:是否忽略大小写,默认为 false
    • matchAll:匹配模式,默认为 false
      • false(默认):OR 逻辑 - 包含任意一个子字符串即可
      • true:AND 逻辑 - 必须包含所有子字符串
  • 使用示例:
    // 注解方式使用 - 单个子字符串(OR 逻辑)
    @Contains({"@"})
    private String email;
    
    // 多个子字符串(OR 逻辑 - 满足任意一个)
    @Contains({"产品", "服务"})
    private String description;
    
    // 多个子字符串(AND 逻辑 - 必须全部满足)
    @Contains(value = {"@", "."}, matchAll = true)
    private String emailStrict;
    
    // 忽略大小写匹配
    @Contains(value = {"HELLO"}, ignoreCase = true)
    private String greeting;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    
    // 基本用法(OR 逻辑)
    validator.isContains("hello world", new String[]{"hello"});
    
    // 多个子字符串(OR 逻辑)
    validator.isContains("test@example.com", new String[]{"@", ".com"});
    
    // 忽略大小写(OR 逻辑)
    validator.isContains("Hello World", new String[]{"hello"}, true);
    
    // AND 逻辑 - 必须包含所有子字符串
    validator.isContains("test@example.com", new String[]{"@", "."}, false, true);
    
  • 注意事项:
    • OR 逻辑(默认):只要包含数组中的任意一个子字符串即可通过验证
    • AND 逻辑matchAll = true):必须包含数组中的所有子字符串才能通过验证
    • 子字符串可以出现在任何位置(开头、中间或结尾)
    • 默认区分大小写;使用 ignoreCase = true 可忽略大小写
    • 常见应用场景:邮箱验证(@)、严格邮箱验证(@.)、URL检查(http://)、密码强度验证(必须包含多种字符类型)、内容过滤

↑ 返回快速查询表

@EndsWith
  • 校验规则:后缀验证,验证字符串是否以指定的后缀结尾。
  • 示例格式:以指定字符串结尾
  • 使用示例:
    // 注解方式使用
    @EndsWith(endsWith = "suffix")
    private String code;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isEndsWith("string_suffix", new String[]{"suffix"});
    

↑ 返回快速查询表

@Enum
  • 校验规则:单个元素或者多个元素的枚举值验证,验证其是否为指定枚举中的有效值。
  • 示例格式:指定枚举值之一
  • 使用示例:
    // 验证单个枚举值(默认验证code()值)
    @Enum(target = MyEnum.class)
    private String status;
    
    // 验证枚举的特定字段值
    @Enum(target = MyEnum.class, field = "type")
    private String statusCode;
    
    // 验证枚举值集合(每个元素都必须是指定枚举的有效值)
    @Enum(target = MyEnum.class)
    private List<String> statuses;
    
    // 验证特定字段值的枚举值集合
    @Enum(target = MyEnum.class, field = "type")
    private List<String> statusCodes;
    
  • 使用链式调用时也可以指定枚举字段:
    // 链式调用方式使用 - 单个值验证
    ValidaX validator = ValidaX.init();
    
    // 验证枚举的name()值(默认)
    validator.isEnum("VALUE1", MyEnum.class);
    
    // 验证枚举的特定字段值(如code字段)
    validator.isEnum("code001", MyEnum.class, "code");
    
    // 链式调用方式使用 - 集合验证
    List<String> statuses = Arrays.asList("VALUE1", "VALUE2");
    validator.isEnum(statuses, MyEnum.class);
    
    // 链式调用方式使用 - 数组验证
    String[] statusArray = {"VALUE1", "VALUE2"};
    validator.isEnum(statusArray, MyEnum.class);
    
  • 示例枚举类:
    public enum StatusEnum {
        ACTIVE("active"),
        INACTIVE("inactive");
        
        private final String code;
        
        StatusEnum(String code) {
            this.code = code;
        }
        
        public String getCode() {
            return code;
        }
    }
    

↑ 返回快速查询表

@Color
  • 校验规则:颜色格式验证,验证字符串是否为有效的HEX颜色值,支持 #FFF 或 #FFFFFF 格式。
  • 示例格式:#FF0000, #F00, #ffffff, #000
  • 使用示例:
    // 注解方式使用
    @Color
    private String color;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isColor("#FF0000");
    

↑ 返回快速查询表

身份验证相关

@ChineseIdCard
  • 校验规则:中国大陆身份证号码验证,支持18位和15位身份证号码。
  • 示例格式:11010119900307211X (18位) 或 11010119900307211 (15位)
  • 使用示例:
    // 注解方式使用
    @ChineseIdCard
    private String idCard;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isChineseIdCard("11010119900307211X");
    

↑ 返回快速查询表

@ChinesePassport
  • 校验规则:中国护照号码验证,支持各种类型的中国护照号码。
  • 示例格式:G12345678, E12345678, S12345678, D1234567, P1234567
  • 使用示例:
    // 注解方式使用
    @ChinesePassport
    private String passportNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isChinesePassport("G12345678");
    

↑ 返回快速查询表

@ChineseMilitaryOfficer
  • 校验规则:中国军官证验证,支持各种类型的中国军官证。
  • 示例格式:军字第1234567号, 海字第1234567号
  • 使用示例:
    // 注解方式使用
    @ChineseMilitaryOfficer
    private String certificateNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isChineseMilitaryOfficer("军字第1234567号");
    

↑ 返回快速查询表

@ChineseSoldier
  • 校验规则:中国士兵证验证,支持各种类型的中国士兵证。
  • 示例格式:沈字第0100000号
  • 使用示例:
    // 注解方式使用
    @ChineseSoldier
    private String certificateNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isChineseSoldier("沈字第0100000号");
    

↑ 返回快速查询表

@ForeignerPermanentResidenceIdentity
  • 校验规则:外国人永久居留身份证验证,验证外国人永久居留身份证号码。
  • 示例格式:911124198108030028
  • 使用示例:
    // 注解方式使用
    @ForeignerPermanentResidenceIdentity
    private String identityNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isForeignerPermanentResidenceIdentity("911124198108030028");
    

↑ 返回快速查询表

@HKMacauResidence
  • 校验规则:港澳居民居住证验证,验证港澳居民居住证号码。
  • 示例格式:810000000000000001, 82000000000000000X
  • 使用示例:
    // 注解方式使用
    @HKMacauResidence
    private String residenceNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isHKMacauResidence("810000000000000001");
    

↑ 返回快速查询表

@HKMacauPass
  • 校验规则:港澳居民来往内地通行证(回乡证)验证,验证港澳居民来往内地通行证号码。
  • 示例格式:H1234567800, M1234567801
  • 使用示例:
    // 注解方式使用
    @HKMacauPass
    private String passNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isHKMacauPass("H1234567800");
    

↑ 返回快速查询表

@TaiwanResidence
  • 校验规则:台湾居民居住证验证,验证台湾居民居住证号码。
  • 示例格式:830000000000000001
  • 使用示例:
    // 注解方式使用
    @TaiwanResidence
    private String residenceNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isTaiwanResidence("830000000000000001");
    

↑ 返回快速查询表

@TaiwanPass
  • 校验规则:台湾居民来往大陆通行证(台胞证)验证,验证台湾居民来往大陆通行证号码。
  • 示例格式:1234567800
  • 使用示例:
    // 注解方式使用
    @TaiwanPass
    private String passNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isTaiwanPass("1234567800");
    

↑ 返回快速查询表

@ForeignerWorkPermit
  • 校验规则:外国人工作许可证验证,验证外国人工作许可证号码。
  • 示例格式:包含字母和数字的组合
  • 使用示例:
    // 注解方式使用
    @ForeignerWorkPermit
    private String permitNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isForeignerWorkPermit(" foreigners work permit number ");
    

↑ 返回快速查询表

@UnifiedSocialCreditCode
  • 校验规则:统一社会信用代码验证,验证统一社会信用代码。
  • 示例格式:91350100M000100Y43
  • 使用示例:
    // 注解方式使用
    @UnifiedSocialCreditCode
    private String creditCode;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isUnifiedSocialCreditCode("91350100M000100Y43");
    

↑ 返回快速查询表

@ChinesePhoneOrLandline
  • 校验规则:中国电话号码验证,支持手机号和固定电话。
  • 示例格式:支持手机号和固定电话
  • 使用示例:
    // 注解方式使用
    @ChinesePhoneOrLandline
    private String phoneNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isChinesePhoneOrLandline("010-12345678");
    

↑ 返回快速查询表

@ChinesePhone
  • 校验规则:中国手机号码验证,验证中国手机号码。
  • 示例格式:11位手机号码
  • 使用示例:
    // 注解方式使用
    @ChinesePhone
    private String phoneNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isChinesePhone("13812345678");
    

↑ 返回快速查询表

@ChineseLandline
  • 校验规则:中国固定电话验证,验证中国固定电话号码。
  • 示例格式:支持区号和分机号
  • 使用示例:
    // 注解方式使用
    @ChineseLandline
    private String phoneNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isChineseLandline("010-12345678");
    

↑ 返回快速查询表

金融验证相关

@BankCard
  • 校验规则:银行卡验证,使用Luhn算法验证银行卡号码的有效性。
  • 示例格式:
    • Visa卡号:4012888888881881
    • MasterCard卡号:5555555555554444
    • 带空格的卡号:4012 8888 8888 1881
    • 带连字符的卡号:4012-8888-8888-1881
  • 使用示例:
    // 注解方式使用
    @BankCard
    private String cardNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isBankCard("4012888888881881");
    

↑ 返回快速查询表

@CVV
  • 校验规则:CVV/CVC安全码验证,验证信用卡背面的3位或4位安全码。
  • 示例格式:123, 1234
  • 使用示例:
    // 注解方式使用
    @CVV
    private String cvv;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isCVV("123");
    

↑ 返回快速查询表

@IBAN
  • 校验规则:IBAN国际银行账户号码验证,验证国际银行账户号码(IBAN)格式和校验位。
  • 示例格式:DE44500800000123456789, GB29NWBK60161331926819
  • 使用示例:
    // 注解方式使用
    @IBAN
    private String iban;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isIBAN("DE44500800000123456789");
    

↑ 返回快速查询表

@SWIFT
  • 校验规则:SWIFT/BIC代码验证,验证SWIFT/BIC银行代码格式,用于国际电汇中识别特定银行。
  • 示例格式:COBADEFF, DEUTDEFFXXX
  • 使用示例:
    // 注解方式使用
    @SWIFT
    private String swiftCode;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isSWIFT("COBADEFF");
    

↑ 返回快速查询表

@StockCode
  • 校验规则:股票代码验证,验证不同交易所的股票代码格式。

  • 支持的交易所及格式:

    • 上海证券交易所: 6位数字,以6开头 (如: 600000)
    • 深圳证券交易所: 6位数字,以0、3或4开头 (如: 000001, 300001, 400001)
    • 香港联合交易所: 4-5位数字 (如: 00700, 3690)
    • 纽约证券交易所: 1-5个字母,可能包含点号 (如: AAPL, BRK.A, BRK.B)
  • 使用示例:

    // 默认支持所有交易所
    @StockCode
    private String stockCode;
    
    // 只支持上海证券交易所
    @StockCode(exchanges = {StockCode.Exchange.SHANGHAI})
    private String shanghaiStock;
    
    // 支持上海证券交易所和纽约证券交易所
    @StockCode(exchanges = {StockCode.Exchange.SHANGHAI, StockCode.Exchange.NEW_YORK})
    private String mixedStock;
    
    // 只支持港股和美股
    @StockCode(exchanges = {StockCode.Exchange.HONG_KONG, StockCode.Exchange.NEW_YORK})
    private String internationalStock;
    
  • 使用链式调用时也可以指定交易所范围:

    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    
    // 默认支持所有交易所
    validator.isStockCode("600000");
    
    // 只验证上海证券交易所
    validator.isStockCode("600000", StockCode.Exchange.SHANGHAI);
    
    // 验证上海或深圳交易所
    validator.isStockCode("000001", StockCode.Exchange.SHANGHAI, StockCode.Exchange.SHENZHEN);
    
    // 验证香港或纽约交易所
    validator.isStockCode("00700", StockCode.Exchange.HONG_KONG, StockCode.Exchange.NEW_YORK);
    

↑ 返回快速查询表

@TradeOrderNumber
  • 校验规则:交易订单号验证,验证金融交易订单号的格式。

  • 支持的格式:

    • T开头+18位数字格式 (如: T123456789012345678)
    • 纯18位数字格式 (如: 123456789012345678)
    • UUID格式(带连字符或不带连字符)(如: 550e8400-e29b-41d4-a716-446655440000 或 550e8400e29b41d4a716446655440000)
  • 使用示例:

    // 默认验证所有支持的格式
    @TradeOrderNumber
    private String orderNumber;
    
  • 使用链式调用方式:

    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    
    // 验证T开头+18位数字格式
    validator.isTradeOrderNumber("T123456789012345678");
    
    // 验证纯18位数字格式
    validator.isTradeOrderNumber("123456789012345678");
    
    // 验证UUID格式(带连字符)
    validator.isTradeOrderNumber("550e8400-e29b-41d4-a716-446655440000");
    
    // 验证UUID格式(不带连字符)
    validator.isTradeOrderNumber("550e8400e29b41d4a716446655440000");
    

↑ 返回快速查询表

@FinancialProductCode
  • 校验规则:金融产品代码验证,验证基金代码、债券代码等金融产品的代码格式。

  • 支持的产品类型及格式:

    • 基金产品:
      • 上海证券交易所基金:以5开头的6位数字 (如: 500001, 510000)
      • 深圳证券交易所基金:以1开头的6位数字 (如: 100001, 150000)
    • 债券产品:
      • 国债:以10开头的6位数字 (如: 100001, 101234)
      • 企业债:以11开头的6位数字 (如: 110001, 111234)
      • 可转债:以12开头的6位数字 (如: 120001, 121234)
      • 公司债:以13开头的6位数字 (如: 130001, 131234)
  • 使用示例:

    // 默认支持所有产品类型
    @FinancialProductCode
    private String productCode;
    
    // 只支持基金产品
    @FinancialProductCode(productTypes = {FinancialProductCode.ProductType.FUND})
    private String fundCode;
    
    // 只支持债券产品
    @FinancialProductCode(productTypes = {FinancialProductCode.ProductType.BOND})
    private String bondCode;
    
    // 支持基金和债券产品
    @FinancialProductCode(productTypes = {FinancialProductCode.ProductType.FUND, FinancialProductCode.ProductType.BOND})
    private String mixedProductCode;
    
  • 使用链式调用时也可以指定产品类型范围:

    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    
    // 默认支持所有产品类型
    validator.isFinancialProductCode("500001");
    
    // 只验证基金产品
    validator.isFinancialProductCode("500001", FinancialProductCode.ProductType.FUND);
    
    // 只验证债券产品
    validator.isFinancialProductCode("100001", FinancialProductCode.ProductType.BOND);
    
    // 验证基金和债券产品
    validator.isFinancialProductCode("500001", FinancialProductCode.ProductType.FUND, FinancialProductCode.ProductType.BOND);
    

↑ 返回快速查询表

教育/职业资格验证/认证相关的验证

@DegreeCertificate
  • 校验规则:学位证书编号验证,验证中国学位证书编号格式。支持两种格式:
    • 普通学位证书:16位数字格式
    • 特殊学位证书:以特定字母开头后跟16位字符的格式
  • 示例格式:1075522008000001, C1047642016057017
  • 使用示例:
    // 注解方式使用
    @DegreeCertificate
    private String certificateNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isDegreeCertificate("1075522008000001");
    

↑ 返回快速查询表

@Doctor
  • 校验规则:医师资格证编号验证,验证医师资格证编号。
  • 规则说明:医师资格证编号由24位或27位字符组成,包括年度代码、省级行政区代码、执业医师级别代码、执业医师类别代码和居民身份证号码
  • 示例格式:20251111014406081973100014 (24位) 或 20251111014406081973100014123 (27位)
  • 使用示例:
    // 注解方式使用
    @Doctor
    private String certificateNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isDoctor("20251111014406081973100014");
    

↑ 返回快速查询表

@Teacher
  • 校验规则:教师资格证编号验证,验证教师资格证编号。
  • 规则说明:共17位数字,分别表示年度代码、省级行政区代码、认定机构代码、资格类型代码、性别代码和序号代码
  • 示例格式:20253412345678901
  • 使用示例:
    // 注解方式使用
    @Teacher
    private String certificateNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isTeacher("20253412345678901");
    

↑ 返回快速查询表

@Lawyer
  • 校验规则:法律职业资格证书/律师执业证验证,验证法律职业资格证书或律师执业证。
  • 格式说明:
    • 律师执业证:17位数字,以1开头,格式为1 + 省代码(2位) + 市代码(2位) + 年份(4位) + 类别代码(1位) + 性别代码(1位) + 序列号(6位)
    • 法律职业资格证书:14位或16位数字
  • 示例格式:
    • 律师执业证:11101201810123456 (1+北京市11+朝阳区01+2018年+专职律师1+男0+序列号123456)
    • 法律职业资格证书:2010130103210001 (年份2010+省代码13+市代码01+区代码03+序列号210001)
  • 使用示例:
    // 注解方式使用
    @Lawyer
    private String certificateNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isLawyer("11101201810123456");
    

↑ 返回快速查询表

@PMP
  • 校验规则:PMP证书编号验证,验证PMP(Project Management Professional)证书编号格式
  • 规则说明:PMP证书编号通常为7位数字或包含特定前缀的组合
  • 示例格式:1234567, PMP123456
  • 使用示例:
    // 注解方式使用
    @PMP
    private String certificateNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isPMP("1234567");
    

↑ 返回快速查询表

@Constructor
  • 校验规则:建造师证书编号验证,验证一级/二级建造师证书编号格式
  • 规则说明:建造师证书编号由一个汉字和12位阿拉伯数字组成,总共13位
  • 示例格式:京111050700001, 鄂242050700001
  • 使用示例:
    // 注解方式使用
    @Constructor
    private String certificateNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isConstructor("京111050700001");
    

↑ 返回快速查询表

@Accountant
  • 校验规则:会计资格证书编号验证,验证会计资格证书编号格式
  • 规则说明:会计资格证书编号由11位数字组成,包含年份代码、地区代码等信息
  • 示例格式:21010203451, 22310512342
  • 使用示例:
    // 注解方式使用
    @Accountant
    private String certificateNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isAccountant("21010203451");
    

↑ 返回快速查询表

网络相关

@Domain
  • 校验规则:域名验证,验证域名格式。
  • 示例格式:example.com, www.example.com
  • 使用示例:
    // 注解方式使用
    @Domain
    private String domain;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isDomain("example.com");
    

↑ 返回快速查询表

@Ip
  • 校验规则:IP地址验证,支持IPv4和IPv6地址验证,可通过参数指定验证的IP版本。
  • 支持的版本:
    • Ip.IpVersion.V4:只验证IPv4地址(如:192.168.1.1
    • Ip.IpVersion.V6:只验证IPv6地址(如:2001:0db8:85a3::8a2e:0370:7334
    • Ip.IpVersion.ANY:同时验证IPv4和IPv6地址(默认)
  • 示例格式:
    • IPv4: 192.168.1.1, 10.0.0.1
    • IPv6: 2001:0db8:85a3:0000:0000:8a2e:0370:7334, ::1, fe80::1
  • 使用示例:
    // 注解方式使用 - 同时支持IPv4和IPv6(默认)
    @Ip
    private String ipAddress;
    
    // 只验证IPv4地址
    @Ip(version = Ip.IpVersion.V4)
    private String ipv4Address;
    
    // 只验证IPv6地址
    @Ip(version = Ip.IpVersion.V6)
    private String ipv6Address;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    
    // 验证任意IP地址(默认)
    validator.isIp("192.168.1.1");
    
    // 只验证IPv4地址
    validator.isIp("192.168.1.1", Ip.IpVersion.V4);
    
    // 只验证IPv6地址
    validator.isIp("2001:0db8:85a3::8a2e:0370:7334", Ip.IpVersion.V6);
    
    // 同时支持IPv4和IPv6
    validator.isIp("192.168.1.1", Ip.IpVersion.ANY);
    

↑ 返回快速查询表

@Mac
  • 校验规则:MAC地址验证,验证MAC地址。
  • 示例格式:00:1A:2B:3C:4D:5E, 00-1A-2B-3C-4D-5E
  • 使用示例:
    // 注解方式使用
    @Mac
    private String macAddress;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isMac("00:1A:2B:3C:4D:5E");
    

↑ 返回快速查询表

@Url
  • 校验规则:URL地址验证,验证URL地址格式。
  • 示例格式:http://example.com, https://example.com/path
  • 使用示例:
    // 注解方式使用
    @Url
    private String url;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isUrl("http://example.com");
    

↑ 返回快速查询表

@Email
  • 校验规则:邮箱地址验证,验证邮箱地址格式。
  • 示例格式:test@example.com, user.name@domain.co.uk
  • 使用示例:
    // 注解方式使用
    @Email
    private String email;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isEmail("test@example.com");
    

↑ 返回快速查询表

@SubnetMask
  • 校验规则:子网掩码验证,验证子网掩码格式。
  • 示例格式:255.255.255.0, 255.0.0.0
  • 使用示例:
    // 注解方式使用
    @SubnetMask
    private String subnetMask;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isSubnetMask("255.255.255.0");
    

↑ 返回快速查询表

@Port
  • 校验规则:端口号验证,验证端口号是否在0-65535范围内。
  • 示例格式:0-65535之间的整数
  • 使用示例:
    // 注解方式使用
    @Port
    private String port;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isPort("8080");
    

↑ 返回快速查询表

中国特定验证

@ChineseLicensePlate
  • 校验规则:中国车牌号验证,验证中国车牌号码。
  • 示例格式:京A12345, 京A12345D
  • 使用示例:
    // 注解方式使用
    @ChineseLicensePlate
    private String licensePlate;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isChineseLicensePlate("京A12345");
    

↑ 返回快速查询表

@ChinesePatent
  • 校验规则:中国专利号验证,验证中国专利号。
  • 示例格式:ZL2013106997442
  • 使用示例:
    // 注解方式使用
    @ChinesePatent
    private String patentNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isChinesePatent("ZL2013106997442");
    

↑ 返回快速查询表

@ChineseTrademark
  • 校验规则:中国商标注册号验证,验证中国商标注册号。
  • 示例格式:1234567, 第1234567号
  • 使用示例:
    // 注解方式使用
    @ChineseTrademark
    private String trademarkNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isChineseTrademark("1234567");
    

↑ 返回快速查询表

@SoftwareCopyright
  • 校验规则:计算机软件著作权登记号验证,验证计算机软件著作权登记号。
  • 示例格式:软著登字第2023001234号
  • 使用示例:
    // 注解方式使用
    @SoftwareCopyright
    private String copyrightNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isSoftwareCopyright("软著登字第2023001234号");
    

↑ 返回快速查询表

@WorkCopyright
  • 校验规则:一般作品著作权登记号验证,验证一般作品著作权登记号。
  • 示例格式:作登字22-2023-A-0018号
  • 使用示例:
    // 注解方式使用
    @WorkCopyright
    private String copyrightNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isWorkCopyright("作登字22-2023-A-0018号");
    

↑ 返回快速查询表

@ChineseZipCode
  • 校验规则:中国邮政编码验证,验证中国邮政编码。
  • 示例格式:100000, 200000
  • 使用示例:
    // 注解方式使用
    @ChineseZipCode
    private String zipCode;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isChineseZipCode("100000");
    

↑ 返回快速查询表

@DrugApproval
  • 校验规则:验证字符串是否是有效的中国药品批准文号.药品批准文号是国家药品监督管理部门批准药品生产企业生产药品的文号
  • 示例格式: 国药准字H20210039, 国药准字ZC20171003, 国药准字HJ20233150
  • 使用示例:
    // 注解方式使用
    @DrugApproval
    private String approvalNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isDrugApproval("国药准字H20210039");
    

↑ 返回快速查询表

@DrugCode
  • 校验规则:验证字符串是否是有效的中国药品本位码.药品本位码是以69开头,20位数字,最后一位为GS1校验位
  • 示例格式: 69012345678901234563, 69123456789012345678
  • 使用示例:
    // 注解方式使用
    @DrugCode
    private String drugCode;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isDrugCode("69012345678901234563");
    

↑ 返回快速查询表

@MedicalDeviceRegistration
  • 校验规则:医疗器械注册证号验证,用于验证中国医疗器械注册证号格式。
  • 示例格式:国械注准20243010001, 粤械注准20242020002, 国械注进20242030003
  • 使用示例:
    // 注解方式使用
    @MedicalDeviceRegistration
    private String registrationNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isMedicalDeviceRegistration("国械注准20243010001");
    

↑ 返回快速查询表

@QQ
  • 校验规则:QQ号码验证,验证QQ号码。
  • 示例格式:123456789
  • 使用示例:
    // 注解方式使用
    @QQ
    private String qqNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isQQ("123456789");
    

↑ 返回快速查询表

@WeChat
  • 校验规则:微信账号验证,验证微信账号格式。
  • 规则说明:
    • 长度为6-20个字符
    • 必须以字母开头
    • 只能包含字母、数字、下划线和减号
  • 示例格式:wechat123, WeChat_123, WeChat-123
  • 使用示例:
    // 注解方式使用
    @WeChat
    private String wechatId;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isWeChat("wechat123");
    

↑ 返回快速查询表

汽车相关的验证

@VIN
  • 校验规则:验证车辆识别号码(VIN)格式和校验位。
  • 示例格式:WP0AJ2972LL122844
  • 使用示例:
    // 注解方式使用
    @VIN
    private String vin;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isVIN("WP0AJ2972LL122844");
    

↑ 返回快速查询表

@VehicleEngine
  • 校验规则:验证车辆发动机编码格式。
  • 示例格式:123456, ABC123, 123ABC456
  • 使用示例:
    // 注解方式使用
    @VehicleEngine
    private String engineCode;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isVehicleEngine("123456");
    

↑ 返回快速查询表

图书相关的验证

@ISBN
  • 校验规则:国际标准书号验证,支持10位和13位ISBN格式。
  • 示例格式:9780306406157 (13位) 或 0306406152 (10位)
  • 使用示例:
    // 注解方式使用
    @ISBN
    private String isbn;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isISBN("9780306406157");
    

↑ 返回快速查询表

@ISSN
  • 校验规则:国际标准连续出版物号验证,支持8位ISSN格式。
  • 示例格式:0317-847103178471
  • 使用示例:
    // 注解方式使用
    @ISSN
    private String issn;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isISSN("0317-8471");
    

↑ 返回快速查询表

@DOI
  • 校验规则:数字对象标识符验证,用于数字资源的唯一标识,广泛用于学术出版物。
  • 示例格式:以"10."开头,如 10.1000/182
  • 使用示例:
    // 注解方式使用
    @DOI
    private String doi;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isDOI("10.1000/182");
    

↑ 返回快速查询表

@CLC
  • 校验规则:验证字符串是否是有效的中国图书馆分类法(CLC)分类号。中国图书馆分类法是中国图书馆普遍采用的图书分类法
  • 示例格式: A, B, TP, TP3, TP311, TP311.1, TP311.138, TP311.138.S6, O175.2, R329.2, F272.3
  • 使用示例:
    // 注解方式使用
    @CLC
    private String clcNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isCLC("TP311.138");
    

↑ 返回快速查询表

@DDC
  • 校验规则:验证字符串是否是有效的杜威十进制分类法(DDC)分类号。杜威十进制分类法是广泛应用于图书馆的分类系统
  • 示例格式: 000, 100, 200, ..., 999, 510, 516.3, 330.94
  • 使用示例:
    // 注解方式使用
    @DDC
    private String ddcNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isDDC("516.3");
    

↑ 返回快速查询表

@ORCID
  • 校验规则:开放研究者与贡献者身份识别码验证,用于唯一标识学术作者和贡献者。
  • 示例格式:0000-0002-1825-00970000000218250097
  • 使用示例:
    // 注解方式使用
    @ORCID
    private String orcidId;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isORCID("0000-0002-1825-0097");
    

↑ 返回快速查询表

@IPC
  • 校验规则:国际专利分类号验证,用于标识专利技术领域。
  • 示例格式:A01B1/00, A01B1/01, H01B12/00
  • 使用示例:
    // 注解方式使用
    @IPC
    private String ipcNumber;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isIPC("A01B1/00");
    

↑ 返回快速查询表

手机相关的验证

@IMEI
  • 校验规则:IMEI验证,验证字符串是否为有效的国际移动设备识别码。
  • 示例格式:123412341234564123412-341234564
  • 使用示例:
    // 注解方式使用
    @IMEI
    private String imei;
    
    // 链式调用方式使用
    ValidaX validator = ValidaX.init();
    validator.isIMEI("123412341234564");
    

↑ 返回快速查询表

更多验证注解

如果您需要更多的验证功能,欢迎通过以下方式反馈:

贡献

欢迎通过以下方式参与这个项目:

  • 在 GitHub Issues 中反馈使用问题或提出改进建议
  • 提交 Pull Request 贡献代码或文档
  • 分享使用经验和最佳实践