CALENDAR_API_ROUTE_README.md 6.8 KB
日历API路由接口说明
接口概述
新增的 get-calendar-info API接口用于获取指定日期的黄历信息，支持智能查询：优先从数据库查询，未找到时自动调用外部API获取数据并保存到数据库。
接口详情
基本信息
- 接口名称:
get-calendar-info - 请求方法:
GET - 接口路径:
/api/data_parse/get-calendar-info - 功能描述: 获取指定日期的黄历信息
请求参数
| 参数名 | 类型 | 必填 | 格式 | 说明 |
|---|---|---|---|---|
| date | string | 是 | YYYY-MM-DD | 查询日期，如：2025-01-19 |
请求示例
# 使用curl
curl -X GET "http://localhost:5000/api/data_parse/get-calendar-info?date=2025-01-19"
# 使用浏览器
GET http://localhost:5000/api/data_parse/get-calendar-info?date=2025-01-19
响应格式
成功响应 (200)
{
"reason": "successed",
"return_code": 200,
"result": {
"id": "1657",
"yangli": "2014-09-11",
"yinli": "甲午(马)年八月十八",
"wuxing": "井泉水 建执位",
"chongsha": "冲兔(己卯)煞东",
"baiji": "乙不栽植千株不长 酉不宴客醉坐颠狂",
"jishen": "官日 六仪 益後 月德合 除神 玉堂 鸣犬",
"yi": "祭祀 出行 扫舍 馀事勿取",
"xiongshen": "月建 小时 土府 月刑 厌对 招摇 五离",
"ji": "诸事不宜"
}
}
错误响应
参数缺失 (400)
{
"reason": "failed",
"return_code": 400,
"result": null,
"error": "缺少必填参数: date"
}
日期格式错误 (400)
{
"reason": "failed",
"return_code": 400,
"result": null,
"error": "日期格式错误，请使用YYYY-MM-DD格式"
}
数据未找到 (404)
{
"reason": "failed",
"return_code": 404,
"result": null,
"error": "未找到日期 2025-01-19 的黄历信息，且API获取失败"
}
服务器错误 (500)
{
"reason": "failed",
"return_code": 500,
"result": null,
"error": "查询过程中发生错误: 具体错误信息"
}
响应字段说明
成功响应字段
| 字段名 | 类型 | 说明 |
|---|---|---|
| reason | string | 操作结果描述，"successed"表示成功 |
| return_code | integer | HTTP状态码，200表示成功 |
| result | object | 黄历信息数据对象 |
黄历信息字段 (result)
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | string | 记录ID |
| yangli | string | 阳历 |
| yinli | string | 阴历 |
| wuxing | string | 五行 |
| chongsha | string | 冲煞 |
| baiji | string | 彭祖百忌 |
| jishen | string | 吉神宜趋 |
| yi | string | 宜 |
| xiongshen | string | 凶神宜忌 |
| ji | string | 忌 |
错误响应字段
| 字段名 | 类型 | 说明 |
|---|---|---|
| reason | string | 操作结果描述，"failed"表示失败 |
| return_code | integer | HTTP状态码 |
| result | null | 失败时为null |
| error | string | 错误描述信息 |
业务逻辑
查询流程
- 参数验证: 检查date参数是否存在且格式正确
- 数据库查询: 在
calendar_info表中查找指定日期的记录 - API调用: 如果数据库中没有找到，自动调用外部黄历API
- 数据保存: 将API获取的数据保存到数据库
- 结果返回: 返回标准化的JSON响应
智能查询特性
- 优先本地: 首先查询本地数据库，响应速度快
- 自动补充: 数据库缺失时自动从API获取
- 数据持久化: API数据自动保存，避免重复调用
- 统一格式: 无论数据来源如何，都返回相同格式
错误处理
HTTP状态码
| 状态码 | 说明 |
|---|---|
| 200 | 查询成功 |
| 400 | 请求参数错误 |
| 404 | 数据未找到 |
| 500 | 服务器内部错误 |
错误类型
- 参数错误: 缺少date参数或格式不正确
- 数据缺失: 指定日期在数据库和API中都没有数据
- API错误: 外部API调用失败
- 系统错误: 数据库操作异常等
使用示例
Python示例
import requests
# 查询指定日期的黄历信息
url = "http://localhost:5000/api/data_parse/get-calendar-info"
params = {"date": "2025-01-19"}
response = requests.get(url, params=params)
if response.status_code == 200:
data = response.json()
if data['return_code'] == 200:
calendar_info = data['result']
print(f"阳历: {calendar_info['yangli']}")
print(f"阴历: {calendar_info['yinli']}")
print(f"宜: {calendar_info['yi']}")
print(f"忌: {calendar_info['ji']}")
else:
print(f"查询失败: {data['error']}")
else:
print(f"HTTP请求失败: {response.status_code}")
JavaScript示例
// 查询指定日期的黄历信息
async function getCalendarInfo(date) {
try {
const response = await fetch(`/api/data_parse/get-calendar-info?date=${date}`);
const data = await response.json();
if (data.return_code === 200) {
const calendarInfo = data.result;
console.log(`阳历: ${calendarInfo.yangli}`);
console.log(`阴历: ${calendarInfo.yinli}`);
console.log(`宜: ${calendarInfo.yi}`);
console.log(`忌: ${calendarInfo.ji}`);
return calendarInfo;
} else {
console.error(`查询失败: ${data.error}`);
return null;
}
} catch (error) {
console.error('请求失败:', error);
return null;
}
}
// 使用示例
getCalendarInfo('2025-01-19');
测试
测试文件
运行以下测试文件验证接口功能：
# 测试API路由接口
python test_calendar_api_route.py
测试用例
- 有效日期: 测试正常日期查询
- 无效格式: 测试错误日期格式
- 参数缺失: 测试缺少date参数
- 空参数: 测试空字符串参数
注意事项
- 日期格式: 必须使用YYYY-MM-DD格式，如2025-01-19
- API密钥: 外部API调用需要有效的API密钥
- 网络超时: API调用设置了超时时间，网络不稳定可能影响结果
- 数据一致性: API数据保存到数据库后，后续查询将直接从数据库返回
- 错误日志: 所有操作都会记录详细日志，便于问题排查
依赖要求
确保安装了以下Python包：
pip install flask requests sqlalchemy
部署说明
- 确保Flask应用正在运行
- 检查数据库连接配置
- 验证外部API密钥有效性
- 测试接口可访问性
更新日志
- v1.0.0: 初始版本，支持基本的黄历信息查询
- v1.1.0: 新增API集成功能，支持自动数据补充
- v1.2.0: 新增路由接口，支持HTTP GET请求