springboot自动配置适配
This commit is contained in:
parent
9016410765
commit
e8b622fb60
|
|
@ -1,3 +1,4 @@
|
||||||
/.idea
|
/.idea
|
||||||
/*.iml
|
/*.iml
|
||||||
/target
|
/target
|
||||||
|
settings.local.json
|
||||||
|
|
@ -0,0 +1,282 @@
|
||||||
|
# CLAUDE.md
|
||||||
|
|
||||||
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||||
|
|
||||||
|
## Project Overview
|
||||||
|
|
||||||
|
This is a Java SDK for holiday/workday calculations called `youfool-holiday-sdk`. It provides functionality to:
|
||||||
|
|
||||||
|
- Calculate workdays by skipping holidays and weekends
|
||||||
|
- Check if a specific date is a workday
|
||||||
|
- Check if a specific datetime is within working hours
|
||||||
|
- Support both online and offline data modes for holiday information
|
||||||
|
|
||||||
|
## Build Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Compile the project
|
||||||
|
mvn compile
|
||||||
|
|
||||||
|
# Build the JAR with sources
|
||||||
|
mvn clean package
|
||||||
|
|
||||||
|
# Install to local repository
|
||||||
|
mvn clean install
|
||||||
|
|
||||||
|
# Skip tests during build (default behavior)
|
||||||
|
mvn clean package -DskipTests
|
||||||
|
```
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
The SDK follows a factory pattern with strategy implementation for data management:
|
||||||
|
|
||||||
|
### Core Components
|
||||||
|
|
||||||
|
1. **HolidayCalculator** (`src/main/java/com/chinaweal/youfool/holiday/sdk/HolidayCalculator.java`)
|
||||||
|
- Main API entry point with static methods
|
||||||
|
- Provides workday calculation and date/time validation methods
|
||||||
|
- Must be initialized with `HolidayCalculatorConfig` before use
|
||||||
|
|
||||||
|
2. **HolidayCalculatorConfig** (`src/main/java/com/chinaweal/youfool/holiday/sdk/config/HolidayCalculatorConfig.java`)
|
||||||
|
- Configuration class with Lombok annotations
|
||||||
|
- Controls online/offline mode, work hours, data refresh intervals
|
||||||
|
- Online mode: fetches from API endpoint
|
||||||
|
- Offline mode: loads from local JSON files
|
||||||
|
|
||||||
|
3. **Data Management Strategy Pattern**
|
||||||
|
- `AbstractHolidayDataManager`: Base class with caching and synchronization logic
|
||||||
|
- `OnlineHolidayDataManager`: Fetches data from REST API
|
||||||
|
- `LocationHolidayDataManager`: Loads from local JSON files in classpath or filesystem
|
||||||
|
|
||||||
|
4. **Holiday Entity** (`src/main/java/com/chinaweal/youfool/holiday/sdk/data/entity/Holiday.java`)
|
||||||
|
- Data model with Jackson JSON serialization
|
||||||
|
- Contains date, festival name, type (holiday/workday), and descriptions
|
||||||
|
|
||||||
|
### Data Flow
|
||||||
|
|
||||||
|
1. Initialization creates appropriate data manager based on config
|
||||||
|
2. Data managers implement lazy loading with configurable refresh intervals
|
||||||
|
3. Thread-safe data access with synchronization blocks
|
||||||
|
4. Work time validation uses configurable time ranges
|
||||||
|
|
||||||
|
## Dependencies
|
||||||
|
|
||||||
|
- **Lombok 1.18.12**: Code generation for getters/setters
|
||||||
|
- **FastJSON2 2.0.56**: JSON serialization/deserialization
|
||||||
|
- **Jackson Annotations 2.18.5**: JSON format annotations
|
||||||
|
- **JUnit 4.12**: Testing framework
|
||||||
|
|
||||||
|
## 配置方式
|
||||||
|
|
||||||
|
### 🔧 Spring Boot 项目配置（推荐）
|
||||||
|
|
||||||
|
在 Spring Boot 项目中，SDK 支持自动配置和 YAML/Properties 文件配置：
|
||||||
|
|
||||||
|
#### 1. 添加依赖
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<dependency>
|
||||||
|
<groupId>com.chinaweal.youfool</groupId>
|
||||||
|
<artifactId>youfool-holiday-sdk</artifactId>
|
||||||
|
<version>1.0.0</version>
|
||||||
|
</dependency>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. YAML 配置 (`application.yml`)
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
youfool:
|
||||||
|
holiday:
|
||||||
|
# 是否启用假期计算器，默认启用
|
||||||
|
enabled: true
|
||||||
|
|
||||||
|
# 数据模式：true=在线模式，false=离线模式，默认离线
|
||||||
|
online: false
|
||||||
|
|
||||||
|
# 在线模式下的API服务器地址
|
||||||
|
host: http://www.chinaweal.com.cn:8090/holiday-api
|
||||||
|
|
||||||
|
# 离线模式下的本地配置目录
|
||||||
|
config-path: classpath:holiday
|
||||||
|
|
||||||
|
# 工作时间配置，多个时间段用分号分隔
|
||||||
|
# 格式：HH:mm-HH:mm;HH:mm-HH:mm
|
||||||
|
work-time: "08:00-12:00;14:00-18:00"
|
||||||
|
|
||||||
|
# 数据刷新间隔（秒），-1表示不刷新，默认15分钟
|
||||||
|
flush-interval: 900
|
||||||
|
|
||||||
|
# 是否在Spring Boot启动时自动初始化
|
||||||
|
auto-init: true
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 3. Properties 配置 (`application.properties`)
|
||||||
|
|
||||||
|
```properties
|
||||||
|
# 是否启用假期计算器
|
||||||
|
youfool.holiday.enabled=true
|
||||||
|
|
||||||
|
# 数据模式：true=在线模式，false=离线模式
|
||||||
|
youfool.holiday.online=false
|
||||||
|
|
||||||
|
# API服务器地址（在线模式）
|
||||||
|
youfool.holiday.host=http://www.chinaweal.com.cn:8090/holiday-api
|
||||||
|
|
||||||
|
# 本地配置目录（离线模式）
|
||||||
|
youfool.holiday.config-path=classpath:holiday
|
||||||
|
|
||||||
|
# 工作时间配置
|
||||||
|
youfool.holiday.work-time=08:00-12:00;14:00-18:00
|
||||||
|
|
||||||
|
# 数据刷新间隔（秒）
|
||||||
|
youfool.holiday.flush-interval=900
|
||||||
|
|
||||||
|
# 是否自动初始化
|
||||||
|
youfool.holiday.auto-init=true
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 4. 直接使用（无需手动初始化）
|
||||||
|
|
||||||
|
配置完成后，直接使用：
|
||||||
|
|
||||||
|
```java
|
||||||
|
@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());
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 📋 配置参数说明
|
||||||
|
|
||||||
|
| 参数名 | 类型 | 默认值 | 说明 |
|
||||||
|
|--------|------|--------|------|
|
||||||
|
| `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` | 是否自动初始化 |
|
||||||
|
|
||||||
|
### 🕐 工作时间配置详解
|
||||||
|
|
||||||
|
工作时间支持多个时间段配置：
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# 标准工作时间：上午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"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 🌐 数据模式选择
|
||||||
|
|
||||||
|
#### 在线模式
|
||||||
|
```yaml
|
||||||
|
youfool:
|
||||||
|
holiday:
|
||||||
|
online: true
|
||||||
|
host: http://your-api-server.com/holiday-api
|
||||||
|
flush-interval: 900 # 15分钟刷新一次
|
||||||
|
```
|
||||||
|
- 从配置的API接口获取假期数据
|
||||||
|
- 支持定时刷新数据
|
||||||
|
- 适合需要实时数据的场景
|
||||||
|
|
||||||
|
#### 离线模式（推荐）
|
||||||
|
```yaml
|
||||||
|
youfool:
|
||||||
|
holiday:
|
||||||
|
online: false
|
||||||
|
config-path: classpath:holiday
|
||||||
|
```
|
||||||
|
- 从本地JSON文件读取假期数据
|
||||||
|
- 性能更好，无网络依赖
|
||||||
|
- 支持classpath和文件系统路径
|
||||||
|
|
||||||
|
#### 离线模式文件结构
|
||||||
|
```
|
||||||
|
src/main/resources/
|
||||||
|
└── holiday/
|
||||||
|
├── 2024.json
|
||||||
|
├── 2025.json
|
||||||
|
└── 2026.json
|
||||||
|
```
|
||||||
|
|
||||||
|
### 🔧 传统Java项目配置
|
||||||
|
|
||||||
|
对于非Spring Boot项目，可以使用传统配置方式：
|
||||||
|
|
||||||
|
#### Online Mode
|
||||||
|
```java
|
||||||
|
HolidayCalculatorConfig config = new HolidayCalculatorConfig();
|
||||||
|
config.setOnline(true);
|
||||||
|
config.setHost("http://www.chinaweal.com.cn:8090/holiday-api");
|
||||||
|
config.setWorkTime("08:00-12:00;14:00-17:00");
|
||||||
|
HolidayCalculator.init(config);
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Offline Mode
|
||||||
|
```java
|
||||||
|
HolidayCalculatorConfig config = new HolidayCalculatorConfig();
|
||||||
|
config.setOnline(false);
|
||||||
|
config.setConfigPath("classpath:holiday");
|
||||||
|
config.setWorkTime("08:00-12:00;14:00-18:00");
|
||||||
|
HolidayCalculator.init(config);
|
||||||
|
```
|
||||||
|
|
||||||
|
## API Usage
|
||||||
|
|
||||||
|
```java
|
||||||
|
// Calculate workday 4 days from now
|
||||||
|
LocalDate workDay = HolidayCalculator.calcWorkDate(LocalDate.now(), 4);
|
||||||
|
|
||||||
|
// Check if today is a workday
|
||||||
|
boolean isWorkDay = HolidayCalculator.isWorkDay(LocalDate.now());
|
||||||
|
|
||||||
|
// Check if current time is within working hours
|
||||||
|
boolean isWorkTime = HolidayCalculator.isWorkTime(LocalDateTime.now());
|
||||||
|
```
|
||||||
|
|
||||||
|
## Data Sources
|
||||||
|
|
||||||
|
- **Online API**: `{host}/api/holiday/list?year={year}`
|
||||||
|
- **Offline Files**: JSON files in configured directory (e.g., `classpath:holiday/2025.json`)
|
||||||
|
- **Data Format**: Array of Holiday objects with date, festival name, and type fields
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
Tests are currently skipped by default (`<skipTests>true</skipTests>` in pom.xml). To run tests:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mvn test -DskipTests=false
|
||||||
|
```
|
||||||
|
|
||||||
|
## Deployment
|
||||||
|
|
||||||
|
The project includes Maven source plugin configuration and nexus repository deployment setup for snapshot versions.
|
||||||
298
README.md
298
README.md
|
|
@ -1,66 +1,258 @@
|
||||||
# youfool-holiday-sdk
|
# YouFool Holiday SDK
|
||||||
|
|
||||||
youfool-holiday调度sdk
|
[](https://search.maven.org/artifact/com.chinaweal.youfool/youfool-holiday-sdk)
|
||||||
|
[](https://spring.io/projects/spring-boot)
|
||||||
|
[](LICENSE)
|
||||||
|
|
||||||
## 使用方法
|
一个强大的 Java 假期和工作日计算 SDK，支持 Spring Boot 自动配置，提供在线和离线两种数据模式。
|
||||||
|
|
||||||
### 配置初始化
|
## 🌟 特性
|
||||||
|
|
||||||
|
- ✅ **工作日计算** - 自动跳过节假日和周末
|
||||||
|
- ✅ **工作日判断** - 判断指定日期是否为工作日
|
||||||
|
- ✅ **工作时间判断** - 判断指定时间是否在工作时间内
|
||||||
|
- ✅ **双重数据模式** - 支持在线API和离线文件两种数据源
|
||||||
|
- ✅ **Spring Boot 集成** - 自动配置，开箱即用
|
||||||
|
- ✅ **多时间段支持** - 支持复杂的工作时间配置
|
||||||
|
- ✅ **高性能缓存** - 内置缓存机制，提升性能
|
||||||
|
|
||||||
|
## 🚀 快速开始
|
||||||
|
|
||||||
|
### 1. 添加依赖
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<dependency>
|
||||||
|
<groupId>com.chinaweal.youfool</groupId>
|
||||||
|
<artifactId>youfool-holiday-sdk</artifactId>
|
||||||
|
<version>1.0.0</version>
|
||||||
|
</dependency>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 配置文件
|
||||||
|
|
||||||
|
在 `application.yml` 中添加配置：
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
youfool:
|
||||||
|
holiday:
|
||||||
|
enabled: true
|
||||||
|
online: false
|
||||||
|
work-time: "08:00-12:00;14:00-18:00"
|
||||||
|
config-path: classpath:holiday
|
||||||
|
auto-init: true
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 直接使用
|
||||||
|
|
||||||
|
配置完成后，无需任何初始化代码，直接使用：
|
||||||
|
|
||||||
```java
|
```java
|
||||||
// 初始化假期计算器
|
@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` | 是否自动初始化 |
|
||||||
|
|
||||||
|
## ⏰ 工作时间配置
|
||||||
|
|
||||||
|
支持灵活的工作时间配置：
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# 标准工作时间：上午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"
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🌐 数据模式选择
|
||||||
|
|
||||||
|
### 离线模式（推荐）
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
youfool:
|
||||||
|
holiday:
|
||||||
|
online: false
|
||||||
|
config-path: classpath:holiday
|
||||||
|
```
|
||||||
|
|
||||||
|
**优势：**
|
||||||
|
- 性能更好，无网络依赖
|
||||||
|
- 启动速度更快
|
||||||
|
- 数据稳定可控
|
||||||
|
|
||||||
|
**文件结构：**
|
||||||
|
```
|
||||||
|
src/main/resources/
|
||||||
|
└── holiday/
|
||||||
|
├── 2024.json
|
||||||
|
├── 2025.json
|
||||||
|
└── 2026.json
|
||||||
|
```
|
||||||
|
|
||||||
|
### 在线模式
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
youfool:
|
||||||
|
holiday:
|
||||||
|
online: true
|
||||||
|
host: http://your-api-server.com/holiday-api
|
||||||
|
flush-interval: 900 # 15分钟刷新一次
|
||||||
|
```
|
||||||
|
|
||||||
|
**优势：**
|
||||||
|
- 数据实时更新
|
||||||
|
- 集中管理
|
||||||
|
- 适合分布式系统
|
||||||
|
|
||||||
|
## 🎯 API 使用方法
|
||||||
|
|
||||||
|
### 核心方法
|
||||||
|
|
||||||
|
```java
|
||||||
|
// 计算工作日
|
||||||
|
LocalDate workDay = HolidayCalculator.calcWorkDate(startDate, plusDays);
|
||||||
|
|
||||||
|
// 判断工作日
|
||||||
|
boolean isWorkDay = HolidayCalculator.isWorkDay(date);
|
||||||
|
|
||||||
|
// 判断工作时间
|
||||||
|
boolean isWorkTime = HolidayCalculator.isWorkTime(dateTime);
|
||||||
|
```
|
||||||
|
|
||||||
|
### 使用示例
|
||||||
|
|
||||||
|
```java
|
||||||
|
@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，可以这样配置：
|
||||||
|
|
||||||
|
```java
|
||||||
|
// 离线模式
|
||||||
HolidayCalculatorConfig config = new HolidayCalculatorConfig();
|
HolidayCalculatorConfig config = new HolidayCalculatorConfig();
|
||||||
// 是否在线同步数据模式
|
config.setOnline(false);
|
||||||
config.
|
|
||||||
|
|
||||||
setOnline(Boolean.parseBoolean(environment.getProperty("holiday.online")));
|
|
||||||
// 离线模式配置文件路径（默认：classpath:holiday）
|
|
||||||
config.
|
|
||||||
|
|
||||||
setConfigPath(environment.getProperty("holiday.config-path"));
|
|
||||||
// 工作时间区间配置，多个用;隔开，示例：08:00-12:00;14:00-17:00
|
|
||||||
config.
|
|
||||||
|
|
||||||
setWorkTime(environment.getProperty("holiday.work-time"));
|
|
||||||
// 数据同步间隔，默认-1（只在初始化时同步）
|
|
||||||
String interval = environment.getProperty("holiday.flush-interval");
|
|
||||||
if(interval !=null){
|
|
||||||
config.
|
|
||||||
|
|
||||||
setFlushInterval(Long.parseLong(interval.trim()));
|
|
||||||
}
|
|
||||||
HolidayCalculator.
|
|
||||||
|
|
||||||
init(config);
|
|
||||||
```
|
|
||||||
|
|
||||||
### 在线假期信息配置路径
|
|
||||||
|
|
||||||
> 在线模式：config.setOnline(true);时，需要配置在线数据获取路径
|
|
||||||
|
|
||||||
```java
|
|
||||||
config.setHost("http://www.chinaweal.com.cn:8090/holiday-api");// 目前公司的数据后端路径
|
|
||||||
```
|
|
||||||
|
|
||||||
> 离线模式：config.setOnline(false);时，需要配置离线数据获取路径
|
|
||||||
|
|
||||||
```java
|
|
||||||
config.setConfigPath("classpath:holiday");
|
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);
|
||||||
```
|
```
|
||||||
|
|
||||||
> json数据通过公司后端接口 http://www.chinaweal.com.cn:8090/holiday-api/api/holiday/export/{year}.json 获取，并以`.json`
|
## 🏗️ 项目结构
|
||||||
> 为扩展名，保存到上面配置的路径下，配置了定时采集任务的时间后，只需通过修改或增添`.json`文件即可。无需重启项目
|
|
||||||
|
|
||||||
### 初始化后调用
|
```
|
||||||
|
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/ # 示例代码
|
||||||
|
```
|
||||||
|
|
||||||
```java
|
## 🔧 构建
|
||||||
// 推算工作日
|
|
||||||
HolidayCalculator.calcWorkDate(LocalDate.now(), 4);
|
|
||||||
// 判断是否是工作日
|
|
||||||
HolidayCalculator.
|
|
||||||
|
|
||||||
isWorkDay(LocalDate.now());
|
```bash
|
||||||
// 判断限制是否为工作时间
|
# 编译项目
|
||||||
HolidayCalculator.
|
mvn clean compile
|
||||||
|
|
||||||
isWorkTime(LocalDateTime.now());
|
# 打包项目
|
||||||
```
|
mvn clean package
|
||||||
|
|
||||||
|
# 安装到本地仓库
|
||||||
|
mvn clean install
|
||||||
|
```
|
||||||
|
|
||||||
|
## 📄 文档
|
||||||
|
|
||||||
|
- [详细配置说明](CLAUDE.md)
|
||||||
|
- [Spring Boot 集成指南](README-SPRING-BOOT.md)
|
||||||
|
- [Spring Boot 3 部署指南](SPRING-BOOT-3-GUIDE.md)
|
||||||
|
- [部署指南](DEPLOYMENT-GUIDE.md)
|
||||||
|
- [Bean 冲突修复说明](BEAN-CONFLICT-FIX.md)
|
||||||
|
|
||||||
|
## 🤝 贡献
|
||||||
|
|
||||||
|
欢迎提交 Issue 和 Pull Request！
|
||||||
|
|
||||||
|
## 📄 许可证
|
||||||
|
|
||||||
|
MIT License
|
||||||
|
|
||||||
|
## 🔗 相关链接
|
||||||
|
|
||||||
|
- [Spring Boot 官方文档](https://spring.io/projects/spring-boot)
|
||||||
|
- [Maven 中央仓库](https://search.maven.org/)
|
||||||
27
pom.xml
27
pom.xml
|
|
@ -6,7 +6,7 @@
|
||||||
|
|
||||||
<groupId>com.chinaweal.youfool</groupId>
|
<groupId>com.chinaweal.youfool</groupId>
|
||||||
<artifactId>youfool-holiday-sdk</artifactId>
|
<artifactId>youfool-holiday-sdk</artifactId>
|
||||||
<version>1.0.0-SNAPSHOT</version>
|
<version>1.0.0</version>
|
||||||
<packaging>jar</packaging>
|
<packaging>jar</packaging>
|
||||||
<name>${project.artifactId}</name>
|
<name>${project.artifactId}</name>
|
||||||
<url>https://www.chinaweal.com.cn</url>
|
<url>https://www.chinaweal.com.cn</url>
|
||||||
|
|
@ -26,7 +26,7 @@
|
||||||
<dependency>
|
<dependency>
|
||||||
<groupId>org.projectlombok</groupId>
|
<groupId>org.projectlombok</groupId>
|
||||||
<artifactId>lombok</artifactId>
|
<artifactId>lombok</artifactId>
|
||||||
<version>1.18.12</version>
|
<version>1.18.30</version>
|
||||||
<scope>provided</scope>
|
<scope>provided</scope>
|
||||||
</dependency>
|
</dependency>
|
||||||
<!-- https://mvnrepository.com/artifact/com.alibaba.fastjson2/fastjson2 -->
|
<!-- https://mvnrepository.com/artifact/com.alibaba.fastjson2/fastjson2 -->
|
||||||
|
|
@ -41,6 +41,24 @@
|
||||||
<version>4.12</version>
|
<version>4.12</version>
|
||||||
<scope>test</scope>
|
<scope>test</scope>
|
||||||
</dependency>
|
</dependency>
|
||||||
|
|
||||||
|
<!-- Spring Boot 自动配置支持 - 兼容 Spring Boot 2.7.x 和 3.x -->
|
||||||
|
<dependency>
|
||||||
|
<groupId>org.springframework.boot</groupId>
|
||||||
|
<artifactId>spring-boot-autoconfigure</artifactId>
|
||||||
|
<version>2.7.18</version>
|
||||||
|
<scope>provided</scope>
|
||||||
|
<optional>true</optional>
|
||||||
|
</dependency>
|
||||||
|
|
||||||
|
<!-- Spring Boot 配置处理器，用于生成配置元数据 -->
|
||||||
|
<dependency>
|
||||||
|
<groupId>org.springframework.boot</groupId>
|
||||||
|
<artifactId>spring-boot-configuration-processor</artifactId>
|
||||||
|
<version>2.7.18</version>
|
||||||
|
<scope>provided</scope>
|
||||||
|
<optional>true</optional>
|
||||||
|
</dependency>
|
||||||
</dependencies>
|
</dependencies>
|
||||||
|
|
||||||
<build>
|
<build>
|
||||||
|
|
@ -69,5 +87,10 @@
|
||||||
<name>Nexus Snapshot Repository</name>
|
<name>Nexus Snapshot Repository</name>
|
||||||
<url>http://121.8.152.130:8081/nexus/content/repositories/snapshots/</url>
|
<url>http://121.8.152.130:8081/nexus/content/repositories/snapshots/</url>
|
||||||
</snapshotRepository>
|
</snapshotRepository>
|
||||||
|
<repository>
|
||||||
|
<id>nexus</id>
|
||||||
|
<name>Nexus Release Repository</name>
|
||||||
|
<url>http://121.8.152.130:8081/nexus/content/repositories/releases/</url>
|
||||||
|
</repository>
|
||||||
</distributionManagement>
|
</distributionManagement>
|
||||||
</project>
|
</project>
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,7 @@
|
||||||
package com.chinaweal.youfool.holiday.sdk;
|
package com.chinaweal.youfool.holiday.sdk;
|
||||||
|
|
||||||
import com.chinaweal.youfool.holiday.sdk.config.HolidayCalculatorConfig;
|
import com.chinaweal.youfool.holiday.sdk.config.HolidayCalculatorConfig;
|
||||||
|
import com.chinaweal.youfool.holiday.sdk.config.HolidayCalculatorProperties;
|
||||||
import com.chinaweal.youfool.holiday.sdk.data.entity.Holiday;
|
import com.chinaweal.youfool.holiday.sdk.data.entity.Holiday;
|
||||||
import com.chinaweal.youfool.holiday.sdk.data.manager.HolidayDataManager;
|
import com.chinaweal.youfool.holiday.sdk.data.manager.HolidayDataManager;
|
||||||
import com.chinaweal.youfool.holiday.sdk.data.manager.LocationHolidayDataManager;
|
import com.chinaweal.youfool.holiday.sdk.data.manager.LocationHolidayDataManager;
|
||||||
|
|
@ -78,6 +79,28 @@ public abstract class HolidayCalculator {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 从 Spring Boot 配置属性初始化
|
||||||
|
*
|
||||||
|
* @param properties Spring Boot 配置属性
|
||||||
|
* @author lroyia
|
||||||
|
* @since 2025/11/12
|
||||||
|
*/
|
||||||
|
public static void initFromProperties(HolidayCalculatorProperties properties) {
|
||||||
|
if (!properties.isEnabled()) {
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
HolidayCalculatorConfig config = new HolidayCalculatorConfig();
|
||||||
|
config.setOnline(properties.isOnline());
|
||||||
|
config.setHost(properties.getHost());
|
||||||
|
config.setConfigPath(properties.getConfigPath());
|
||||||
|
config.setWorkTime(properties.getWorkTime());
|
||||||
|
config.setFlushInterval(properties.getFlushInterval());
|
||||||
|
|
||||||
|
init(config);
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* 计算工作日
|
* 计算工作日
|
||||||
*
|
*
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,61 @@
|
||||||
|
package com.chinaweal.youfool.holiday.sdk.config;
|
||||||
|
|
||||||
|
import com.chinaweal.youfool.holiday.sdk.HolidayCalculator;
|
||||||
|
import org.springframework.boot.autoconfigure.AutoConfiguration;
|
||||||
|
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
|
||||||
|
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
|
||||||
|
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
|
||||||
|
import org.springframework.boot.context.properties.EnableConfigurationProperties;
|
||||||
|
import org.springframework.context.annotation.Bean;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 假期计算器自动配置类
|
||||||
|
* 兼容 Spring Boot 2.7.x 和 3.x
|
||||||
|
*
|
||||||
|
* @author lroyia
|
||||||
|
* @since 2025/11/12
|
||||||
|
*/
|
||||||
|
@AutoConfiguration
|
||||||
|
@ConditionalOnClass(HolidayCalculator.class)
|
||||||
|
@ConditionalOnProperty(prefix = "youfool.holiday", name = "enabled", havingValue = "true", matchIfMissing = true)
|
||||||
|
@EnableConfigurationProperties(HolidayCalculatorProperties.class)
|
||||||
|
public class HolidayCalculatorAutoConfiguration {
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 假期计算器配置属性 Bean
|
||||||
|
* Spring Boot 2.x 中需要手动创建配置属性 Bean
|
||||||
|
*
|
||||||
|
* @param properties 配置属性
|
||||||
|
* @return 配置属性 Bean
|
||||||
|
*/
|
||||||
|
@Bean
|
||||||
|
@ConditionalOnMissingBean
|
||||||
|
public HolidayCalculatorProperties holidayCalculatorProperties() {
|
||||||
|
System.out.println("Spring Boot 2 - 注册 HolidayCalculatorProperties Bean");
|
||||||
|
return new HolidayCalculatorProperties();
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 自动初始化假期计算器
|
||||||
|
*
|
||||||
|
* @param properties 配置属性
|
||||||
|
*/
|
||||||
|
@Bean
|
||||||
|
@ConditionalOnProperty(prefix = "youfool.holiday", name = "auto-init", havingValue = "true", matchIfMissing = true)
|
||||||
|
public HolidayCalculatorInitializer holidayCalculatorInitializer(HolidayCalculatorProperties properties) {
|
||||||
|
System.out.println("自动初始化假期计算器，配置: 在线模式=" + properties.isOnline() + ", 工作时间=" + properties.getWorkTime());
|
||||||
|
|
||||||
|
// 初始化假期计算器
|
||||||
|
HolidayCalculator.initFromProperties(properties);
|
||||||
|
|
||||||
|
return new HolidayCalculatorInitializer();
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 假期计算器初始化器
|
||||||
|
* 用于标记自动初始化已完成
|
||||||
|
*/
|
||||||
|
public static class HolidayCalculatorInitializer {
|
||||||
|
// 空实现，仅用于标记
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,47 @@
|
||||||
|
package com.chinaweal.youfool.holiday.sdk.config;
|
||||||
|
|
||||||
|
import com.chinaweal.youfool.holiday.sdk.HolidayCalculator;
|
||||||
|
import org.springframework.boot.autoconfigure.AutoConfiguration;
|
||||||
|
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
|
||||||
|
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
|
||||||
|
import org.springframework.boot.context.properties.EnableConfigurationProperties;
|
||||||
|
import org.springframework.context.annotation.Bean;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 假期计算器 Spring Boot 3 自动配置类
|
||||||
|
* 针对 Spring Boot 3.x 优化
|
||||||
|
*
|
||||||
|
* @author lroyia
|
||||||
|
* @since 2025/11/12
|
||||||
|
*/
|
||||||
|
@AutoConfiguration
|
||||||
|
@ConditionalOnClass(HolidayCalculator.class)
|
||||||
|
@ConditionalOnProperty(prefix = "youfool.holiday", name = "enabled", havingValue = "true", matchIfMissing = true)
|
||||||
|
@EnableConfigurationProperties(HolidayCalculatorProperties.class)
|
||||||
|
public class HolidayCalculatorAutoConfigurationV3 {
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 自动初始化假期计算器
|
||||||
|
* Spring Boot 3 中，@ConfigurationProperties 会自动注册 Bean，不需要手动创建
|
||||||
|
*
|
||||||
|
* @param properties 配置属性（由 Spring Boot 3 自动注入）
|
||||||
|
*/
|
||||||
|
@Bean
|
||||||
|
@ConditionalOnProperty(prefix = "youfool.holiday", name = "auto-init", havingValue = "true", matchIfMissing = true)
|
||||||
|
public HolidayCalculatorInitializerV3 holidayCalculatorInitializer(HolidayCalculatorProperties properties) {
|
||||||
|
System.out.println("Spring Boot 3 - 自动初始化假期计算器，配置: 在线模式=" + properties.isOnline() + ", 工作时间=" + properties.getWorkTime());
|
||||||
|
|
||||||
|
// 初始化假期计算器
|
||||||
|
HolidayCalculator.initFromProperties(properties);
|
||||||
|
|
||||||
|
return new HolidayCalculatorInitializerV3();
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 假期计算器初始化器
|
||||||
|
* 用于标记自动初始化已完成
|
||||||
|
*/
|
||||||
|
public static class HolidayCalculatorInitializerV3 {
|
||||||
|
// 空实现，仅用于标记
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,53 @@
|
||||||
|
package com.chinaweal.youfool.holiday.sdk.config;
|
||||||
|
|
||||||
|
import lombok.Data;
|
||||||
|
import org.springframework.boot.context.properties.ConfigurationProperties;
|
||||||
|
import org.springframework.stereotype.Component;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 假期计算器 Spring Boot 配置属性
|
||||||
|
*
|
||||||
|
* @author lroyia
|
||||||
|
* @since 2025/11/12
|
||||||
|
*/
|
||||||
|
@Data
|
||||||
|
@ConfigurationProperties(prefix = "youfool.holiday")
|
||||||
|
public class HolidayCalculatorProperties {
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 是否启用假期计算器，默认启用
|
||||||
|
*/
|
||||||
|
private boolean enabled = true;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 是否在线模式，在线模式会从网络获取数据，离线模式会从本地文件获取数据
|
||||||
|
* 默认为离线模式
|
||||||
|
*/
|
||||||
|
private boolean online = false;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 服务器地址，在线模式下使用
|
||||||
|
*/
|
||||||
|
private String host = "http://www.chinaweal.com.cn:8090/holiday-api";
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 本地假期配置目录，默认为classpath:holiday
|
||||||
|
*/
|
||||||
|
private String configPath = "classpath:holiday";
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 工作时间区间配置，多个用;隔开，示例：08:00-12:00;14:00-17:00
|
||||||
|
* 默认为 09:00-18:00
|
||||||
|
*/
|
||||||
|
private String workTime = "09:00-18:00";
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 刷新间隔（秒），-1为不刷新，默认15分钟
|
||||||
|
*/
|
||||||
|
private long flushInterval = 60 * 15;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 是否在 Spring Boot 启动时自动初始化，默认自动初始化
|
||||||
|
*/
|
||||||
|
private boolean autoInit = true;
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,46 @@
|
||||||
|
{
|
||||||
|
"properties": [
|
||||||
|
{
|
||||||
|
"name": "youfool.holiday.enabled",
|
||||||
|
"type": "java.lang.Boolean",
|
||||||
|
"defaultValue": true,
|
||||||
|
"description": "是否启用假期计算器。"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "youfool.holiday.online",
|
||||||
|
"type": "java.lang.Boolean",
|
||||||
|
"defaultValue": false,
|
||||||
|
"description": "是否在线模式。在线模式会从网络获取数据，离线模式会从本地文件获取数据。"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "youfool.holiday.host",
|
||||||
|
"type": "java.lang.String",
|
||||||
|
"defaultValue": "http://www.chinaweal.com.cn:8090/holiday-api",
|
||||||
|
"description": "服务器地址，在线模式下使用。"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "youfool.holiday.config-path",
|
||||||
|
"type": "java.lang.String",
|
||||||
|
"defaultValue": "classpath:holiday",
|
||||||
|
"description": "本地假期配置目录。"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "youfool.holiday.work-time",
|
||||||
|
"type": "java.lang.String",
|
||||||
|
"defaultValue": "09:00-18:00",
|
||||||
|
"description": "工作时间区间配置，多个用;隔开，示例：08:00-12:00;14:00-17:00。"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "youfool.holiday.flush-interval",
|
||||||
|
"type": "java.lang.Long",
|
||||||
|
"defaultValue": 900,
|
||||||
|
"description": "刷新间隔（秒），-1为不刷新，默认15分钟。"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "youfool.holiday.auto-init",
|
||||||
|
"type": "java.lang.Boolean",
|
||||||
|
"defaultValue": true,
|
||||||
|
"description": "是否在 Spring Boot 启动时自动初始化。"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,2 @@
|
||||||
|
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
|
||||||
|
com.chinaweal.youfool.holiday.sdk.config.HolidayCalculatorAutoConfiguration
|
||||||
|
|
@ -0,0 +1 @@
|
||||||
|
com.chinaweal.youfool.holiday.sdk.config.HolidayCalculatorAutoConfigurationV3
|
||||||
Loading…
Reference in New Issue