aszerW
0e531a1876
- universal_fetcher_README.md：统一数据获取接口完整文档 - universal_fetcher_QUICKSTART.md：5分钟快速上手指南 - universal_fetcher_ARCHITECTURE.md：架构设计说明 - universal_fetcher_TEST_REPORT.md：测试报告与修复记录 - flask_api_README.md：Flask API 完整文档 - FLASK_SERVICE_SUMMARY.md：项目实现总结 总计 2000+ 行文档，涵盖 API 说明、使用示例、架构设计
405 lines
7.8 KiB
Markdown
405 lines
7.8 KiB
Markdown
# Universal Data Fetcher API 文档
|
||
|
||
## 概述
|
||
|
||
提供统一的 RESTful API 接口，支持获取各类资产的 K 线数据（OHLCV）。
|
||
|
||
## 支持的资产类型
|
||
|
||
- **A股指数**: `000300.SH`, `399006.SZ`, `H30269.CSI`
|
||
- **A股ETF**: `510300.SH`, `159915.SZ`, `513100.SH`
|
||
- **A股股票**: `600000.SH`, `000001.SZ`
|
||
- **港股指数**: `HSI`, `HSTECH.HK`
|
||
- **美股指数**: `NDX`, `SPX`, `DJI`, `N225`, `GDAXI`
|
||
- **美股股票**: `AAPL`, `MSFT`, `GOOGL`, `AMZN`, `TSLA`
|
||
- **期货合约**: `AU.SHF`, `CU.SHF`
|
||
- **加密货币**: `BTC`, `ETH`
|
||
|
||
## 快速开始
|
||
|
||
### 1. 启动服务
|
||
|
||
```bash
|
||
# 基础启动（仅支持A股）
|
||
./start_flask_server.sh
|
||
|
||
# 启用 SSH 隧道（支持港美股）
|
||
./start_flask_server.sh --with-ssh
|
||
|
||
# 指定端口
|
||
./start_flask_server.sh --port 8080 --with-ssh
|
||
|
||
# 调试模式
|
||
./start_flask_server.sh --debug --with-ssh
|
||
```
|
||
|
||
### 2. 测试 API
|
||
|
||
```bash
|
||
# 健康检查
|
||
curl http://localhost:5000/health
|
||
|
||
# 获取K线数据
|
||
curl 'http://localhost:5000/api/v1/ohlcv?code=000300.SH&start=2024-01-01&end=2024-03-31'
|
||
|
||
# 批量获取
|
||
curl -X POST http://localhost:5000/api/v1/ohlcv/batch \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"codes": ["000300.SH", "NDX", "HSI"],
|
||
"start": "2024-01-01",
|
||
"end": "2024-03-31"
|
||
}'
|
||
```
|
||
|
||
## API 端点
|
||
|
||
### 1. 健康检查
|
||
|
||
```http
|
||
GET /health
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"status": "healthy",
|
||
"timestamp": "2024-01-15T10:30:00",
|
||
"ssh_configured": true
|
||
}
|
||
```
|
||
|
||
### 2. 检测资产类型
|
||
|
||
```http
|
||
GET /api/v1/asset-type?code={code}
|
||
```
|
||
|
||
**参数**:
|
||
- `code` (required): 标的代码
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"code": "000300.SH",
|
||
"asset_type": "china_index",
|
||
"description": "A股指数"
|
||
}
|
||
```
|
||
|
||
**示例**:
|
||
```bash
|
||
curl 'http://localhost:5000/api/v1/asset-type?code=000300.SH'
|
||
curl 'http://localhost:5000/api/v1/asset-type?code=NDX'
|
||
curl 'http://localhost:5000/api/v1/asset-type?code=BTC'
|
||
```
|
||
|
||
### 3. 获取K线数据
|
||
|
||
```http
|
||
GET /api/v1/ohlcv?code={code}&start={start}&end={end}&retry={retry}
|
||
```
|
||
|
||
**参数**:
|
||
- `code` (required): 标的代码
|
||
- `start` (optional): 开始日期，格式 `YYYY-MM-DD`，默认90天前
|
||
- `end` (optional): 结束日期，格式 `YYYY-MM-DD`，默认今天
|
||
- `retry` (optional): 重试次数，默认3
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"code": "000300.SH",
|
||
"asset_type": "china_index",
|
||
"data": [
|
||
{
|
||
"date": "2024-01-02",
|
||
"open": 3538.7244,
|
||
"high": 3542.9624,
|
||
"low": 3502.7866,
|
||
"close": 3502.7866,
|
||
"volume": 128626763.0,
|
||
"code": "000300.SH"
|
||
},
|
||
...
|
||
],
|
||
"count": 58,
|
||
"date_range": {
|
||
"start": "2024-01-02",
|
||
"end": "2024-03-29"
|
||
},
|
||
"columns": ["date", "open", "high", "low", "close", "volume", "code"]
|
||
}
|
||
```
|
||
|
||
**示例**:
|
||
```bash
|
||
# 获取沪深300指数
|
||
curl 'http://localhost:5000/api/v1/ohlcv?code=000300.SH&start=2024-01-01&end=2024-03-31'
|
||
|
||
# 获取纳斯达克100指数（需要SSH隧道）
|
||
curl 'http://localhost:5000/api/v1/ohlcv?code=NDX&start=2024-01-01&end=2024-03-31'
|
||
|
||
# 获取黄金期货
|
||
curl 'http://localhost:5000/api/v1/ohlcv?code=AU.SHF&start=2024-01-01&end=2024-03-31'
|
||
```
|
||
|
||
### 4. 批量获取K线数据
|
||
|
||
```http
|
||
POST /api/v1/ohlcv/batch
|
||
```
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"codes": ["000300.SH", "NDX", "HSI"],
|
||
"start": "2024-01-01",
|
||
"end": "2024-03-31",
|
||
"retry": 3
|
||
}
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"results": {
|
||
"000300.SH": {
|
||
"code": "000300.SH",
|
||
"asset_type": "china_index",
|
||
"data": [...],
|
||
"count": 58,
|
||
"date_range": {...}
|
||
},
|
||
"NDX": {
|
||
"code": "NDX",
|
||
"asset_type": "us_index",
|
||
"data": [...],
|
||
"count": 61,
|
||
"date_range": {...}
|
||
},
|
||
"HSI": {
|
||
"code": "HSI",
|
||
"asset_type": "hk_index",
|
||
"error": "No data available",
|
||
"data": [],
|
||
"count": 0
|
||
}
|
||
},
|
||
"success_count": 2,
|
||
"failed_count": 1,
|
||
"total": 3,
|
||
"start": "2024-01-01",
|
||
"end": "2024-03-31"
|
||
}
|
||
```
|
||
|
||
**示例**:
|
||
```bash
|
||
curl -X POST http://localhost:5000/api/v1/ohlcv/batch \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"codes": ["000300.SH", "510300.SH", "NDX", "HSI", "AU.SHF"],
|
||
"start": "2024-01-01",
|
||
"end": "2024-03-31"
|
||
}'
|
||
```
|
||
|
||
### 5. 获取支持的代码示例
|
||
|
||
```http
|
||
GET /api/v1/supported-codes
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"china_index": {
|
||
"description": "A股指数",
|
||
"examples": ["000300.SH", "399006.SZ", "000016.SH", "H30269.CSI"]
|
||
},
|
||
"china_etf": {
|
||
"description": "A股ETF",
|
||
"examples": ["510300.SH", "159915.SZ", "510500.SH", "513100.SH"]
|
||
},
|
||
...
|
||
}
|
||
```
|
||
|
||
## Python 客户端
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
pip install requests
|
||
```
|
||
|
||
### 使用示例
|
||
|
||
```python
|
||
import requests
|
||
|
||
# 基础配置
|
||
BASE_URL = "http://localhost:5000"
|
||
|
||
# 1. 健康检查
|
||
response = requests.get(f"{BASE_URL}/health")
|
||
print(response.json())
|
||
|
||
# 2. 获取单只标的
|
||
def get_ohlcv(code, start, end):
|
||
response = requests.get(
|
||
f"{BASE_URL}/api/v1/ohlcv",
|
||
params={"code": code, "start": start, "end": end}
|
||
)
|
||
return response.json()
|
||
|
||
# 获取沪深300
|
||
data = get_ohlcv("000300.SH", "2024-01-01", "2024-03-31")
|
||
print(f"获取到 {data['count']} 条数据")
|
||
|
||
# 3. 批量获取
|
||
def batch_ohlcv(codes, start, end):
|
||
response = requests.post(
|
||
f"{BASE_URL}/api/v1/ohlcv/batch",
|
||
json={"codes": codes, "start": start, "end": end}
|
||
)
|
||
return response.json()
|
||
|
||
# 批量获取
|
||
results = batch_ohlcv(
|
||
["000300.SH", "NDX", "HSI"],
|
||
"2024-01-01",
|
||
"2024-03-31"
|
||
)
|
||
|
||
for code, result in results['results'].items():
|
||
if 'error' not in result:
|
||
print(f"✓ {code}: {result['count']} 条")
|
||
else:
|
||
print(f"✗ {code}: {result['error']}")
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
### 错误响应格式
|
||
|
||
```json
|
||
{
|
||
"error": "错误描述",
|
||
"code": "000300.SH",
|
||
"start": "2024-01-01",
|
||
"end": "2024-03-31"
|
||
}
|
||
```
|
||
|
||
### 常见错误码
|
||
|
||
| HTTP 状态码 | 说明 | 解决方案 |
|
||
|------------|------|---------|
|
||
| 400 | 参数错误 | 检查请求参数格式 |
|
||
| 404 | 数据不存在 | 检查代码是否正确，日期范围是否合理 |
|
||
| 500 | 服务器内部错误 | 查看服务器日志 |
|
||
|
||
### 常见错误
|
||
|
||
**1. 代码不存在**
|
||
```json
|
||
{
|
||
"error": "No data available for the specified code and date range",
|
||
"code": "INVALID",
|
||
"start": "2024-01-01",
|
||
"end": "2024-03-31"
|
||
}
|
||
```
|
||
|
||
**2. 日期格式错误**
|
||
```json
|
||
{
|
||
"error": "Invalid date format. Use YYYY-MM-DD",
|
||
"start": "2024-01-01",
|
||
"end": "2024/03/31"
|
||
}
|
||
```
|
||
|
||
**3. 缺少必需参数**
|
||
```json
|
||
{
|
||
"error": "Missing required parameter: code",
|
||
"example": "/api/v1/ohlcv?code=000300.SH&start=2024-01-01&end=2024-03-31"
|
||
}
|
||
```
|
||
|
||
## 环境配置
|
||
|
||
### 必需环境变量
|
||
|
||
```bash
|
||
# Tushare Token（获取A股数据必需）
|
||
export TUSHARE_TOKEN=your_token_here
|
||
```
|
||
|
||
### 可选环境变量（SSH隧道）
|
||
|
||
```bash
|
||
# 启用 SSH 隧道（支持港美股）
|
||
export SSH_ENABLED=true
|
||
export SSH_HOST=8.218.167.69
|
||
export SSH_PORT=22
|
||
export SSH_USERNAME=root
|
||
export SSH_KEY_PATH=hk_ecs.pem
|
||
export SSH_LOCAL_PORT=1080
|
||
```
|
||
|
||
### .env 文件示例
|
||
|
||
```env
|
||
# Tushare
|
||
TUSHARE_TOKEN=your_tushare_token_here
|
||
|
||
# SSH 隧道（可选）
|
||
SSH_ENABLED=true
|
||
SSH_HOST=8.218.167.69
|
||
SSH_PORT=22
|
||
SSH_USERNAME=root
|
||
SSH_KEY_PATH=hk_ecs.pem
|
||
SSH_LOCAL_PORT=1080
|
||
```
|
||
|
||
## 性能说明
|
||
|
||
### 响应时间
|
||
|
||
- A股数据: ~500ms/只
|
||
- 港美股数据: ~1-2s/只（通过SSH隧道）
|
||
- 批量获取: 并发处理，总体时间取决于最慢的数据源
|
||
|
||
### 限流说明
|
||
|
||
- Tushare: 受 API 频率限制
|
||
- YFinance: 建议添加延迟避免限流
|
||
- 批量获取: 自动添加 0.5s 延迟
|
||
|
||
## 注意事项
|
||
|
||
1. **SSH 隧道**: 获取港美股数据需要配置 SSH 隧道
|
||
2. **Tushare Token**: 获取A股数据需要有效的 Tushare Token
|
||
3. **日期范围**: 建议单次查询不超过 1 年数据
|
||
4. **网络环境**: 中国大陆直接访问 YFinance 可能受限
|
||
|
||
## 示例代码
|
||
|
||
查看完整示例:
|
||
- [Python 客户端](../examples/flask_api_client.py)
|
||
- [API 测试](../tests/test_flask_api.py)
|
||
|
||
## 更新日志
|
||
|
||
### v1.0.0 (2024-XX-XX)
|
||
|
||
- 初始版本
|
||
- 支持8种资产类型
|
||
- RESTful API 接口
|
||
- Python 客户端
|
||
- SSH 隧道支持
|