日历API集成功能说明

功能概述

get_calendar_by_date 函数现在具备了完整的智能查询功能：

优先查询数据库: 首先在本地 calendar_info 表中查找指定日期的黄历信息
自动API调用: 如果数据库中没有找到记录，自动调用外部API获取数据
数据持久化: 将API获取的数据自动保存到数据库中
统一返回格式: 无论数据来源如何，都返回标准化的JSON格式

工作流程

用户请求日期 → 查询数据库 → 找到数据？ → 是 → 返回数据
                    ↓
                  否
                    ↓
              调用外部API → 成功？ → 是 → 保存到数据库 → 返回数据
                    ↓
                  否
                    ↓
              返回错误信息

新增方法

CalendarService.fetch_calendar_from_api()

从聚合数据黄历API获取指定日期的黄历信息。

参数:

yangli_date (date): 阳历日期

返回:

Optional[dict]: API返回的黄历信息，失败时返回None

CalendarService.save_calendar_from_api()

将API返回的黄历信息保存到数据库。

参数:

api_data (dict): API返回的黄历信息数据

返回:

Optional[CalendarInfo]: 保存后的黄历信息对象，失败时返回None

配置文件

新增 calendar_config.py 配置文件，集中管理API相关配置：

CALENDAR_API_CONFIG = {
    'url': 'http://v.juhe.cn/laohuangli/d',
    'key': 'your-api-key-here',
    'timeout': 10,
    'retry_times': 3
}

API数据格式转换

外部API返回的数据格式与数据库字段的映射关系：

API字段	数据库字段	说明
`yangli`	`yangli`	阳历日期
`yinli`	`yinli`	阴历日期
`wuxing`	`wuxing`	五行
`chongsha`	`chongsha`	冲煞
`baiji`	`baiji`	彭祖百忌
`jishen`	`jishen`	吉神宜趋
`yi`	`yi`	宜
`xionshen`	`xiongshen`	凶神宜忌 (注意字段名差异)
`ji`	`ji`	忌

错误处理

函数包含完整的错误处理机制：

400: 日期格式错误
404: 数据库和API都没有找到数据
500: 系统内部错误（如API调用失败、数据库保存失败等）

使用示例

from app.core.data_parse.calendar import get_calendar_by_date

# 查询指定日期的黄历信息
result = get_calendar_by_date("2025-08-24")

if result['return_code'] == 200:
    calendar_data = result['result']
    print(f"阳历: {calendar_data['yangli']}")
    print(f"阴历: {calendar_data['yinli']}")
    print(f"宜: {calendar_data['yi']}")
    print(f"忌: {calendar_data['ji']}")
else:
    print(f"查询失败: {result['error']}")

注意事项

API密钥: 当前硬编码在配置文件中，生产环境建议使用环境变量
网络超时: API调用设置了10秒超时，可根据网络情况调整
数据一致性: API数据保存到数据库后，后续查询将直接从数据库返回
错误日志: 所有API调用和数据库操作的错误都会记录到控制台

测试

运行以下测试文件验证功能：

# 测试基本功能
python test_calendar_function.py

# 测试API集成功能
python test_calendar_api_integration.py

依赖要求

确保安装了以下Python包：

pip install requests sqlalchemy

CALENDAR_API_INTEGRATION_README.md 3.4 KB Historia Czysty