有时候,我们处理一些业务,比如:计算员工请假的时间工作日;就需要数据库内存在一张工作日历,记录调休和节假日。
实际上,是有很多的公共接口。但是很多情况下,我们需要在内网环境下使用,这个时候就需要在数据库内生成工作日历表,如果使用频繁,甚至考虑缓存到中间件Redis内。
那么,如何在数据库内生成一个工作日历表呢?
离线日历库
如果只是简单的日历,那么其实系统自带的日历功能,也足够我们使用;比如iOS自带的日历,可以轻松滑动到300年后:
关键我们需要的是完整的放假表,例如: 2024年的9月14日,因为中秋节调休,周六要上班。所以,我们肯定需要一个工作日历的数据来源。
对于中国的节假日,最准确的肯定是中国政府网每年下半年发布次年的节假日和调休表(每次都是第一时间关注又要调休几次、最多要连续上几天的班╳╳○○),比如: 2024年的放假安排
如何获取一个离线的日历库呢?推荐以下几个项目:
- 中国节假日、调休日、工作日、24节气查询,农历阳历互转,支持 TS、CommonJS、UMD 模块化使用: https://github.com/vsme/chinese-days
- 判断一天是不是法定节假日/法定工作日(查看节假日安排): https://github.com/LKI/chinese-calendar
项目vsme/chinese-days
是有提供调休的JSON文件的:chinese-days.json,内部主要用两个部分:
- holidays: 放假的日期;
- workdays: 因节日而调休的日期。
理论上,你可以直接解析这个JSON文件,或者直接使用项目封装好的功能:
js
<script src="https://cdn.jsdelivr.net/npm/chinese-days/dist/index.min.js"></script>
<script>
// 检查某个日期是否为工作日
console.log(isWorkday('2023-01-01')); // false
// isHoliday 检查某个日期是否为节假日
console.log(isHoliday('2023-01-01')); // true
// 检查某个日期是否为调休日(in lieu day)
// 检查 2024-05-02 返回 `true` 则表示是一个调休日。
console.log(isInLieu('2024-05-02')); // true
// 检查 2024-05-01 返回 `false` 则表示不是一个调休日。
console.log(isInLieu('2024-05-01')); // false
</script>
当然,为了可以生成SQL脚本,我们这里使用LKI/chinese-calendar
库,接下来我们就来演示。
ChineseCalendar
LKI/chinese-calendar
是基于Python的一个日期项目,如果你观察源码,你会发现日期数据是使用枚举类和Python字典存储的:
甚至结构和vsme/chinese-days
也是一样的;其实vsme/chinese-days
的JSON数据就是基于LKI/chinese-calendar
的。在vsme/chinese-days
的项目简介内,就有提及。
两个项目,都是基于MIT协议,在团队和企业内也可以放心使用。
比较有趣的是节日的中英名字映射、放假天数,LKI/chinese-calendar
使用的是枚举类:
Python
class Holiday(Enum):
def __new__(cls, english, chinese, days):
obj = object.__new__(cls)
obj._value_ = english
obj.chinese = chinese
obj.days = days
return obj
new_years_day = "New Year's Day", "元旦", 1
spring_festival = "Spring Festival", "春节", 3
tomb_sweeping_day = "Tomb-sweeping Day", "清明", 1
labour_day = "Labour Day", "劳动节", 1
dragon_boat_festival = "Dragon Boat Festival", "端午", 1
national_day = "National Day", "国庆节", 3
mid_autumn_festival = "Mid-autumn Festival", "中秋", 1
# special holidays
anti_fascist_70th_day = "Anti-Fascist 70th Day", "中国人民抗日战争暨世界反法西斯战争胜利70周年纪念日", 1
倒不是使用枚举类有多么让人意想不到,只是发现原来放假的节日这么少😭。
至于这个库怎么使用,其实也很简单:
bash
import datetime
# 判断 2018年4月30号 是不是节假日
from chinese_calendar import is_holiday, is_workday
april_last = datetime.date(2018, 4, 30)
assert is_workday(april_last) is False
assert is_holiday(april_last) is True
# 或者在判断的同时,获取节日名
import chinese_calendar as calendar # 也可以这样 import
on_holiday, holiday_name = calendar.get_holiday_detail(april_last)
assert on_holiday is True
assert holiday_name == calendar.Holiday.labour_day.value
# 还能判断法定节假日是不是调休
import chinese_calendar
assert chinese_calendar.is_in_lieu(datetime.date(2006, 2, 1)) is False
assert chinese_calendar.is_in_lieu(datetime.date(2006, 2, 2)) is True
接下来,我们就封转一下。 使其生成SQL脚本。
数据库设计
既然需要一张表来存储工作日历,那么数据库的表应该如何设计?
我这里设计得比较简单,采用每天一条记录的方式进行记录,表名为WORK_CALENDAR
,主键为CALENDAR_DATE
:
YEAR | CALENDAR_DATE | DATE_TYPE | COMMENTS |
---|---|---|---|
2024 | 2024-01-01 | 1 | New Year's Day |
2024 | 2024-01-02 | 0 | |
2024 | 2024-01-03 | 0 | |
2024 | 2024-01-04 | 0 | |
2024 | 2024-01-05 | 0 | |
2024 | 2024-01-06 | 3 | |
2024 | 2024-01-07 | 3 | |
解释一下各个字段:
YEAR
: 日期所属的年份;CALENDAR_DATE
: 数据对应的日期;DATE_TYPE
: 日期类型,0为普通工作日,1为节日放假,2为节日调休补班,3为周末放假;COMMENTS
: 备注节日。
可能你有更好的方法,可以评论区留言嗷。
代码实现
接下来,我们看看代码如何实现。
因为需要一次性生成一年的工作日历,所以我们需要先获取一年的数据日期,之后遍历数据日期,使用LKI/chinese-calendar
去解析每次的数据日期,将返回的结果包转为CSV或者拼接SQL。
流程图如下:
全年日期
我们先获取全年的日期,可以使用datetime
进行日期类型的创建:
python
# year为所属的年,如:2024
begin = datetime.date(year, 1, 1)
之后,使用datetime.timedelta(days=1)
方法 ,获取一条的数值,并遍历累加即可。完整的代码为:
python
def get_whole_year(year=TARGET_YEAR):
"""
获取一年内所有的日期
:param year: 获取的年
:return: 日期数组
"""
begin = datetime.date(year, 1, 1) # 设置开始日期为给定年的1月1日
now = begin
end = datetime.date(year, 12, 31) # 设置结束日期为给定年的12月31日
delta = datetime.timedelta(days=1) # 定义日期增量为1天
days = [] # 初始化日期数组
while now <= end: # 循环直到当前日期达到结束日期
days.append(now.strftime("%Y-%m-%d")) # 将当前日期以"YYYY-MM-DD"格式添加到数组中
now += delta # 增加日期增量
return days # 返回日期数组
日期类型
在项目的代码内,我们知道LKI/chinese-calendar
返回的都是True
或Fasle
,比如:calendar.is_workday(date)
。
但是我们数据库内的设计,使用的是0~3
作为存储,并且还有一个注释字段,用来存储节日;所以,我们也需要设计一个枚举类,用来映射:
python
class DATATYPE(Enum):
"""
日期类型枚举类
"""
WORKDAY = ("0", "普通工作日")
WEEKEND = ("3", "普通周末")
HOLIDAY = ("1", "节日假期")
WORKING_HOLIDAY = ("2", "节日补班")
def __init__(self, code: str, description: str):
self.code = code
self.description = description
@property
def code(self) -> str:
return self._code
@code.setter
def code(self, value: str):
self._code = value
@property
def description(self) -> str:
return self._description
@description.setter
def description(self, value: str):
self._description = value
当我们进行日期的判断,就可以把布尔类型,经过枚举进行包转:
python
if calendar.is_holiday(date):
print("{}是节假日".format(judge_date))
on_holiday, holiday_name = calendar.get_holiday_detail(date)
# 判断是否为节日(否:周末;是:节日)
if holiday_name is not None:
return DATATYPE.HOLIDAY.code + "-" + str(holiday_name)
else:
return DATATYPE.WEEKEND.code
实现效果
最后,把上述的代码进行整理,核心判断内容就这样完成了:
python
def judge_date_type(judge_date):
"""
判断日期的类型
:param judge_date:
:return: 判断的类型;如果是假期有关,附带假期备注
"""
date = datetime.datetime.strptime(judge_date, '%Y-%m-%d').date()
if calendar.is_holiday(date):
print("{}是节假日".format(judge_date))
on_holiday, holiday_name = calendar.get_holiday_detail(date)
# 判断是否为节日(否:周末;是:节日)
if holiday_name is not None:
return DATATYPE.HOLIDAY.code + "-" + str(holiday_name)
else:
return DATATYPE.WEEKEND.code
elif calendar.is_workday(date):
on_holiday, holiday_name = calendar.get_holiday_detail(date)
if holiday_name is not None:
# 节日名称为非空,说明是补班,否则就是普通工作日
print("{}是补班日".format(judge_date))
return DATATYPE.WORKING_HOLIDAY.code + "-" + str(holiday_name)
else:
return DATATYPE.WORKDAY.code
else:
# 理论上不存在没有匹配的情况
print("{}没有匹配" .format(judge_date))
assert False
再使用pandas进行包装一下,可以轻松得到SQL和CSV文件:
完整的代码,可以在我的GitHub仓库上找到:
END
哈哈,本次的分享就到这边。 其实是一件非常简单的事情,希望设计思路可以帮助到你。
如果你也需要工作日历,那么你可以直接clone代码并运行即可。
大家一般又是如何生成"工作日历"的呢?