中国法定节假日API自动更新：从抓取解析到缓存降级的工程实践

简介这是一套面向Java开发者的中国法定节假日查询接口项目用于解决业务系统中节假日判断、调休安排与工作日计算等常见需求。项目提供单一HTTP接口支持按日期、月份或年份查询返回结构化的节假日信息并可将数据保存至数据库以降低对网络的依赖同时具备自动更新能力调用方式简单直接。压缩包共25个文件约102KB以12个Java源码文件为核心配合3个SQL脚本用于建表与数据初始化另有2个XML配置、2个properties配置及mvnw、jar等构建运行文件整体结构清晰便于二次开发与本地部署。目前已有7530人学习下载适合需要快速集成节假日判断能力的Java后端开发者参考使用。需要说明的是该项目为个人开源作品作者不保证永久维护使用者可结合自身业务场景评估后直接接入或改造。1. 节假日 API 的自动更新到底在解决什么问题每年元旦刚过日历类、考勤类、排班类应用就会集体进入一种焦虑状态第二年的放假安排还没公布但用户已经在问“春节放几天”“调休怎么算”。等通知出来运维又得连夜改配置、重新发版。这个标题里的holiday:chinese holiday 获取中国法定节假日API 自动更新说的就是把这套流程从“人工盯通知”变成“程序自己拉取、自己更新、自己兜底”。它解决的核心问题有三个一是数据源的时效性法定节假日安排每年由官方在年底前后发布API 必须能感知变化二是调用方的稳定性业务代码不应该关心数据从哪来、什么时候变只关心“给我某天的状态”三是缓存与降级官方接口不可用时本地要有一份可用的快照。适合谁做考勤、排班、日历、OA、外卖预约、旅游预订的开发者尤其是那些被“调休”两个字折磨过的人。2. 先想清楚数据从哪来三种取数路径的取舍2.1 官方公告页解析与第三方聚合接口的差别做节假日数据绕不开“数据源”这个第一性问题。常见做法有三类第一类是直接解析官方公告页优点是权威、免费缺点是页面结构可能调整解析规则要跟着维护第二类是调用第三方聚合 API优点是省事、返回结构统一缺点是依赖外部服务可能限流、收费或突然下线第三类是自己维护一份 JSON 文件手动更新优点是绝对可控缺点是失去了“自动更新”的意义。我一般会采用“官方解析为主、本地快照兜底”的混合策略。具体来说写一个抓取器定期去拉官方公告页解析出节假日和调休日期写入本地数据库同时对外暴露一个查询接口业务方只调这个接口。这样即使某次抓取失败本地还有上一次成功的数据可用。第三方聚合接口可以作为备选但不作为唯一来源否则哪天对方改了规则你的系统就跟着翻车。2.2 数据模型日期、类型、年份三个字段就够了吗很多人第一版会把数据模型设计得很简单date、typeholiday/workday。但实际用起来会发现不够。比如“春节”本身是节日但调休上班的周六周日是工作日这两者需要区分再比如有些日期是“法定节假日但调休”有些是“周末正常休息”业务方可能想知道具体名称。我建议的最小字段集是dateYYYY-MM-DD、year年份、type枚举holiday / workday / weekend、name节日名称如“春节”“国庆节”、is_offday布尔是否放假。这样查询时既可以直接按is_offday判断也可以按name做展示。下面是一个建表语句示例CREATE TABLE holiday_calendar ( id INT PRIMARY KEY AUTO_INCREMENT, date DATE NOT NULL, year INT NOT NULL, type ENUM(holiday, workday, weekend) NOT NULL, name VARCHAR(64) DEFAULT NULL, is_offday TINYINT(1) NOT NULL DEFAULT 0, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, UNIQUE KEY uk_date (date), KEY idx_year (year) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;逻辑说明date加唯一索引保证同一天不会重复插入year加普通索引方便按年查询updated_at用于排查数据是什么时候更新的。参数上type用枚举而不是字符串是为了避免拼写错误is_offday冗余存储是为了查询时不用再判断type直接WHERE is_offday 1就能拿到所有放假日期。2.3 抓取频率与触发时机定时任务还是事件驱动自动更新的“自动”体现在触发机制上。最朴素的是每天凌晨跑一次定时任务但节假日安排通常一年只发布一次每天跑有点浪费。更合理的做法是在每年 11 月到次年 1 月之间提高抓取频率比如每天一次其他月份降低到每周一次同时提供一个手动触发接口方便运维在收到消息后立即更新。如果你用的是 Linux 服务器cron 表达式可以这样写# 每年 11 月到次年 1 月每天凌晨 2 点执行 0 2 * * * [ $(date \%m) -ge 11 ] || [ $(date \%m) -le 1 ] /usr/bin/python3 /opt/holiday/fetch.py /var/log/holiday.log 21 # 其他月份每周一凌晨 3 点执行 0 3 * * 1 [ $(date \%m) -gt 1 ] [ $(date \%m) -lt 11 ] /usr/bin/python3 /opt/holiday/fetch.py /var/log/holiday.log 21逻辑说明第一行判断月份是否在 11 到 1 之间是则每天执行第二行判断月份是否在 2 到 10 之间是则每周一执行。注意 cron 里的%需要转义。参数上日志重定向到文件方便后续排查抓取失败的原因。如果你不想用 shell 判断也可以把频率逻辑写在 Python 脚本里用schedule库或 APScheduler 来控制。3. 把抓取和解析写成可复现的脚本3.1 用 Python 请求官方公告页并提取关键字段假设官方公告页的 HTML 结构是稳定的实际中需要定期检查我们可以用requests加BeautifulSoup来解析。下面是一个最小可运行示例import requests from bs4 import BeautifulSoup import re from datetime import datetime def fetch_holiday_notice(url): headers { User-Agent: Mozilla/5.0 (compatible; HolidayBot/1.0) } resp requests.get(url, headersheaders, timeout10) resp.raise_for_status() resp.encoding resp.apparent_encoding soup BeautifulSoup(resp.text, html.parser) # 假设公告正文在 div classcontent 里 content soup.find(div, class_content) if not content: raise ValueError(未找到公告正文容器) text content.get_text(stripTrue) return text def parse_holiday_text(text): # 匹配类似“1月1日至3日放假调休共3天”的句式 pattern re.compile(r(\d)月(\d)日至(\d)日放假) matches pattern.findall(text) result [] for m in matches: start_month, start_day, end_day int(m[0]), int(m[1]), int(m[2]) year datetime.now().year # 这里只做示例实际需要处理跨年、调休等复杂情况 result.append({ year: year, start: f{year}-{start_month:02d}-{start_day:02d}, end: f{year}-{start_month:02d}-{end_day:02d} }) return result逻辑说明fetch_holiday_notice负责发请求并拿到正文文本parse_holiday_text用正则提取放假区间。参数上timeout10防止请求卡死resp.apparent_encoding自动识别编码避免中文乱码。注意这只是一个演示真实公告里还有“调休”“上班”等描述需要更复杂的解析规则。我一般会把解析规则写成配置文件方便页面改版时快速调整。3.2 把解析结果写入数据库并做去重拿到解析结果后不能直接插入因为同一年可能多次抓取重复插入会触发唯一索引冲突。可以用INSERT ... ON DUPLICATE KEY UPDATE来更新INSERT INTO holiday_calendar (date, year, type, name, is_offday) VALUES (%s, %s, %s, %s, %s) ON DUPLICATE KEY UPDATE type VALUES(type), name VALUES(name), is_offday VALUES(is_offday), updated_at CURRENT_TIMESTAMP;逻辑说明ON DUPLICATE KEY UPDATE在遇到date唯一索引冲突时会更新已有记录而不是报错。参数上VALUES(type)表示使用本次插入的值。这样即使同一天被解析多次最终数据也是一致的。注意 MySQL 的VALUES函数在 8.0.20 之后被标记为废弃可以用别名写法但为了兼容性这里保留传统写法。3.3 对外提供查询接口按日期和按年份两种入参业务方通常有两种查询需求查某一天是不是放假或者查某一年所有放假日期。可以用 Flask 写两个简单接口from flask import Flask, request, jsonify import pymysql app Flask(__name__) def get_db(): return pymysql.connect(hostlocalhost, userroot, password, dbholiday, charsetutf8mb4) app.route(/api/holiday/day) def query_day(): date request.args.get(date) if not date: return jsonify({error: missing date}), 400 conn get_db() with conn.cursor(pymysql.cursors.DictCursor) as cur: cur.execute(SELECT date, type, name, is_offday FROM holiday_calendar WHERE date %s, (date,)) row cur.fetchone() conn.close() if not row: return jsonify({error: not found}), 404 return jsonify(row) app.route(/api/holiday/year) def query_year(): year request.args.get(year) if not year: return jsonify({error: missing year}), 400 conn get_db() with conn.cursor(pymysql.cursors.DictCursor) as cur: cur.execute(SELECT date, type, name, is_offday FROM holiday_calendar WHERE year %s ORDER BY date, (year,)) rows cur.fetchall() conn.close() return jsonify(rows)逻辑说明/api/holiday/day接收date参数返回单日状态/api/holiday/year接收year参数返回该年所有记录。参数上pymysql.cursors.DictCursor让查询结果以字典形式返回方便直接转 JSON。注意数据库连接没有做连接池生产环境建议用 SQLAlchemy 或连接池管理。4. 避坑与排查那些让我连夜改代码的瞬间4.1 现象接口返回的放假日期比官方少一天原因解析正则只匹配了“至”字但官方公告里有时写“1月1日至3日”有时写“1月1日、2日、3日”格式不统一。解决把解析规则拆成多个模式按优先级依次尝试并记录日志。如果所有模式都匹配失败触发告警人工介入。4.2 现象调休上班的周六被标记成了放假原因数据模型里type只有 holiday 和 workday但周末正常休息没有单独标记导致查询时把调休上班的周六误判为放假。解决引入weekend类型并在查询接口里明确is_offday 1才是放假type workday是调休上班。4.3 现象跨年日期解析错误12 月 31 日被算到了下一年原因解析时直接用datetime.now().year如果公告在 12 月发布跨年日期会出错。解决从公告文本里提取年份或者根据公告标题里的“2025年”来指定年份不要依赖当前时间。4.4 现象官方页面改版后抓取脚本直接报错退出原因soup.find(div, class_content)找不到容器抛出异常后没有兜底。解决在抓取函数里加 try-except失败时记录日志并保留上一次数据同时设置告警比如连续失败 3 次发邮件通知。4.5 现象数据库里同一天出现两条记录一条 holiday 一条 workday原因唯一索引建在了date上但插入时用了INSERT IGNORE或没有正确处理冲突。解决确保唯一索引存在并用ON DUPLICATE KEY UPDATE更新而不是忽略。如果已经出现脏数据先按date分组去重保留updated_at最新的那条。5. 进阶让自动更新更稳的几个技巧5.1 用版本号管理每次抓取结果方便回滚每次抓取成功后不要直接覆盖旧数据而是先写入一张holiday_calendar_history表记录version时间戳、raw_text原始公告文本、parsed_json解析结果。这样如果新解析有问题可以快速回滚到上一个版本。查询接口默认读最新版本但提供一个?version参数用于调试。5.2 加一层本地缓存减少数据库压力如果查询量很大可以在应用层加一层内存缓存比如用functools.lru_cache或 Redis。缓存键用date或year过期时间设为 1 小时。注意在数据更新后要主动清除缓存否则会读到旧数据。我一般会在写入数据库后发一个消息到 Redis 的 pub/sub让所有实例清缓存。5.3 监控与告警怎么知道自动更新失败了自动更新最怕的是“悄悄失败”。我一般会做三个监控一是抓取成功率连续失败 3 次发告警二是数据新鲜度如果距离上次成功更新超过 7 天发告警三是接口错误率如果/api/holiday/day的 5xx 错误超过阈值发告警。告警渠道可以用邮件、企业微信机器人或短信看团队习惯。5.4 一个具体技巧用dateutil处理调休日期的偏移调休日期经常是“周末上班”比如“1月4日星期六上班”。解析时可以用dateutil.relativedelta来计算偏移但更简单的是直接解析出具体日期字符串。如果公告里写的是“1月4日”直接转成2025-01-04即可。注意不要用datetime.strptime去猜年份年份一定要从公告里取。最后说一个我自己的习惯每次官方发布新一年安排后我会先手动跑一遍抓取脚本把结果和官方公告逐条比对确认无误后再让定时任务接管。这个“后悔药”步骤帮我避免过至少两次线上事故。希望帮到你。本文还有配套的精品资源点击获取