صفحهٔ اصلی گشت‌و‌گذار راهنما
ورود
mxl_citu
/
DataOps-platform
1
0
انشعاب 0
پرونده‌ها مشکلات 0 درخواست واکشی 0 ویکی
درخت: 6ed55e5bf7
شاخه‌ها تگ‌ها
DataOps-plat...
/
CALENDAR_API_ROUTE_README.md

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 错误描述信息

业务逻辑

查询流程

  1. 参数验证: 检查date参数是否存在且格式正确
  2. 数据库查询: 在calendar_info表中查找指定日期的记录
  3. API调用: 如果数据库中没有找到，自动调用外部黄历API
  4. 数据保存: 将API获取的数据保存到数据库
  5. 结果返回: 返回标准化的JSON响应

智能查询特性

  • 优先本地: 首先查询本地数据库，响应速度快
  • 自动补充: 数据库缺失时自动从API获取
  • 数据持久化: API数据自动保存，避免重复调用
  • 统一格式: 无论数据来源如何，都返回相同格式

错误处理

HTTP状态码

状态码 说明
200 查询成功
400 请求参数错误
404 数据未找到
500 服务器内部错误

错误类型

  1. 参数错误: 缺少date参数或格式不正确
  2. 数据缺失: 指定日期在数据库和API中都没有数据
  3. API错误: 外部API调用失败
  4. 系统错误: 数据库操作异常等

使用示例

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

测试用例

  1. 有效日期: 测试正常日期查询
  2. 无效格式: 测试错误日期格式
  3. 参数缺失: 测试缺少date参数
  4. 空参数: 测试空字符串参数

注意事项

  1. 日期格式: 必须使用YYYY-MM-DD格式，如2025-01-19
  2. API密钥: 外部API调用需要有效的API密钥
  3. 网络超时: API调用设置了超时时间，网络不稳定可能影响结果
  4. 数据一致性: API数据保存到数据库后，后续查询将直接从数据库返回
  5. 错误日志: 所有操作都会记录详细日志，便于问题排查

依赖要求

确保安装了以下Python包：

pip install flask requests sqlalchemy

部署说明

  1. 确保Flask应用正在运行
  2. 检查数据库连接配置
  3. 验证外部API密钥有效性
  4. 测试接口可访问性

更新日志

  • v1.0.0: 初始版本，支持基本的黄历信息查询
  • v1.1.0: 新增API集成功能，支持自动数据补充
  • v1.2.0: 新增路由接口，支持HTTP GET请求