做过考勤、工时统计、审批流的人都躲不开一个需求：判断某天是不是工作日，是不是法定节假日，要不要调休上班。自己维护一张节假日表看起来最简单，但每年国务院办公厅的通知一出，就得重新改一遍数据。所以多数团队最后都会去找节假日接口。

接口一般返回什么

一个够用的节假日接口，至少能给出三类信息：日期、当天类型（工作日、休息日、法定节假日）、以及是否调休。稍微完善一点的还会带农历、节日名称和所属年份。

典型返回长这样：

{
  "code": 200,
  "data": [
    { "date": "2026-10-01", "type": "holiday", "name": "国庆节", "workday": false }
  ]
}

拿到数据后，本地缓存一份，按年份或按天索引，比每次请求都走网络稳定。

免费接口的几种来源

  • 公开的聚合数据源：有人把每年的放假安排整理成 JSON 放到 GitHub，直接拉 raw 文件。优点是免费、结构清楚；缺点是得自己找可信的仓库，年份更新有滞后。
  • 商业 API 平台的免费额度：多数平台每天给几百次调用，适合小项目，但要留意是否需要实名、是否能商用。
  • 日历类开放接口：部分日历服务提供节假日字段，稳定性好，但字段较少，调休信息不一定全。

选型时重点看什么

第一看更新时效。每年的放假安排通常在前一年年底公布，接口能不能在公布后一周内更新，直接影响考勤算得对不对。

第二看调休。只看「是不是周末」是不够的，节假日前后经常有周末调班，这一项错了，加班费就全错。

第三看调用限制。有的接口按 IP 限流，服务器出口 IP 固定的话容易撞上限；有的要求携带 key 且有 QPS 限制。

几个实际踩过的坑

遇到过接口把「元旦」写成一天，但实际放假是三天，原因是它只返回法定节日当天，不含调休连休。也遇到过跨年边界问题，12 月 31 日查不到数据，因为接口只提供当年和次年。

还有个细节，时区。接口返回的日期一般按北京时间算，服务器如果设成 UTC，跨零点判断会出现偏差，建议统一按东八区转换后再比较。

更稳的做法

别把业务完全绑在一个接口上。自己维护一份基础表，接口只作为每年的更新来源和校验来源，两者对不上时告警。这样即使接口停服，考勤逻辑还能照常跑。

如果用量不大，直接抓公开的节假日 JSON 定为定时任务更省事，一年只需要真正更新一两次，却少了一个外部依赖。