StockDataAPI - 股票数据API服务

📖 项目简介

StockDataAPI 是一个高性能的股票数据API服务，提供实时股票价格查询功能。支持多数据源（天行API、腾讯、新浪），具备智能缓存、请求合并、限流控制等特性。

✨ 主要特性

• 🚀 高性能: 异步处理，支持高并发
• 🔄 智能API策略: A股使用天行API，港股使用沧海数据API
• 💾 智能缓存: Redis缓存，提升响应速度
• 🕐 定时更新: 每天凌晨2点自动更新股票名称缓存
• 🔀 请求合并: 自动合并相同请求，减少API调用
• 🛡️ 限流控制: 防止API调用超限
• 📊 实时数据: 交易时间实时更新
• 🔧 易于扩展: 模块化设计，便于功能扩展
• 🎯 成本优化: 大幅减少沧海API使用量
• 🔍 智能搜索: 支持股票代码、名称、拼音、拼音缩写搜索

🏗️ 架构设计

核心模块

• main.py: 主程序，处理HTTP请求
• tsanghi_api.py: 沧海数据API接口
• backup_api.py: 备用API（腾讯、新浪）
• tian_api.py: 天行API接口
• models.py: 数据模型定义
• constants.py: 常量管理
• utils.py: 工具类集合
• stock_search.py: 股票搜索索引模块

数据流

HTTP请求 → 请求合并 → 缓存检查 → 股票分类 → 分别调用API → 数据合并 → 响应返回

API调用策略

• A股（sh、sz、bj开头）: 天行API → 腾讯、新浪备用
• 港股（hk开头）: 沧海数据API → 天行、腾讯、新浪备用

🚀 快速开始

环境要求

• Python 3.8+
• Redis 服务器
• 天行API密钥
• 沧海数据API密钥（可选，推荐）

安装依赖

pip install -r requirements.txt

配置设置

编辑 config/config.yaml 文件：

environment: production  # 或 test
api_key: your_tianapi_key
api_key_test: your_test_key

# 沧海数据API密钥（推荐配置）
tsanghi_api_key: your_tsanghi_api_key
tsanghi_api_key_test: your_tsanghi_test_key

redis:
  host: localhost
  port: 6379
  db: 0
  max_connections: 10

server:
  host: 0.0.0.0
  port: 8000

启动服务

# 开发模式
python main.py

# 生产模式
gunicorn main:app -c gunicorn_conf.py

📡 API接口

获取股票价格

GET /get_stock_price/{stock_codes}

参数:

• stock_codes: 股票代码，多个代码用逗号分隔

示例:

GET /get_stock_price/sh600001,sz000001,hk00700

响应:

{
  "request_id": "Request-123-abc123",
  "results": {
    "sh600001": {
      "source": "API",
      "data": "邯郸钢铁,10.200,10.200,10.500,10.800,10.150,10.490,10.510,100000,1050000,100,10.490,200,10.480,300,10.470,400,10.460,500,10.450,100,10.510,200,10.520,300,10.530,400,10.540,500,10.550,2025-07-23,10:30:00,00"
    }
  }
}

定时任务管理

GET /scheduler/status

获取定时任务状态

响应:

{
  "request_id": "Status-20250123-143000",
  "scheduler_status": {
    "status": "running",
    "next_run": "2025-01-24T02:00:00",
    "last_run": "2025-01-23T02:00:00"
  }
}

POST /scheduler/force_update

强制立即更新缓存

响应:

{
  "request_id": "ForceUpdate-20250123-143000",
  "success": true,
  "message": "强制更新缓存完成"
}

股票搜索

GET /api/stock/search

股票搜索接口，支持代码、名称、拼音、拼音缩写搜索

参数:

• q: 搜索关键词（必填）
• limit: 返回结果数量限制（可选，默认10，最大50）
• fuzzy: 是否启用模糊搜索（可选，默认true）

示例:

GET /api/stock/search?q=中央商场&limit=5

响应:

{
  "request_id": "Search-20250726-152500",
  "query": "中央商场",
  "results": [
    {
      "code": "600280",
      "name": "中央商场",
      "exchange": "XSHG",
      "full_code": "sh600280",
      "pinyin": "zhongyangshangchang",
      "pinyin_abbr": "zysc",
      "match_type": "exact_name",
      "score": 1.0
    }
  ],
  "total": 1,
  "search_time": 0.015,
  "index_info": {
    "total_stocks": 5000,
    "last_refresh": "2025-07-26T15:00:05.893208",
    "exchanges": ["XSHG", "XSHE", "XHKG", "BJSE", "INDEX"]
  }
}

GET /api/stock/search/index

获取搜索索引信息

响应:

{
  "request_id": "IndexInfo-20250726-152500",
  "index_info": {
    "total_stocks": 5000,
    "last_refresh": "2025-07-26T15:00:05.893208",
    "exchanges": ["XSHG", "XSHE", "XHKG", "BJSE", "INDEX"]
  }
}

POST /api/stock/search/refresh

手动刷新搜索索引

响应:

{
  "request_id": "RefreshIndex-20250726-152500",
  "success": true,
  "message": "搜索索引刷新成功",
  "index_info": {
    "total_stocks": 5000,
    "last_refresh": "2025-07-26T15:00:05.893208",
    "exchanges": ["XSHG", "XSHE", "XHKG", "BJSE", "INDEX"]
  }
}

🔧 配置说明

环境配置

• environment: 运行环境（production/test）
• api_key: 天行API密钥
• api_key_test: 测试环境API密钥

Redis配置

• host: Redis服务器地址
• port: Redis端口
• db: 数据库编号
• max_connections: 最大连接数

服务器配置

• host: 监听地址
• port: 监听端口

API限制

• tianapi: 天行API限流配置
• tencent: 腾讯API限流配置
• sina: 新浪API限流配置

缓存配置

• trading_hours_cache: 交易时间缓存时间（秒）
• non_trading_hours_cache: 非交易时间缓存时间（秒）

📊 数据格式

股票数据字段

返回的CSV格式数据包含33个字段：

1. 股票名称
2. 开盘价
3. 昨收价
4. 当前价
5. 最高价
6. 最低价
7. 买一价
8. 卖一价
9. 成交量
10. 成交额 11-30. 买卖盘数据
11. 日期
12. 时间
13. 状态

支持的股票类型

• A股: 上海证券交易所（sh开头）、深圳证券交易所（sz开头）
• 港股: 香港交易所（hk开头）
• 指数: 上证指数、深证指数等

🛠️ 开发指南

项目结构

StockDataAPI/
├── main.py                    # 主程序
├── backup_api.py             # 备用API
├── tian_api.py               # 天行API
├── models.py                 # 数据模型
├── constants.py              # 常量定义
├── utils.py                  # 工具类
├── config.yaml               # 配置文件
├── requirements.txt           # 依赖文件
├── docs/                     # 文档目录
└── test_*.py                 # 测试文件

添加新功能

1. 新增数据源: 在 backup_api.py 中添加新接口
2. 新增字段: 在 models.py 中扩展 StockInfo 类
3. 新增常量: 在 constants.py 中添加配置
4. 新增工具: 在 utils.py 中添加工具方法

测试

# 运行所有测试
python test_models.py
python test_api_compatibility.py
python test_main_optimization.py

📈 性能优化

缓存策略

• 交易时间: 5秒缓存
• 非交易时间: 20分钟缓存
• Redis Pipeline: 批量操作

并发控制

• 请求合并: 相同请求自动合并
• 限流控制: 防止API调用超限
• 连接池: Redis连接复用

错误处理

• 自动重试: API调用失败自动重试
• 降级策略: 主API失败自动切换到备用API
• 数据验证: 自动清理损坏的缓存数据

🔍 监控和日志

日志级别

• DEBUG: 开发环境详细日志
• INFO: 一般信息日志
• WARNING: 警告信息
• ERROR: 错误信息

关键指标

• 请求响应时间
• 缓存命中率
• API调用成功率
• 并发请求数

🤝 贡献指南

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

📄 许可证

本项目采用 MIT 许可证。

📞 联系方式

如有问题或建议，请通过以下方式联系：

• 提交 Issue
• 发送邮件
• 项目讨论区

---

版本: v2.0.0
更新时间: 2025-07-23
兼容性: 100% 向后兼容
功能: 专注于股票实时信息查询