YouFool Holiday SDK

一个强大的 Java 假期和工作日计算 SDK，支持 Spring Boot 自动配置，提供在线和离线两种数据模式。

🌟 特性

• ✅ 工作日计算 - 自动跳过节假日和周末
• ✅ 工作日判断 - 判断指定日期是否为工作日
• ✅ 工作时间判断 - 判断指定时间是否在工作时间内
• ✅ 双重数据模式 - 支持在线API和离线文件两种数据源
• ✅ Spring Boot 集成 - 自动配置，开箱即用
• ✅ 多时间段支持 - 支持复杂的工作时间配置
• ✅ 高性能缓存 - 内置缓存机制，提升性能

🚀 快速开始

1. 添加依赖

<dependency>
    <groupId>com.chinaweal.youfool</groupId>
    <artifactId>youfool-holiday-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

2. 配置文件

在 application.yml 中添加配置：

youfool:
  holiday:
    enabled: true
    online: false
    work-time: "08:00-12:00;14:00-18:00"
    config-path: classpath:holiday
    auto-init: true

3. 直接使用

配置完成后，无需任何初始化代码，直接使用：

@RestController
public class HolidayController {

    @GetMapping("/workdate")
    public LocalDate getWorkDate() {
        // 计算5个工作日后的日期
        return HolidayCalculator.calcWorkDate(LocalDate.now(), 5);
    }

    @GetMapping("/isWorkDay")
    public boolean isWorkDay(@RequestParam LocalDate date) {
        // 判断指定日期是否为工作日
        return HolidayCalculator.isWorkDay(date);
    }

    @GetMapping("/isWorkTime")
    public boolean isWorkTime() {
        // 判断当前时间是否为工作时间
        return HolidayCalculator.isWorkTime(LocalDateTime.now());
    }
}

就这么简单！SDK 会自动初始化并开始工作。

📋 配置参数

参数名	类型	默认值	说明
youfool.holiday.enabled	boolean	true	是否启用假期计算器
youfool.holiday.online	boolean	false	数据模式：true=在线，false=离线
youfool.holiday.host	String	http://www.chinaweal.com.cn:8090/holiday-api	在线模式API地址
youfool.holiday.config-path	String	classpath:holiday	离线模式配置目录
youfool.holiday.work-time	String	"09:00-18:00"	工作时间配置
youfool.holiday.flush-interval	long	900	数据刷新间隔（秒）
youfool.holiday.auto-init	boolean	true	是否自动初始化

⏰ 工作时间配置

支持灵活的工作时间配置：

# 标准工作时间：上午9点到下午6点
work-time: "09:00-18:00"

# 分段工作时间：上午和午休分开
work-time: "08:00-12:00;14:00-17:30"

# 多个时间段
work-time: "06:00-09:00;10:00-12:00;14:00-18:00;20:00-22:00"

# 24小时工作时间
work-time: "00:00-23:59"

🌐 数据模式选择

离线模式（推荐）

youfool:
  holiday:
    online: false
    config-path: classpath:holiday

优势：

• 性能更好，无网络依赖
• 启动速度更快
• 数据稳定可控

文件结构：

src/main/resources/
└── holiday/
    ├── 2024.json
    ├── 2025.json
    └── 2026.json

在线模式

youfool:
  holiday:
    online: true
    host: http://your-api-server.com/holiday-api
    flush-interval: 900  # 15分钟刷新一次

优势：

• 数据实时更新
• 集中管理
• 适合分布式系统

🎯 API 使用方法

核心方法

// 计算工作日
LocalDate workDay = HolidayCalculator.calcWorkDate(startDate, plusDays);

// 判断工作日
boolean isWorkDay = HolidayCalculator.isWorkDay(date);

// 判断工作时间
boolean isWorkTime = HolidayCalculator.isWorkTime(dateTime);

使用示例

@Service
public class BusinessService {

    public LocalDate getDeliveryDate(LocalDate orderDate, int processingDays) {
        // 计算处理完成后的工作日（排除节假日和周末）
        return HolidayCalculator.calcWorkDate(orderDate, processingDays);
    }

    public boolean canProcessNow() {
        // 判断当前是否为工作时间
        return HolidayCalculator.isWorkTime(LocalDateTime.now());
    }

    public boolean isValidBusinessDay(LocalDate date) {
        // 判断是否为有效工作日
        return HolidayCalculator.isWorkDay(date);
    }
}

🔄 传统 Java 项目配置

如果你不使用 Spring Boot，可以这样配置：

// 离线模式
HolidayCalculatorConfig config = new HolidayCalculatorConfig();
config.setOnline(false);
config.setConfigPath("classpath:holiday");
config.setWorkTime("08:00-12:00;14:00-18:00");
HolidayCalculator.init(config);

// 在线模式
HolidayCalculatorConfig config = new HolidayCalculatorConfig();
config.setOnline(true);
config.setHost("http://api.example.com/holiday");
config.setWorkTime("08:00-12:00;14:00-18:00");
HolidayCalculator.init(config);

🏗️ 项目结构

youfool-holiday-sdk/
├── src/main/java/com/chinaweal/youfool/holiday/sdk/
│   ├── HolidayCalculator.java                 # 主API类
│   ├── config/
│   │   ├── HolidayCalculatorConfig.java      # 传统配置类
│   │   ├── HolidayCalculatorProperties.java  # Spring Boot配置类
│   │   ├── HolidayCalculatorAutoConfiguration.java    # Spring Boot 2.x自动配置
│   │   └── HolidayCalculatorAutoConfigurationV3.java  # Spring Boot 3.x自动配置
│   ├── data/
│   │   ├── entity/Holiday.java               # 假期实体类
│   │   └── manager/                          # 数据管理器
│   └── ...                                   # 其他工具类
├── src/main/resources/
│   ├── META-INF/
│   │   ├── spring.factories                  # Spring Boot 2.x自动配置注册
│   │   └── spring/                           # Spring Boot 3.x自动配置注册
│   └── META-INF/additional-spring-configuration-metadata.json  # 配置元数据
└── example/                                  # 示例代码

🔧 构建

# 编译项目
mvn clean compile

# 打包项目
mvn clean package

# 安装到本地仓库
mvn clean install

📄 文档

• 详细配置说明
• Spring Boot 集成指南
• Spring Boot 3 部署指南
• 部署指南
• Bean 冲突修复说明

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

🔗 相关链接

• Spring Boot 官方文档
• Maven 中央仓库