节假日查询：日历 / 日程应用如何集成？从数据到 UI 的全链路设计
# 节假日查询：日历 / 日程应用如何集成？从数据到 UI 的全链路设计
> 接口 894（894-4 / 894-6 / 894-7） · 免费 · POST/GET · 返回 JSON · 适用人群：日历/排班应用开发者 · 阅读时间：约 9 分钟
## TL;DR
- 数据层：894-4 拿全年放假 + 894-7 拿补班，合并成"日期 → 类型"映射表。
- 渲染层：用 `type`（894-6）或自建映射给日历格子上色（放假红 / 补班灰 / 普通蓝）。
- 更新层：数据一年变一次，缓存整年 + 次年预热，避免每次打开实时拉。
## Why：日历应用的刚需底座
任何带"中国节假日"的日历、排班、请假、考勤产品，都需要一份准确的放假/补班基准。自己维护容易过期出错，接入节假日查询等于把这部分甩给官方自营数据源。
## What：三个接入点怎么分工
| 接入点 | 用在哪一步 |
|--------|------|
| 894-4 假日列表 | 年初拉全年放假区间，生成"放假日集合" |
| 894-7 调休日列表 | 拉全年补班日，生成"补班日集合" |
| 894-6 单日判定 | 实时查"今天/某天"属性，或懒加载单日 |
## How：全链路实现
### 步骤 1：构建年度映射表
```python
def build_year_map(year, appkey):
holidays = get_year_holidays(year, appkey) # 894-4
makeup = get_makeup_days(year, appkey) # 894-7
day_type = {}
for h in holidays:
for d in daterange(h["begin"], h["end"]):
day_type[d] = "off" # 放假
for m in makeup:
day_type[m["begin"]] = "makeup" # 补班
return day_type
```
### 步骤 2：日历渲染着色
| 类型 | 颜色建议 | 含义 |
|------|------|------|
| off（放假） | 红 `#ffd6d6` | 法定节假日 |
| makeup（补班） | 灰 `#e8e8e8` | 调休上班 |
| normal | 白/蓝 | 普通工作日/周末 |
### 步骤 3：实时单日提示
```javascript
// 用户点开某天 → 894-6 实时判定（或先查本地映射，未命中再调接口）
async function dayInfo(day) {
const r = await fetch(`https://route.showapi.com/894-6?appKey=YOUR_APPKEY&day=${day}`,
{ method: "POST" });
const b = (await r.json()).showapi_res_body;
if (String(b.ret_code) !== "0") return null;
return { type: b.type, holiday: b.holiday }; // 1工作 2周末 3节假日
}
```
## 返回示例与解析
全年数据来自 894-4（`data[]` 含 begin/end/holiday/inverse_days），补班来自 894-7（`inverse_days[]` 含 name/begin/end）。两者合并即完整年度日历。字段细节见 [返回字段全解](https://www.showapi.com/guides/holiday-query-response-codes-894)。
## 进阶 / 边界
- **补班可能落在周末**：用接口返回的日期为准，别硬编码"补班=周日"。
- **2018 年前无数据**：历史回溯维护本地静态表，详见 [数据覆盖范围](https://www.showapi.com/guides/holiday-query-data-range-894)。
- **次年预热**：12 月预热下一年数据，元旦零冷启动，详见 [缓存策略](https://www.showapi.com/guides/holiday-query-cache-894)。
## FAQ
**Q1：只用一个接入点够吗？**
A：做全年日历建议 894-4 + 894-7 组合；只做"今天放不放假"用 894-6 即可。
**Q2：放假和补班会重叠吗？**
A：不会重叠，但补班日常是周末，渲染时注意优先级（补班灰优先于普通周末蓝）。
**Q3：数据多久更新一次？**
A：一年一次，国务院文件发布后一周内。
**Q4：免费够用吗？**
A：日历类应用调用量可控，配合缓存基本不会触档位上限；具体以官方档位说明为准。
**Q5：能离线吗？**
A：可把整年结果缓存到本地，离线读缓存，仅更新时联网。
## 相关能力 / 下一步阅读
- [节假日查询：一键生成全年放假日历，894-4 假日列表实战](https://www.showapi.com/guides/holiday-query-year-list-894)
- [节假日查询：调休上班日怎么算？894-7 调休日列表查询实战](https://www.showapi.com/guides/holiday-query-makeup-days-894)
- [节假日查询：免费接口也要省调用，节假日数据缓存策略设计](https://www.showapi.com/guides/holiday-query-cache-894)
- **本系列共 12 篇**：查看[节假日查询指南总目录](https://www.showapi.com/guides/holiday-query-guides-894)
