# WhenRule **Repository Path**: feng-kailong/when-rule ## Basic Information - **Project Name**: WhenRule - **Description**: WhenRule 是一个轻量级的 **Java 时间规则匹配库**。通过链式 Builder 组合多种时间条件,判断某个时刻是否满足业务规则。 适用于定时任务调度、营销活动生效窗口、仅在节假日/工作日执行逻辑等场景。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-05-28 - **Last Updated**: 2026-06-01 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # WhenRule WhenRule 是一个轻量级的 **Java 时间规则匹配库**。通过链式 Builder 组合多种时间条件,判断某个时刻是否满足业务规则。 适用于定时任务调度、营销活动生效窗口、仅在节假日/工作日执行逻辑等场景。 --- ## 特性 - **链式 API**:Fluent Builder,条件组合清晰易读 - **多种时间维度**:时间区间、每日时间窗口、节假日/工作日、周末、指定年/月/日/周几 - **跨午夜支持**:每日时间窗口支持跨日(如 22:00 ~ 次日 02:00) - **AND / OR 多段组合**:通过 `.and()` / `.or()` 组合多组条件,从左到右求值 - **中国节假日支持**:内置 2007–2027 年中国法定节假日与调休数据(JSON) - **调休感知**:正确处理「周末补班」与「工作日放假」 - **可插拔数据源**:通过 SPI 接口自定义节假日数据来源(DB / Redis / HTTP / 自定义文件等),零侵入扩展,支持**全局配置**与**调用级覆盖**两种粒度 - **灵活匹配模式**:单段内支持 `ALL`(全部满足)与 `ANY`(任一满足) - **时区支持**:基于 `ZonedDateTime` 与地区时区配置 - **零框架依赖**:核心库不依赖 Spring 等框架,纯 Java 项目可直接使用 - **内置模板**:`WhenRuleTemplates` 提供法定节假日、工作日上午、月末最后一天等常用场景,一行代码启用 --- ## 环境要求 - Java 17+ - Maven 3.x --- ## 快速开始 ### 引入依赖 ```xml io.github.nbut-fkl WhenRule 1.2.0 ``` > 若尚未发布到 Maven 中央仓库,可先在本项目根目录执行 `mvn install` 安装到本地仓库。 ### 基本用法 ```java import com.fkl.whenRule.WhenRule; import com.fkl.whenRule.WhenRuleBuilder; import com.fkl.whenRule.WhenRuleTimeRange; import com.fkl.whenRule.enums.MatchingModelEnums; import java.time.LocalDateTime; import java.time.ZoneId; import java.time.ZonedDateTime; import java.util.List; // 判断当前时间是否为工作日上午 9:00–12:00 boolean matched = WhenRule.when( new WhenRuleBuilder() .calculateTime(ZonedDateTime.now(ZoneId.of("Asia/Shanghai"))) .matchingModel(MatchingModelEnums.ALL) .timeRange(new WhenRuleTimeRange( LocalDateTime.of(2026, 3, 10, 9, 0), LocalDateTime.of(2026, 3, 10, 12, 0) )) .holiday(false) // 工作日(含调休补班) .specifyMonth(List.of(3)) // 3 月 ); System.out.println(matched); // true 或 false ``` ### 使用内置模板(推荐) ```java import com.fkl.whenRule.WhenRule; import com.fkl.whenRule.template.WhenRuleTemplates; import java.time.LocalDateTime; import java.time.ZoneId; import java.time.ZonedDateTime; // 工作日上午 09:00–12:00 boolean matched = WhenRule.when( WhenRuleTemplates.workdayMorning() .calculateTime(ZonedDateTime.of( LocalDateTime.of(2026, 3, 10, 10, 0), ZoneId.of("Asia/Shanghai") )) ); // 法定节假日 WhenRule.when( WhenRuleTemplates.officialHoliday() .calculateTime(ZonedDateTime.now(ZoneId.of("Asia/Shanghai"))) ); ``` --- ## 核心概念 ### 入口 ```java boolean result = WhenRule.when(builder); ``` - 未设置任何条件时,默认返回 `true` - 传入 `null` builder 时,会使用默认 builder(当前时间、中国时区) ### 匹配模式 | 模式 | 说明 | |------|------| | `MatchingModelEnums.ALL` | 所有已配置条件均满足时返回 `true`(默认) | | `MatchingModelEnums.ANY` | 任一条件满足即返回 `true` | ### 基础配置 | 方法 | 说明 | 默认值 | |------|------|--------| | `country(CountryEnums)` | 国家 | `CN` | | `region(RegionEnums)` | 地区/时区 | 随国家默认(CN → `Asia/Shanghai`) | | `calculateTime(ZonedDateTime)` | 待判断的时间 | 当前时间 | | `matchingModel(MatchingModelEnums)` | 匹配模式 | `ALL` | > 切换 `country()` 时会自动同步该国家的默认 `region`。 --- ## 条件说明 同一类条件重复调用时会**替换**而非叠加(例如多次调用 `holiday()` 只保留最后一次)。 ### 1. 时间区间 `timeRange()` ```java .timeRange(new WhenRuleTimeRange(startTime, endTime)) ``` | 参数 | 说明 | |------|------| | `startTime` | 开始时间,`null` 表示无下限 | | `endTime` | 结束时间,`null` 表示无上限 | 边界为**闭区间** `[start, end]`,起止时刻本身也算匹配。 --- ### 2. 节假日 / 工作日 `holiday()` ```java .holiday(true) // 匹配节假日 .holiday(false) // 匹配工作日(含调休补班) ``` **目前仅支持中国(`CountryEnums.CN`)**,数据来自 `src/main/resources/holiday/cn/{year}.json`。 | `flag` | 包含 | 排除 | |--------|------|------| | `true`(节假日) | 周六、周日、法定放假日期 | 调休补班日(`isOffDay: false`) | | `false`(工作日) | 周一至周五、调休补班日 | 法定放假日期(`isOffDay: true`) | 示例(2026 年): | 日期 | 说明 | `holiday(true)` | `holiday(false)` | |------|------|:---------------:|:----------------:| | 2026-01-01 | 元旦(周四) | ✅ | ❌ | | 2026-02-14 | 春节调休补班(周六) | ❌ | ✅ | | 2026-02-15 | 春节(周日) | ✅ | ❌ | | 2026-03-10 | 普通周二 | ❌ | ✅ | --- ### 3. 周末 `weekend()` ```java .weekend(true) // 匹配周六、周日 .weekend(false) // 匹配周一至周五 ``` > **注意**:`weekend()` 仅按自然周判断,**不感知调休**。若需准确的中国工作日/节假日判断,请优先使用 `holiday()`,避免与 `weekend()` 同时使用时产生逻辑冲突。 --- ### 4. 指定周几 `specifyWeekday()` ```java .specifyWeekday(List.of(1, 5)) // 周一、周五 ``` - 取值范围:`1`(周一)– `7`(周日) - 传 `null`:不限制(不加入该条件) - 传空列表 `List.of()`:始终不匹配 --- ### 5. 指定日期 `specifyDay()` ```java .specifyDay(List.of(1, 15, 31)) // 每月 1、15、31 号 ``` - 取值范围:`1`–`31` - `null` / 空列表语义同 `specifyWeekday()` --- ### 6. 指定月份 `specifyMonth()` ```java .specifyMonth(List.of(1, 6, 12)) // 1 月、6 月、12 月 ``` - 取值范围:`1`(一月)– `12`(十二月) --- ### 7. 指定年份 `specifyYear()` ```java .specifyYear(List.of(2025, 2026)) ``` - 四位年份,如 `2026` --- ### 8. 每日时间窗口 `dailyTimeRange()` ```java .dailyTimeRange(new WhenRuleDailyTimeRange(LocalTime.of(14, 0), LocalTime.of(17, 0))) ``` 与 `timeRange()` 的区别:**只关心时分秒,不绑定具体日期**,适合表达「每天/每个工作日的某个固定时段」。 | 参数 | 说明 | |------|------| | `startTime` | 开始时间(`LocalTime`),`null` 表示无下限 | | `endTime` | 结束时间(`LocalTime`),`null` 表示无上限 | - 边界为**闭区间** `[start, end]` - **跨午夜**:当 `startTime` 晚于 `endTime` 时(例如 `22:00 ~ 02:00`)自动按跨日处理 ```java // 每天晚上 22:00 ~ 次日 02:00 .dailyTimeRange(new WhenRuleDailyTimeRange(LocalTime.of(22, 0), LocalTime.of(2, 0))) ``` --- ## 多段条件组合(AND / OR) 当一个条件组(单个 Builder 内的 ALL/ANY)无法表达需求时,可以用 `.and()` / `.or()` 把多组条件串起来。**保留基础配置**(`country` / `region` / `calculateTime` / `matchingModel`),后续段无需重复设置。 ```java // 「工作日下午 2~5 点」 OR 「周末上午 9~12 点」 boolean matched = WhenRule.when( new WhenRuleBuilder() .calculateTime(ZonedDateTime.now(ZoneId.of("Asia/Shanghai"))) .holiday(false) .dailyTimeRange(new WhenRuleDailyTimeRange(LocalTime.of(14, 0), LocalTime.of(17, 0))) .or() .weekend(true) .dailyTimeRange(new WhenRuleDailyTimeRange(LocalTime.of(9, 0), LocalTime.of(12, 0))) ); ``` ### 求值规则 - **从左到右顺序求值**,不区分 AND/OR 优先级 - `A .and() B .or() C` 等价于 `(A AND B) OR C`,**而非** `A AND (B OR C)` - 每个段内仍由 `matchingModel(ALL/ANY)` 控制条件之间的关系 - 段间的 `.and()` / `.or()` 只用于段与段之间 - `calculateTime`、`country`、`region`、`matchingModel` 这些基础配置在所有段间**自动保留** - 单段 Builder(不调用 `.and()` / `.or()`)行为与之前完全一致,向后兼容 --- ## 使用示例 ### 仅在工作日 9:00–18:00 执行 ```java WhenRule.when( new WhenRuleBuilder() .calculateTime(ZonedDateTime.now(ZoneId.of("Asia/Shanghai"))) .timeRange(new WhenRuleTimeRange( LocalDateTime.of(2026, 1, 1, 9, 0), LocalDateTime.of(2026, 1, 1, 18, 0) )) .holiday(false) ); ``` ### 仅在法定节假日执行 ```java WhenRule.when( new WhenRuleBuilder() .calculateTime(ZonedDateTime.now(ZoneId.of("Asia/Shanghai"))) .holiday(true) ); ``` ### 每月 1 号和 15 号 ```java WhenRule.when( new WhenRuleBuilder() .calculateTime(ZonedDateTime.now(ZoneId.of("Asia/Shanghai"))) .specifyDay(List.of(1, 15)) ); ``` ### 2026 年 Q1 的周一或周五(任一满足) ```java WhenRule.when( new WhenRuleBuilder() .matchingModel(MatchingModelEnums.ANY) .calculateTime(ZonedDateTime.of( LocalDateTime.of(2026, 2, 2, 10, 0), ZoneId.of("Asia/Shanghai") )) .specifyYear(List.of(2026)) .specifyMonth(List.of(1, 2, 3)) .specifyWeekday(List.of(1, 5)) ); ``` ### 每个工作日下午 2:00–5:00(每日重复) ```java WhenRule.when( new WhenRuleBuilder() .calculateTime(ZonedDateTime.now(ZoneId.of("Asia/Shanghai"))) .holiday(false) .dailyTimeRange(new WhenRuleDailyTimeRange(LocalTime.of(14, 0), LocalTime.of(17, 0))) ); ``` ### 工作日下午 OR 周末上午(多段组合) ```java WhenRule.when( new WhenRuleBuilder() .calculateTime(ZonedDateTime.now(ZoneId.of("Asia/Shanghai"))) .holiday(false) .dailyTimeRange(new WhenRuleDailyTimeRange(LocalTime.of(14, 0), LocalTime.of(17, 0))) .or() .weekend(true) .dailyTimeRange(new WhenRuleDailyTimeRange(LocalTime.of(9, 0), LocalTime.of(12, 0))) ); ``` --- ## 内置模板 `WhenRuleTemplates` `WhenRuleTemplates` 集中提供常用规则模板,每个静态方法返回预配置好的 `WhenRuleBuilder`,可继续链式追加条件。 > 模板**不会**自动设置 `calculateTime`,使用前请调用 `.calculateTime(...)` 指定待判断时间。 | 方法 | 说明 | |------|------| | **节假日 / 工作日** | | | `officialHoliday()` | 法定节假日(含自然周末,排除调休补班) | | `officialHoliday(HolidayDataProvider)` | 法定节假日 + 自定义数据源 | | `workday()` | 工作日(含调休补班,排除法定放假) | | `workday(HolidayDataProvider)` | 工作日 + 自定义数据源 | | `weekend()` | 自然周末(周六、周日,不感知调休) | | `weekday()` / `mondayToFriday()` | 自然周一至周五 | | **工作时段** | | | `workdayMorning()` / `(start, end)` | 工作日上午,默认 09:00–12:00 | | `workdayAfternoon()` / `(start, end)` | 工作日下午,默认 14:00–18:00 | | `workdayEvening()` / `(start, end)` | 工作日晚上,默认 18:00–22:00 | | `businessHours()` / `(start, end)` | 工作时段,默认 09:00–18:00 | | `workdayNightShift()` / `(start, end)` | 工作日夜班,默认 22:00–次日 06:00 | | `lunchBreak()` / `(start, end)` | 午休,默认 12:00–13:30 | | `nightShift()` / `(start, end)` | 跨午夜时段,默认 22:00–06:00 | | **周末 / 节假日 + 时段** | | | `weekendMorning()` / `(start, end)` | 周末上午,默认 09:00–12:00 | | `weekendAfternoon()` / `(start, end)` | 周末下午,默认 14:00–18:00 | | `holidayMorning()` / `(start, end)` | 节假日上午,默认 09:00–12:00 | | `holidayAfternoon()` / `(start, end)` | 节假日下午,默认 14:00–18:00 | | **按月 / 按周 / 按年** | | | `firstDayOfMonth()` | 每月 1 号 | | `midMonth()` | 每月 15 号 | | `lastDayOfMonth()` | 每月最后一天 | | `payday()` | 发薪日(每月 10、15 号) | | `monthlyOnDays(int...)` | 指定每月若干日期 | | `everyMonday()` / `everyFriday()` / `everySunday()` | 每周固定星期 | | `weeklyOnWeekdays(int...)` | 指定每周若干星期(1=周一,7=周日) | | `q1()` / `q2()` / `q3()` / `q4()` | 第一至第四季度 | | `quarterEnd()` | 季度末最后一天(3/6/9/12 月) | | `inMonths(int...)` | 指定若干月份 | | `inYear(int)` / `inYears(int...)` | 指定年份 | ### 示例 ```java // 发薪日(10、15 号)的工作日上午 WhenRule.when( WhenRuleTemplates.workdayMorning() .calculateTime(ZonedDateTime.of( LocalDateTime.of(2026, 3, 10, 10, 0), ZoneId.of("Asia/Shanghai") )) .specifyDay(List.of(10, 15)) ); // 季度末最后一天 WhenRule.when( WhenRuleTemplates.quarterEnd() .calculateTime(ZonedDateTime.of( LocalDateTime.of(2026, 3, 31, 10, 0), ZoneId.of("Asia/Shanghai") )) ); // 工作日上午 WhenRule.when( WhenRuleTemplates.workdayMorning() .calculateTime(ZonedDateTime.now(ZoneId.of("Asia/Shanghai"))) ); // 工作时段 08:30–17:30 WhenRule.when( WhenRuleTemplates.businessHours(LocalTime.of(8, 30), LocalTime.of(17, 30)) .calculateTime(ZonedDateTime.now(ZoneId.of("Asia/Shanghai"))) ); // 月末最后一天 + 继续追加条件 WhenRule.when( WhenRuleTemplates.lastDayOfMonth() .calculateTime(ZonedDateTime.of( LocalDateTime.of(2026, 1, 31, 10, 0), ZoneId.of("Asia/Shanghai") )) .specifyMonth(List.of(1, 4, 7, 10)) // 仅 Q 季末月 ); // 模板 + 多段组合 WhenRule.when( WhenRuleTemplates.workdayMorning() .calculateTime(ZonedDateTime.now(ZoneId.of("Asia/Shanghai"))) .or() .weekend(true) .dailyTimeRange(new WhenRuleDailyTimeRange(LocalTime.of(9, 0), LocalTime.of(12, 0))) ); ``` --- ## 节假日数据格式 数据文件路径:`src/main/resources/holiday/cn/{year}.json` ```json { "days": [ { "name": "元旦", "date": "2026-01-01", "isOffDay": true }, { "name": "春节", "date": "2026-02-14", "isOffDay": false } ] } ``` | 字段 | 说明 | |------|------| | `name` | 节假日名称 | | `date` | 日期,格式 `yyyy-MM-dd` | | `isOffDay` | `true` = 放假;`false` = 调休补班 | --- ## 自定义节假日数据源 WhenRule 提供了一个 **SPI(服务提供接口)** 机制 —— `HolidayDataProvider`,让你不必使用内置的 JSON 文件,而是接入**任意数据源**:自有数据库、Redis、HTTP 接口、配置中心等。 ### 设计概览 | 组件 | 类型 | 作用 | |------|------|------| | [`HolidayDataProvider`](src/main/java/com/fkl/whenRule/condition/impl/holiday/HolidayDataProvider.java) | 接口 | 节假日数据源 SPI,用户实现该接口接入自己的数据源 | | [`ClasspathJsonHolidayDataProvider`](src/main/java/com/fkl/whenRule/condition/impl/holiday/ClasspathJsonHolidayDataProvider.java) | 默认实现 | 从 jar 内置 `holiday/{country}/{year}.json` 读取,带本地缓存 | | [`JdbcHolidayDataProvider`](src/main/java/com/fkl/whenRule/condition/impl/holiday/JdbcHolidayDataProvider.java) | 官方 JDBC 实现 | 用户传入 `DataSource`,从 `when_rule_holidays` 表按国家/年份查询 | | [`HolidayAdminService`](src/main/java/com/fkl/whenRule/condition/impl/holiday/HolidayAdminService.java) | 管理 Service | 节假日数据增删改查(**仅 JDBC 模式可用**) | | [`WhenRuleConfig`](src/main/java/com/fkl/whenRule/config/WhenRuleConfig.java) | 全局配置中心 | 在程序启动时注册自定义实现,未注册则使用默认 JSON | > 不做任何配置时使用默认实现,开箱即用。 ### SPI 接口定义 ```java public interface HolidayDataProvider { /** * 加载指定国家、指定年份的"非常规日"数据(节假日 + 调休工作日)。 * * @param country 国家 * @param year 年份 * @return 当年节假日数据集合,无数据时返回空集合(不要返回 null) */ List load(CountryEnums country, int year); /** 清空内部缓存,默认空实现,实现类如有缓存可重写 */ default void clearCache() { } } ``` 返回的 `DaysEntity` 字段与 JSON 中的字段保持一致: | 字段 | 说明 | |------|------| | `name` | 节假日名称 | | `date` | 日期(`LocalDate`) | | `isOffDay` | `true` = 放假;`false` = 调休补班 | ### 全局注册入口 `WhenRuleConfig` 是一个线程安全的静态配置中心,对外暴露三个方法: | 方法 | 说明 | |------|------| | `getHolidayDataProvider()` | 获取当前 provider(默认 `ClasspathJsonHolidayDataProvider`) | | `setHolidayDataProvider(provider)` | 注册自定义实现,传 `null` 会被忽略 | | `setHolidayDataSource(dataSource)` | 注册 JDBC 数据源(内部封装为 `JdbcHolidayDataProvider`) | | `isJdbcHolidayEnabled()` | 当前全局是否为 JDBC 模式 | | `holidayAdminService()` | 获取 AdminService(非 JDBC 返回 `Optional.empty()`) | | `requireHolidayAdminService()` | 获取 AdminService(非 JDBC 抛出异常) | | `reset()` | 重置为默认 JSON 实现,便于单元测试 | ### 优先级模型 WhenRule 的节假日数据源解析采用 **调用级 → 全局** 的优先级,**调用级覆盖全局**: ``` WhenRuleBuilder.holidayDataProvider(...) ← 调用级 provider(最高) WhenRuleBuilder.holidayDataSource(...) ← 调用级 DataSource(等价于 new JdbcHolidayDataProvider(ds)) ↓ 未设置时回退 WhenRuleConfig.setHolidayDataProvider(...) ← 全局 provider WhenRuleConfig.setHolidayDataSource(...) ← 全局 DataSource ↓ 未设置时回退 ClasspathJsonHolidayDataProvider ← 内置 JSON 默认 ``` 这样设计的好处: - **全局配置足够简单**:90% 场景只需启动时调用一次 `WhenRuleConfig.setHolidayDataProvider(...)` - **多场景互不干扰**:不同业务线/不同请求可以通过 `builder.holidayDataProvider(...)` 各自指定,**无线程安全问题、无 ThreadLocal 泄漏风险** - **调用级不污染全局**:builder 上的 provider 仅作用于本次规则计算,不会修改 `WhenRuleConfig` ### 用法 1:使用默认实现(零配置) 什么都不做即可。`HolidayCondition` 会自动调用内置 `ClasspathJsonHolidayDataProvider`,读取 jar 内置的 2007–2027 年中国节假日 JSON 数据。 ### 用法 2:官方 JDBC 数据源(推荐) 先建表并导入数据(参见 [`sql/when_rule_holidays_init.sql`](sql/when_rule_holidays_init.sql)): ```sql CREATE TABLE when_rule_holidays( id bigint primary key auto_increment, name varchar(255), country varchar(255), `date` date, is_off_day tinyint default 0 ); ``` **全局注册**(程序启动时一次): ```java import com.fkl.whenRule.config.WhenRuleConfig; import com.fkl.whenRule.condition.impl.holiday.HolidayAdminService; import javax.sql.DataSource; // 用户应用自己准备 DataSource(HikariCP / Spring 等) DataSource dataSource = ...; WhenRuleConfig.setHolidayDataSource(dataSource); // 管理数据(仅 JDBC 模式可用) HolidayAdminService admin = WhenRuleConfig.requireHolidayAdminService(); admin.save(HolidayRecord.builder() .name("元旦") .country("CN") .date(LocalDate.of(2026, 1, 1)) .isOffDay(true) .build()); ``` **Builder 级注册**(单次规则使用独立数据源): ```java WhenRule.when(new WhenRuleBuilder() .calculateTime(...) .holiday(true) .holidayDataSource(dataSource)); // 或 .holidayDataProvider(new JdbcHolidayDataProvider(dataSource)) ``` > 未调用 `setHolidayDataSource` 时,默认仍使用 jar 内 JSON,**AdminService 不可用**(`isJdbcHolidayEnabled()` 为 `false`)。 ### 用法 3:自定义 Provider(完全自行实现) 若需接入 Redis / HTTP 等非 JDBC 存储,仍可实现 SPI: ```java import com.fkl.whenRule.condition.impl.holiday.HolidayDataProvider; import com.fkl.whenRule.config.WhenRuleConfig; import com.fkl.whenRule.entity.DaysEntity; import com.fkl.whenRule.enums.CountryEnums; import java.util.List; public class MyHolidayDataProvider implements HolidayDataProvider { @Override public List load(CountryEnums country, int year) { // 你的查询逻辑:Redis / HTTP / MyBatis 等 return holidayDao.queryByCountryAndYear(country.name(), year); } } WhenRuleConfig.setHolidayDataProvider(new MyHolidayDataProvider()); ``` ### 用法 4:混合 / 装饰模式(默认数据 + 自定义补丁) 例如想在内置数据基础上叠加公司内部的特殊调休: ```java import com.fkl.whenRule.condition.impl.holiday.ClasspathJsonHolidayDataProvider; import com.fkl.whenRule.condition.impl.holiday.HolidayDataProvider; import com.fkl.whenRule.config.WhenRuleConfig; import java.util.ArrayList; import java.util.List; WhenRuleConfig.setHolidayDataProvider(new HolidayDataProvider() { private final HolidayDataProvider fallback = new ClasspathJsonHolidayDataProvider(); @Override public List load(CountryEnums country, int year) { List list = new ArrayList<>(fallback.load(country, year)); list.addAll(myDao.queryCompanyHolidays(year)); // 追加公司内部调休 return list; } }); ``` ### 用法 5:Spring Boot 项目集成 在 Spring 项目中注入 `DataSource` 后注册: ```java @Component public class WhenRuleInitializer { @Resource private DataSource dataSource; @PostConstruct public void init() { WhenRuleConfig.setHolidayDataSource(dataSource); } } ``` > 提示:未来会提供官方 `WhenRule-spring-boot-starter`,自动从 yml 配置完成注册。 ### 用法 6:调用级 provider / DataSource(多场景并发隔离)⭐️ 当应用内**同时存在多种业务场景**,每个场景需要不同的节假日数据源时,**不要**频繁调用 `WhenRuleConfig.setHolidayDataProvider(...)`(会引发线程安全问题),而是使用 `WhenRuleBuilder.holidayDataProvider(...)` —— **仅作用于本次规则计算**: ```java HolidayDataProvider tenantA = (country, year) -> dao.queryTenantA(year); HolidayDataProvider tenantB = (country, year) -> dao.queryTenantB(year); // 线程 1 boolean r1 = WhenRule.when(new WhenRuleBuilder() .holidayDataProvider(tenantA) // 仅当前 builder 使用 tenantA .holiday(true)); // 线程 2(同一时刻,互不影响) boolean r2 = WhenRule.when(new WhenRuleBuilder() .holidayDataProvider(tenantB) // 仅当前 builder 使用 tenantB .holiday(true)); ``` **特性**: - ✅ 完全线程安全,多个 builder 互不干扰 - ✅ 不修改全局 `WhenRuleConfig`,没有副作用 - ✅ 调用顺序无要求:`holidayDataProvider()` 在 `holiday()` 前后调用都生效 - ✅ `.and()` / `.or()` 多段组合时自动跨段生效 - ✅ 传 `null` 显式回退到全局配置 ### `HolidayAdminService` 数据管理(仅 JDBC 模式) 当且仅当使用 `JdbcHolidayDataProvider` 时,可通过 AdminService 直接操作数据库: ```java if (WhenRuleConfig.isJdbcHolidayEnabled()) { HolidayAdminService admin = WhenRuleConfig.requireHolidayAdminService(); long id = admin.save(HolidayRecord.builder() .name("公司年会假").country("CN") .date(LocalDate.of(2026, 12, 25)).isOffDay(true).build()); admin.update(...); admin.deleteById(id); admin.listByCountryAndYear(CountryEnums.CN, 2026); admin.replaceYear(CountryEnums.CN, 2027, records); admin.importDays(CountryEnums.CN, 2027, daysFromJson); } ``` | 方法 | 说明 | |------|------| | `save` / `update` / `deleteById` | 增删改 | | `listByCountryAndYear` | 按国家+年份查询 | | `replaceYear` / `importDays` | 整年覆盖 / 批量导入 | > JSON 模式下 `holidayAdminService()` 返回 empty;后台可在 `isJdbcHolidayEnabled()` 为 false 时禁用写操作。 ### 单元测试中的隔离 为避免不同测试用例之间互相污染,建议: ```java @AfterEach void tearDown() { HolidayCondition.clearCache(); // 清当前 provider 缓存 WhenRuleConfig.reset(); // 重置回默认实现 } ``` ### 注意事项 - `load()` **不要返回 `null`**,无数据请返回空集合 - 自定义实现请自行处理**缓存与并发**(默认实现使用 `ConcurrentHashMap`) - `HolidayCondition.clearCache()` 内部委托给**全局 provider** 的 `clearCache()`,不会清理通过 builder 级注入的 provider 实例缓存 - `setHolidayDataProvider(null)` / `setHolidayDataSource(null)` 不会清空当前 provider,会被静默忽略 - `HolidayAdminService` 仅在 JDBC 模式下可用;改库后会自动 `clearCache()`,builder 级私有 provider 需自行清理 - `WhenRuleConfig` 全局单例**不适合在运行时频繁切换**(多线程会互相覆盖),需要场景隔离时请使用 `WhenRuleBuilder.holidayDataProvider(...)` / `holidayDataSource(...)` 调用级注入 - 目前节假日匹配逻辑仅对 `CountryEnums.CN` 生效;自定义 provider 即便提供了其他国家数据,仍受此限制(后续会扩展) --- ## 运行测试 ```bash mvn test ``` --- ## 路线图 ### 短期计划 - [x] **更强的自定义时间配置** - [x] 支持每日/每周重复时间段(`dailyTimeRange` 已实现,参见「条件说明」第 8 节) - [x] 支持跨天时间段(`dailyTimeRange` 跨午夜场景,如 22:00 ~ 次日 02:00) - [x] 多段条件组合(`.and()` / `.or()` 语法) - [x] **可插拔节假日数据源** - [x] 通过 `HolidayDataProvider` SPI 接入任意数据源(DB / Redis / HTTP / 自定义文件) - [x] 全局配置中心 `WhenRuleConfig`,启动时一次注册即可全局生效 - [x] 默认实现 `ClasspathJsonHolidayDataProvider` 保持向后兼容 - [x] 调用级 provider 注入(`WhenRuleBuilder.holidayDataProvider(...)`),支持多场景并发隔离 - [x] **节假日数据存储升级(架构层)** - [x] 通过 SPI 把"如何取数据"从 jar 内置 JSON 解耦出来,用户可接入任意存储 - [x] 支持运行时动态更新(用户的 provider 直接查 DB / Redis / 配置中心即可),无需重新发布 - [x] **官方扩展实现(生态层)** - [x] 官方 `JdbcHolidayDataProvider`(用户传入 `DataSource`,按国家/年份查询) - [x] `WhenRuleConfig.setHolidayDataSource` / `WhenRuleBuilder.holidayDataSource` 全局与调用级注入 - [x] `HolidayAdminService` 提供增删改查、整年覆盖、批量导入(仅 JDBC 模式可用) - [x] **更多内置模板** - [x] `WhenRuleTemplates` 预置常用规则(法定节假日、工作日、工作日上午/下午、工作时段、月末最后一天等) - [x] 一行代码快速启用常见场景,返回的 Builder 可继续链式扩展 ### 长期计划 - [ ] **多国家 / 多地区支持** - 当前节假日逻辑仅完整支持中国(`CN`) - 扩展美国、欧盟等主要国家/地区的节假日与工作历 - 支持按地区自定义工作日历 - [ ] **国际化与扩展性** - 插件化条件注册机制 - 更丰富的时区与夏令时处理 - Spring Boot Starter 集成(自动从 `application.yml` 注册自定义 `HolidayDataProvider`) --- ## 项目结构 ``` WhenRule/ ├── src/main/java/com/fkl/whenRule/ │ ├── WhenRule.java # 入口 │ ├── WhenRuleBuilder.java # 链式构建器 │ ├── WhenRuleTimeRange.java # 绝对时间区间(LocalDateTime) │ ├── WhenRuleDailyTimeRange.java # 每日时间窗口(LocalTime) │ ├── config/ # 全局配置(WhenRuleConfig) │ ├── template/ # 内置模板(WhenRuleTemplates) │ ├── condition/ # 条件接口与实现 │ │ └── impl/holiday/ # SPI、JSON/JDBC 实现、HolidayAdminService │ ├── entity/ # DaysEntity、HolidayRecord 等 │ └── enums/ # 枚举(国家、地区、匹配模式、AND/OR) ├── sql/when_rule_holidays_init.sql # 节假日表 DDL + 初始化数据 ├── src/main/resources/holiday/cn/ # 中国节假日 JSON 数据(默认数据源) └── src/test/java/ # 单元测试 ``` --- ## 许可证 本项目采用 [MIT License](LICENSE)(麻省理工学院许可证)。 您可以自由使用、修改、分发本软件,但需保留原始版权声明与许可全文。