ValidX 迁移指南v1.0.0/v1.0.1 → v1.1.0本文档描述从 v1.0.0 或 v1.0.1 升级到 v1.1.0 时的破坏性变更和迁移步骤。概述版本 1.1.0 对FutureDate和PastDate注解的日期时间格式支持引入了破坏性变更。影响级别高- 使用日期时间字符串如2025-12-31 12:00:00与FutureDate或PastDate的应用会受到影响。破坏性变更1. FutureDate - 不再支持时间组件v1.0.0/v1.0.1 行为FutureDateprivateStringdate;// ✅ 两种格式都自动支持date2025-12-31;// 解析为 LocalDatedate2025-12-31 12:00:00;// 解析为 LocalDateTime然后转换为 LocalDate工作原理首先尝试解析为yyyy-MM-dd格式如果失败再尝试解析为yyyy-MM-dd HH:mm:ss格式自动支持纯日期和日期时间字符v1.1.0 行为FutureDateprivateStringdate;// ✅ 纯日期格式仍然有效date2025-12-31;// ❌ 日期时间格式不再有效date2025-12-31 12:00:00;// 验证失败变更内容仅支持纯日期格式无时间组件默认 patternyyyy-MM-dd可通过pattern参数指定自定义格式但不能包含时间符号HH、mm、ss 等如果pattern包含时间符号初始化时会抛出IllegalArgumentException2. PastDate - 不再支持时间组件v1.0.0/v1.0.1 行为PastDateprivateStringdate;// ✅ 两种格式都自动支持date2020-01-01;// 解析为 LocalDatedate2020-01-01 12:00:00;// 解析为 LocalDateTime然后转换为 LocalDatev1.1.0 行为PastDateprivateStringdate;// ✅ 纯日期格式仍然有效date2020-01-01;// ❌ 日期时间格式不再有效date2020-01-01 12:00:00;// 验证失败变更内容与FutureDate相同 - 仅支持纯日期格式pattern 参数不能包含时间符号迁移步骤步骤 1识别受影响的代码在代码库中搜索使用日期时间字符串的FutureDate和PastDate# 搜索潜在的日期时间使用模式grep-rFutureDate\|PastDate--include*.javayour-project/查找使用FutureDate或PastDate注解的 String 字段包含时间组件的值如2025-12-31 12:00:00使用isFutureDate()或isPastDate()的链式验证步骤 2选择迁移策略对于每个受影响的使用场景选择以下策略之一策略 A切换到 FutureDateTime / PastDateTime⭐推荐使用 v1.1.0 新增的专用日期时间注解迁移前v1.0.0/v1.0.1publicclassEventDTO{FutureDateprivateStringeventTime;// 2025-12-31 12:00:00}迁移后v1.1.0publicclassEventDTO{FutureDateTime// ← 使用新注解privateStringeventTime;// 2025-12-31 12:00:00}优点✅ 专为日期时间验证设计的注解✅ 默认 pattern 为yyyy-MM-dd HH:mm:ss✅ 语义更清晰✅ 常见场景无需配置策略 B移除时间组件如果只需要日期部分在验证前去掉时间迁移前v1.0.0/v1.0.1FutureDateprivateStringeventDate;// 2025-12-31 12:00:00迁移后v1.1.0FutureDateprivateStringeventDate;// 2025-12-31已移除时间// 或在代码中StringdateTime2025-12-31 12:00:00;StringdateOnlydateTime.substring(0,10);// 提取 2025-12-31优点✅ 无需更改注解✅ 明确只验证日期部分缺点⚠️ 丢失时间信息⚠️ 需要数据转换策略 C继续使用 FutureDate不推荐如果必须使用FutureDate处理纯日期字符串和自定义格式示例// v1.1.0 - 仅用于纯日期格式FutureDate(patternMM/dd/yyyy)privateStringusDate;// 12/31/2025 - 可以FutureDate(patternyyyy-MM-dd HH:mm:ss)// ❌ 会抛出 IllegalArgumentExceptionprivateStringdateTime;// 这不会工作重要⚠️ 此策略不能用于日期时间字符串⚠️ pattern 参数不支持时间符号步骤 3更新链式验证调用如果使用链式验证 API迁移前v1.0.0/v1.0.1ValidXvalidatorValidX.init();validator.isFutureDate(2025-12-31 12:00:00);// v1.0.0 中有效迁移后v1.1.0ValidXvalidatorValidX.init();// 选项 A使用新的日期时间方法validator.isFutureDateTime(2025-12-31 12:00:00);// ✅ 推荐// 选项 B移除时间组件validator.isFutureDate(2025-12-31);// ✅ 有效步骤 4更新测试更新测试用例以反映新行为迁移前v1.0.0/v1.0.1TestvoidtestFutureDate(){UserDTOdtonewUserDTO();dto.setEventDate(2025-12-31 12:00:00);// 以前有效SetConstraintViolationUserDTOviolationsvalidator.validate(dto);assertTrue(violations.isEmpty());// 通过}迁移后v1.1.0TestvoidtestFutureDateTime(){UserDTOdtonewUserDTO();dto.setEventTime(2025-12-31 12:00:00);// 将 UserDTO 中的注解更新为 FutureDateTimeSetConstraintViolationUserDTOviolationsvalidator.validate(dto);assertTrue(violations.isEmpty());// 仍然通过}TestvoidtestFutureDateWithTimeFormat_ShouldFail(){UserDTOdtonewUserDTO();dto.setEventDate(2025-12-31 12:00:00);// 日期时间字符串// 如果仍使用 FutureDate现在会失败SetConstraintViolationUserDTOviolationsvalidator.validate(dto);assertFalse(violations.isEmpty());// v1.1.0 中失败}快速参考注解映射使用场景v1.0.0/v1.0.1v1.1.0说明纯日期未来FutureDateFutureDate✅ 无需更改纯日期过去PastDatePastDate✅ 无需更改日期时间未来FutureDateFutureDateTime⚠️需要更改日期时间过去PastDatePastDateTime⚠️需要更改自定义日期格式不支持自动检测FutureDate(pattern...)✅ 新功能自定义日期时间格式不支持FutureDateTime(pattern...)✅ 新功能示例完整迁移迁移前v1.0.0/v1.0.1publicclassEventDTO{NotNullFutureDateprivateStringeventDate;// 接受 2025-12-31 或 2025-12-31 12:00:00NotNullPastDateprivateStringregistrationDate;// 接受 2020-01-01 或 2020-01-01 09:30:00}ServicepublicclassEventService{publicvoidvalidateEvent(MapString,Objectdata){ValidXvalidatorValidX.init();validator.isFutureDate(data.get(startTime))// 对时间字符串有效.isPastDate(data.get(createdAt));// 对时间字符串有效if(!validator.passed()){thrownewValidationException(validator.getErrors());}}}迁移后v1.1.0publicclassEventDTO{// 变更现在使用 FutureDateTime 进行时间感知验证NotNullFutureDateTime// ← 从 FutureDate 更改privateStringeventDate;// 2025-12-31 12:00:00// 变更现在使用 PastDateTime 进行时间感知验证NotNullPastDateTime// ← 从 PastDate 更改privateStringregistrationDate;// 2020-01-01 09:30:00}ServicepublicclassEventService{publicvoidvalidateEvent(MapString,Objectdata){ValidXvalidatorValidX.init();// 变更使用新的日期时间方法validator.isFutureDateTime(data.get(startTime))// ← 已更改.isPastDateTime(data.get(createdAt));// ← 已更改if(!validator.passed()){thrownewValidationException(validator.getErrors());}}}常见问题Q1为什么要引入这个破坏性变更A为了提供更清晰的语义和更好的验证FutureDate/PastDate→ 纯日期验证无时间FutureDateTime/PastDateTime→ 日期时间验证有时间这种分离使意图明确避免歧义。Q2v1.1.0 会验证我现有的纯日期字符串吗A✅ 会如果你使用的是纯日期字符串如2025-12-31无需更改。Q3我可以对日期时间使用自定义格式吗A可以但要使用正确的注解// ✅ 对于自定义格式的日期时间FutureDateTime(patternMM/dd/yyyy HH:mm:ss)privateStringusDateTime;// ❌ 这会抛出异常FutureDate(patternMM/dd/yyyy HH:mm:ss)// IllegalArgumentExceptionQ4如果我不迁移会怎样如果你的代码将日期时间字符串传递给FutureDate或PastDate❌ 验证会失败字符串不匹配纯日期格式❌ 你的应用可能会拒绝有效数据❌ 测试可能开始失败Q5有过渡期吗没有。这是 v1.1.0 中的即时破坏性变更。我们建议升级前检查你的代码库升级后运行全面测试使用上述迁移策略需要帮助如果在迁移过程中遇到问题查看文档参考 README.md 中更新的注解文档查看示例参考本指南中的使用示例联系支持发送邮件至 vipxieliang126.com包含你的当前版本显示问题的代码片段错误消息如果有总结检查清单在将 v1.1.0 部署到生产环境之前在代码库中搜索FutureDate和PastDate的使用识别所有使用日期时间字符串的字段/验证在需要的地方将注解更新为FutureDateTime/PastDateTime更新链式验证调用.isFutureDate()→.isFutureDateTime()更新所有测试用例运行完整测试套件以验证无回归在预发环境中测试验证行为如果暴露这些字段更新 API 文档最后更新2026-08-06适用于ValidX v1.1.0
ValidX 迁移指南：v1.0.0/v1.0.1 → v1.1.0
ValidX 迁移指南v1.0.0/v1.0.1 → v1.1.0本文档描述从 v1.0.0 或 v1.0.1 升级到 v1.1.0 时的破坏性变更和迁移步骤。概述版本 1.1.0 对FutureDate和PastDate注解的日期时间格式支持引入了破坏性变更。影响级别高- 使用日期时间字符串如2025-12-31 12:00:00与FutureDate或PastDate的应用会受到影响。破坏性变更1. FutureDate - 不再支持时间组件v1.0.0/v1.0.1 行为FutureDateprivateStringdate;// ✅ 两种格式都自动支持date2025-12-31;// 解析为 LocalDatedate2025-12-31 12:00:00;// 解析为 LocalDateTime然后转换为 LocalDate工作原理首先尝试解析为yyyy-MM-dd格式如果失败再尝试解析为yyyy-MM-dd HH:mm:ss格式自动支持纯日期和日期时间字符v1.1.0 行为FutureDateprivateStringdate;// ✅ 纯日期格式仍然有效date2025-12-31;// ❌ 日期时间格式不再有效date2025-12-31 12:00:00;// 验证失败变更内容仅支持纯日期格式无时间组件默认 patternyyyy-MM-dd可通过pattern参数指定自定义格式但不能包含时间符号HH、mm、ss 等如果pattern包含时间符号初始化时会抛出IllegalArgumentException2. PastDate - 不再支持时间组件v1.0.0/v1.0.1 行为PastDateprivateStringdate;// ✅ 两种格式都自动支持date2020-01-01;// 解析为 LocalDatedate2020-01-01 12:00:00;// 解析为 LocalDateTime然后转换为 LocalDatev1.1.0 行为PastDateprivateStringdate;// ✅ 纯日期格式仍然有效date2020-01-01;// ❌ 日期时间格式不再有效date2020-01-01 12:00:00;// 验证失败变更内容与FutureDate相同 - 仅支持纯日期格式pattern 参数不能包含时间符号迁移步骤步骤 1识别受影响的代码在代码库中搜索使用日期时间字符串的FutureDate和PastDate# 搜索潜在的日期时间使用模式grep-rFutureDate\|PastDate--include*.javayour-project/查找使用FutureDate或PastDate注解的 String 字段包含时间组件的值如2025-12-31 12:00:00使用isFutureDate()或isPastDate()的链式验证步骤 2选择迁移策略对于每个受影响的使用场景选择以下策略之一策略 A切换到 FutureDateTime / PastDateTime⭐推荐使用 v1.1.0 新增的专用日期时间注解迁移前v1.0.0/v1.0.1publicclassEventDTO{FutureDateprivateStringeventTime;// 2025-12-31 12:00:00}迁移后v1.1.0publicclassEventDTO{FutureDateTime// ← 使用新注解privateStringeventTime;// 2025-12-31 12:00:00}优点✅ 专为日期时间验证设计的注解✅ 默认 pattern 为yyyy-MM-dd HH:mm:ss✅ 语义更清晰✅ 常见场景无需配置策略 B移除时间组件如果只需要日期部分在验证前去掉时间迁移前v1.0.0/v1.0.1FutureDateprivateStringeventDate;// 2025-12-31 12:00:00迁移后v1.1.0FutureDateprivateStringeventDate;// 2025-12-31已移除时间// 或在代码中StringdateTime2025-12-31 12:00:00;StringdateOnlydateTime.substring(0,10);// 提取 2025-12-31优点✅ 无需更改注解✅ 明确只验证日期部分缺点⚠️ 丢失时间信息⚠️ 需要数据转换策略 C继续使用 FutureDate不推荐如果必须使用FutureDate处理纯日期字符串和自定义格式示例// v1.1.0 - 仅用于纯日期格式FutureDate(patternMM/dd/yyyy)privateStringusDate;// 12/31/2025 - 可以FutureDate(patternyyyy-MM-dd HH:mm:ss)// ❌ 会抛出 IllegalArgumentExceptionprivateStringdateTime;// 这不会工作重要⚠️ 此策略不能用于日期时间字符串⚠️ pattern 参数不支持时间符号步骤 3更新链式验证调用如果使用链式验证 API迁移前v1.0.0/v1.0.1ValidXvalidatorValidX.init();validator.isFutureDate(2025-12-31 12:00:00);// v1.0.0 中有效迁移后v1.1.0ValidXvalidatorValidX.init();// 选项 A使用新的日期时间方法validator.isFutureDateTime(2025-12-31 12:00:00);// ✅ 推荐// 选项 B移除时间组件validator.isFutureDate(2025-12-31);// ✅ 有效步骤 4更新测试更新测试用例以反映新行为迁移前v1.0.0/v1.0.1TestvoidtestFutureDate(){UserDTOdtonewUserDTO();dto.setEventDate(2025-12-31 12:00:00);// 以前有效SetConstraintViolationUserDTOviolationsvalidator.validate(dto);assertTrue(violations.isEmpty());// 通过}迁移后v1.1.0TestvoidtestFutureDateTime(){UserDTOdtonewUserDTO();dto.setEventTime(2025-12-31 12:00:00);// 将 UserDTO 中的注解更新为 FutureDateTimeSetConstraintViolationUserDTOviolationsvalidator.validate(dto);assertTrue(violations.isEmpty());// 仍然通过}TestvoidtestFutureDateWithTimeFormat_ShouldFail(){UserDTOdtonewUserDTO();dto.setEventDate(2025-12-31 12:00:00);// 日期时间字符串// 如果仍使用 FutureDate现在会失败SetConstraintViolationUserDTOviolationsvalidator.validate(dto);assertFalse(violations.isEmpty());// v1.1.0 中失败}快速参考注解映射使用场景v1.0.0/v1.0.1v1.1.0说明纯日期未来FutureDateFutureDate✅ 无需更改纯日期过去PastDatePastDate✅ 无需更改日期时间未来FutureDateFutureDateTime⚠️需要更改日期时间过去PastDatePastDateTime⚠️需要更改自定义日期格式不支持自动检测FutureDate(pattern...)✅ 新功能自定义日期时间格式不支持FutureDateTime(pattern...)✅ 新功能示例完整迁移迁移前v1.0.0/v1.0.1publicclassEventDTO{NotNullFutureDateprivateStringeventDate;// 接受 2025-12-31 或 2025-12-31 12:00:00NotNullPastDateprivateStringregistrationDate;// 接受 2020-01-01 或 2020-01-01 09:30:00}ServicepublicclassEventService{publicvoidvalidateEvent(MapString,Objectdata){ValidXvalidatorValidX.init();validator.isFutureDate(data.get(startTime))// 对时间字符串有效.isPastDate(data.get(createdAt));// 对时间字符串有效if(!validator.passed()){thrownewValidationException(validator.getErrors());}}}迁移后v1.1.0publicclassEventDTO{// 变更现在使用 FutureDateTime 进行时间感知验证NotNullFutureDateTime// ← 从 FutureDate 更改privateStringeventDate;// 2025-12-31 12:00:00// 变更现在使用 PastDateTime 进行时间感知验证NotNullPastDateTime// ← 从 PastDate 更改privateStringregistrationDate;// 2020-01-01 09:30:00}ServicepublicclassEventService{publicvoidvalidateEvent(MapString,Objectdata){ValidXvalidatorValidX.init();// 变更使用新的日期时间方法validator.isFutureDateTime(data.get(startTime))// ← 已更改.isPastDateTime(data.get(createdAt));// ← 已更改if(!validator.passed()){thrownewValidationException(validator.getErrors());}}}常见问题Q1为什么要引入这个破坏性变更A为了提供更清晰的语义和更好的验证FutureDate/PastDate→ 纯日期验证无时间FutureDateTime/PastDateTime→ 日期时间验证有时间这种分离使意图明确避免歧义。Q2v1.1.0 会验证我现有的纯日期字符串吗A✅ 会如果你使用的是纯日期字符串如2025-12-31无需更改。Q3我可以对日期时间使用自定义格式吗A可以但要使用正确的注解// ✅ 对于自定义格式的日期时间FutureDateTime(patternMM/dd/yyyy HH:mm:ss)privateStringusDateTime;// ❌ 这会抛出异常FutureDate(patternMM/dd/yyyy HH:mm:ss)// IllegalArgumentExceptionQ4如果我不迁移会怎样如果你的代码将日期时间字符串传递给FutureDate或PastDate❌ 验证会失败字符串不匹配纯日期格式❌ 你的应用可能会拒绝有效数据❌ 测试可能开始失败Q5有过渡期吗没有。这是 v1.1.0 中的即时破坏性变更。我们建议升级前检查你的代码库升级后运行全面测试使用上述迁移策略需要帮助如果在迁移过程中遇到问题查看文档参考 README.md 中更新的注解文档查看示例参考本指南中的使用示例联系支持发送邮件至 vipxieliang126.com包含你的当前版本显示问题的代码片段错误消息如果有总结检查清单在将 v1.1.0 部署到生产环境之前在代码库中搜索FutureDate和PastDate的使用识别所有使用日期时间字符串的字段/验证在需要的地方将注解更新为FutureDateTime/PastDateTime更新链式验证调用.isFutureDate()→.isFutureDateTime()更新所有测试用例运行完整测试套件以验证无回归在预发环境中测试验证行为如果暴露这些字段更新 API 文档最后更新2026-08-06适用于ValidX v1.1.0
