万年历接口怎么调：字段解析与几个坑

做考勤、排班、节假日提醒的系统，绕不开万年历。自己算农历太费劲，调用现成的接口是常规做法，但返回的数据怎么用，有几个地方不注意就会算错。

典型请求与返回

GET https://api.example.com/calendar?date=2026-10-21&key=YOUR_KEY

{
  "code": 0,
  "data": {
    "date": "2026-10-21",
    "week": "星期三",
    "lunar": "九月初一",
    "ganzhi": "丙午年 戊戌月 癸卯日",
    "term": "",
    "isWorkday": true,
    "festival": "",
    "lunarFestival": ""
  }
}

字段含义一眼能看懂：公历日期、星期、农历、干支、节气、是否工作日、节日。真正要注意的是怎么用。

日期用公历传，本地化在客户端做

传参尽量只用 yyyy-MM-dd，别传「2026年10月21日」这种带中文的格式，很多接口会解析失败。传时间戳时要确认单位是秒还是毫秒，两者差一千倍，传错会得到 1970 年的结果。

一周的数据怎么拉

做周历、月历需要一次拿多天。两种方式：一种是接口支持 start 和 end 参数，一次返回区间；另一种是按天循环调用，再拼成数组。前者省请求，后者更兼容老接口。批量拉的时候并发别太高，接口一般有频率限制。

四个容易出错的地方

• 时区：服务器在 UTC，客户端在东八区，用服务器时间判断「今天」会差八小时，节假日常常因此在凌晨出错。
• 农历闰月：闰月会让农历月份重名，字符串比较不可靠，最好改用数值编号或者接口给的原始字段。
• 工作日不等于周一至周五：有调休上班的周末，也有放假的工作日，一定要看 isWorkday 这个字段，别自己用星期推算。
• 节假日覆盖范围：很多免费接口只覆盖中国大陆的法定节假日，做港澳台或者海外业务要确认数据源范围。

缓存和更新

万年历数据几乎是静态的，唯一的变数是国务院每年发布的节假日安排。合理做法是把每天的日历结果缓存到本地数据库或者 Redis，按天失效，节假日更新后手动刷一次。这样既省接口调用，也不怕对方临时挂掉。

最后一句：选接口先看数据覆盖范围和支持的日期区间，再看价格，字段能不能对上自己的业务需求更重要。