GitHub_Trending/ap/apihub中的节假日API：Nager.Date与Calendarific集成
项目地址: https://gitcode.com/GitHub_Trending/ap/apihub 在现代应用开发中，节假日API是提升用户体验的关键组件，尤其对于日程管理、电商促销和考勤系统等场景至关重要。本文将详细介绍如何在GitHub_Trending/ap/apihub项目中集成两大主流节假日API——Nager.Date与Calendarific，帮助开发者快速实现全球节假日查询功能。
项目基础架构
apihub作为一站式API学习平台，其模块化架构为第三方API集成提供了灵活支持。核心目录结构如下：
-
控制器层：src/controllers/public/
存放公共API处理逻辑，可参考现有实现如猫图API、随机用户API -
路由层：src/routes/public/
定义API访问端点，示例可参考书籍API路由 -
工具函数：src/utils/helpers.js
提供HTTP请求、数据格式化等通用能力，可复用现有ApiRequest类
Nager.Date集成实现
1. 创建控制器
在src/controllers/public/目录下新建holiday-nager.controllers.js：
const { ApiRequest } = require('../../utils/ApiRequest');
const { ApiResponse } = require('../../utils/ApiResponse');
const asyncHandler = require('../../utils/asyncHandler');
/**
* 获取指定国家的节假日
* @route GET /api/public/holidays/nager/{countryCode}/{year}
*/
const getNagerHolidays = asyncHandler(async (req, res) => {
const { countryCode, year } = req.params;
const apiUrl = `https://date.nager.at/api/v3/PublicHolidays/${year}/${countryCode}`;
const response = await ApiRequest.get(apiUrl);
return res.status(200).json(
new ApiResponse(200, response.data, 'Holidays fetched successfully')
);
});
module.exports = { getNagerHolidays };
2. 配置路由
在src/routes/public/目录下新建holiday.routes.js：
const express = require('express');
const router = express.Router();
const { getNagerHolidays } = require('../../controllers/public/holiday-nager.controllers');
router.get('/nager/:countryCode/:year', getNagerHolidays);
module.exports = router;
3. 注册路由
修改src/routes/index.js，添加新路由：
const holidayRoutes = require('./public/holiday.routes');
app.use('/api/public/holidays', holidayRoutes);
Calendarific集成实现
1. 创建控制器
在src/controllers/public/目录下新建holiday-calendarific.controllers.js：
const { ApiRequest } = require('../../utils/ApiRequest');
const { ApiResponse } = require('../../utils/ApiResponse');
const asyncHandler = require('../../utils/asyncHandler');
const { CALENDARIFIC_API_KEY } = process.env;
/**
* 获取多国家节假日对比
* @route GET /api/public/holidays/calendarific
*/
const getCalendarificHolidays = asyncHandler(async (req, res) => {
const { country, year } = req.query;
const apiUrl = 'https://calendarific.com/api/v2/holidays';
const response = await ApiRequest.get(apiUrl, {
params: {
api_key: CALENDARIFIC_API_KEY,
country,
year
}
});
return res.status(200).json(
new ApiResponse(200, response.data.response.holidays, 'Holidays fetched successfully')
);
});
module.exports = { getCalendarificHolidays };
2. 扩展路由配置
更新src/routes/public/holiday.routes.js：
const { getCalendarificHolidays } = require('../../controllers/public/holiday-calendarific.controllers');
// 添加新路由
router.get('/calendarific', getCalendarificHolidays);
功能测试与示例
测试用例
参考项目现有测试结构，在e2e/routes/public/目录下创建holidays.test.js：
const request = require('supertest');
const app = require('../../../src/app');
describe('Holiday API', () => {
test('GET /api/public/holidays/nager/US/2024 should return US holidays', async () => {
const res = await request(app)
.get('/api/public/holidays/nager/US/2024')
.expect(200);
expect(res.body.data).toBeInstanceOf(Array);
expect(res.body.data[0]).toHaveProperty('name');
});
});
前端集成示例
可参考examples/apps/todo/web/react-vite-tailwind/项目结构，实现节假日查询组件：
// src/components/HolidayChecker.tsx
import { useEffect, useState } from 'react';
import { fetchHolidays } from '../api/holidayApi';
export function HolidayChecker() {
const [holidays, setHolidays] = useState([]);
useEffect(() => {
fetchHolidays('CN', 2024).then(data => setHolidays(data));
}, []);
return (
<div className="p-4 bg-gray-50">
<h3 className="text-lg font-semibold">2024年中国节假日</h3>
<ul className="mt-2 space-y-2">
{holidays.map(holiday => (
<li key={holiday.date}>{holiday.name} - {holiday.date}</li>
))}
</ul>
</div>
);
}
部署与扩展建议
环境变量配置
在项目根目录创建.env文件：
# Calendarific API密钥
CALENDARIFIC_API_KEY=your_api_key_here
# API缓存配置
HOLIDAY_CACHE_TTL=86400000 # 24小时缓存
性能优化
- 启用缓存：使用src/middlewares/cache.middlewares.js缓存频繁查询结果
- 批量查询：参考src/controllers/public/stock.controllers.js实现批量国家节假日查询
- 错误处理：复用src/utils/ApiError.js统一错误处理机制
总结与扩展方向
本文实现的节假日API模块已纳入项目标准API架构，代码结构符合：
- 控制器：src/controllers/public/holiday-nager.controllers.js
- 路由：src/routes/public/holiday.routes.js
后续可扩展功能：
- 节假日提醒服务：集成src/socket/index.js实现实时推送
- 多语言支持：参考examples/apps/ecommerce/web/react-vite-redux-tailwind/src/i18n.ts
- 自定义节假日：结合src/models/实现用户自定义节假日管理
完整实现可参考项目贡献指南CONTRIBUTING.md，提交PR参与项目迭代。
注：图示为Unix创始人Ken Thompson，象征系统设计的简洁之道
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
