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 说明、使用示例、架构设计
362 lines
8.1 KiB
Markdown
362 lines
8.1 KiB
Markdown
# Flask 数据服务实现总结
|
||
|
||
## 📦 已完成的组件
|
||
|
||
### 1. 核心服务 (flask_server.py)
|
||
**文件**: `core/datasource/flask_server.py` (541行)
|
||
|
||
**功能**:
|
||
- ✅ RESTful API 接口
|
||
- ✅ 支持8种资产类型
|
||
- ✅ 自动资产类型检测
|
||
- ✅ SSH 隧道集成
|
||
- ✅ 单只/批量数据获取
|
||
- ✅ 统一的 JSON 响应格式
|
||
- ✅ 完善的错误处理
|
||
|
||
**API 端点**:
|
||
```
|
||
GET / - API 信息
|
||
GET /health - 健康检查
|
||
GET /api/v1/asset-type - 检测资产类型
|
||
GET /api/v1/ohlcv - 获取K线数据
|
||
POST /api/v1/ohlcv/batch - 批量获取K线
|
||
GET /api/v1/supported-codes - 支持的代码示例
|
||
```
|
||
|
||
### 2. 启动脚本 (start_flask_server.sh)
|
||
**文件**: `start_flask_server.sh` (128行)
|
||
|
||
**功能**:
|
||
- ✅ 环境检查（Python、依赖、Token）
|
||
- ✅ SSH 私钥权限自动修复
|
||
- ✅ 命令行参数解析
|
||
- ✅ 彩色输出提示
|
||
- ✅ 帮助文档
|
||
|
||
**用法**:
|
||
```bash
|
||
./start_flask_server.sh # 基础启动
|
||
./start_flask_server.sh --with-ssh # 启用SSH隧道
|
||
./start_flask_server.sh --port 8080 # 指定端口
|
||
./start_flask_server.sh --debug # 调试模式
|
||
```
|
||
|
||
### 3. Python 客户端 (flask_api_client.py)
|
||
**文件**: `examples/flask_api_client.py` (299行)
|
||
|
||
**功能**:
|
||
- ✅ DataFetcherClient 类封装
|
||
- ✅ 健康检查
|
||
- ✅ 资产类型检测
|
||
- ✅ 单只/批量数据获取
|
||
- ✅ 命令行调用示例
|
||
- ✅ DataFrame 转换示例
|
||
|
||
**使用**:
|
||
```python
|
||
from examples.flask_api_client import DataFetcherClient
|
||
|
||
client = DataFetcherClient("http://localhost:5000")
|
||
|
||
# 获取单只标的
|
||
data = client.get_ohlcv("000300.SH", "2024-01-01", "2024-03-31")
|
||
|
||
# 批量获取
|
||
results = client.batch_ohlcv(
|
||
["000300.SH", "NDX", "HSI"],
|
||
"2024-01-01",
|
||
"2024-03-31"
|
||
)
|
||
```
|
||
|
||
### 4. API 文档 (flask_api_README.md)
|
||
**文件**: `docs/flask_api_README.md` (405行)
|
||
|
||
**内容**:
|
||
- ✅ 快速开始指南
|
||
- ✅ 完整的 API 端点文档
|
||
- ✅ 请求/响应示例
|
||
- ✅ 错误处理说明
|
||
- ✅ Python 客户端示例
|
||
- ✅ 环境配置指南
|
||
|
||
### 5. API 测试脚本 (test_flask_api.py)
|
||
**文件**: `tests/test_flask_api.py` (141行)
|
||
|
||
**功能**:
|
||
- ✅ 健康检查测试
|
||
- ✅ 首页信息测试
|
||
- ✅ 资产类型检测测试
|
||
- ✅ K线数据获取测试
|
||
- ✅ 批量获取测试
|
||
- ✅ 支持的代码测试
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 启动服务
|
||
|
||
```bash
|
||
# 进入项目目录
|
||
cd /Users/aszer/Documents/vscode/etf
|
||
|
||
# 启动服务（仅A股）
|
||
./start_flask_server.sh
|
||
|
||
# 或启动服务（支持港美股，需要SSH隧道）
|
||
./start_flask_server.sh --with-ssh
|
||
```
|
||
|
||
### 2. 测试 API
|
||
|
||
```bash
|
||
# 健康检查
|
||
curl http://localhost:5000/health
|
||
|
||
# 获取沪深300数据
|
||
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"
|
||
}'
|
||
```
|
||
|
||
### 3. Python 调用
|
||
|
||
```python
|
||
import requests
|
||
|
||
# 获取数据
|
||
response = requests.get(
|
||
'http://localhost:5000/api/v1/ohlcv',
|
||
params={
|
||
'code': '000300.SH',
|
||
'start': '2024-01-01',
|
||
'end': '2024-03-31'
|
||
}
|
||
)
|
||
data = response.json()
|
||
|
||
print(f"获取到 {data['count']} 条数据")
|
||
for item in data['data'][:3]:
|
||
print(f"{item['date']}: 开盘 {item['open']}, 收盘 {item['close']}")
|
||
```
|
||
|
||
## 📊 API 响应示例
|
||
|
||
### 单只标的响应
|
||
|
||
```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"]
|
||
}
|
||
```
|
||
|
||
### 批量获取响应
|
||
|
||
```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": {...}
|
||
}
|
||
},
|
||
"success_count": 2,
|
||
"failed_count": 0,
|
||
"total": 2,
|
||
"start": "2024-01-01",
|
||
"end": "2024-03-31"
|
||
}
|
||
```
|
||
|
||
## 🔧 配置说明
|
||
|
||
### 环境变量
|
||
|
||
```bash
|
||
# 必需
|
||
export TUSHARE_TOKEN=your_token_here
|
||
|
||
# 可选（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_TOKEN=your_token_here
|
||
|
||
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
|
||
```
|
||
|
||
## 📁 文件结构
|
||
|
||
```
|
||
etf/
|
||
├── core/datasource/
|
||
│ ├── flask_server.py # Flask API 服务 (541行)
|
||
│ ├── universal_fetcher.py # 统一数据获取器 (441行)
|
||
│ ├── hybrid_source.py # 混合数据源
|
||
│ └── __init__.py # 模块导出
|
||
├── examples/
|
||
│ ├── flask_api_client.py # Python 客户端 (299行)
|
||
│ └── universal_fetcher_examples.py
|
||
├── tests/
|
||
│ ├── test_flask_api.py # API 测试 (141行)
|
||
│ ├── test_universal_fetcher.py
|
||
│ └── test_ssh_tunnel.py
|
||
├── docs/
|
||
│ ├── flask_api_README.md # API 文档 (405行)
|
||
│ ├── universal_fetcher_README.md
|
||
│ └── ...
|
||
├── start_flask_server.sh # 启动脚本 (128行)
|
||
└── hk_ecs.pem # SSH 私钥
|
||
```
|
||
|
||
## 🎯 支持的资产类型
|
||
|
||
| 类型 | 代码示例 | 数据源 | 需要SSH |
|
||
|------|---------|--------|---------|
|
||
| A股指数 | 000300.SH | Tushare | 否 |
|
||
| A股ETF | 510300.SH | Tushare | 否 |
|
||
| A股股票 | 600000.SH | Tushare | 否 |
|
||
| 港股指数 | HSI | YFinance | 是 |
|
||
| 美股指数 | NDX | YFinance | 是 |
|
||
| 美股股票 | AAPL | YFinance | 是 |
|
||
| 期货 | AU.SHF | Tushare | 否 |
|
||
| 加密货币 | BTC | CCXT | 是 |
|
||
|
||
## 📝 注意事项
|
||
|
||
1. **Tushare Token**: 获取A股数据必需
|
||
2. **SSH 隧道**: 获取港美股/加密货币需要
|
||
3. **私钥权限**: 自动修复为 600
|
||
4. **网络环境**: 中国大陆直接访问 YFinance 受限
|
||
5. **日期格式**: 统一使用 YYYY-MM-DD
|
||
|
||
## 🔄 与现有代码的关系
|
||
|
||
```
|
||
现有代码:
|
||
UniversalDataFetcher
|
||
└─ HybridDataSource
|
||
├─ Tushare (A股)
|
||
├─ YFinance (港美股) - 需要SSH
|
||
└─ CCXT (加密货币) - 需要SSH
|
||
|
||
新增代码:
|
||
Flask API Server
|
||
└─ UniversalDataFetcher
|
||
└─ ... (同上)
|
||
|
||
客户端:
|
||
DataFetcherClient
|
||
└─ HTTP requests
|
||
└─ Flask API Server
|
||
```
|
||
|
||
## ✅ 功能清单
|
||
|
||
### API 功能
|
||
- [x] 健康检查
|
||
- [x] 资产类型检测
|
||
- [x] 单只标的K线获取
|
||
- [x] 批量标的K线获取
|
||
- [x] 支持的代码列表
|
||
- [x] 统一的JSON响应
|
||
- [x] 错误处理
|
||
- [x] CORS支持
|
||
|
||
### 部署功能
|
||
- [x] 环境检查
|
||
- [x] 依赖安装
|
||
- [x] SSH配置
|
||
- [x] 命令行参数
|
||
- [x] 彩色输出
|
||
- [x] 帮助文档
|
||
|
||
### 客户端功能
|
||
- [x] Python客户端类
|
||
- [x] 健康检查
|
||
- [x] 资产检测
|
||
- [x] 数据获取
|
||
- [x] 批量获取
|
||
- [x] DataFrame转换
|
||
|
||
## 🚀 下一步建议
|
||
|
||
1. **添加认证**: API Key 或 JWT 认证
|
||
2. **添加限流**: 防止滥用
|
||
3. **添加缓存**: Redis 缓存常用数据
|
||
4. **添加日志**: 请求日志和错误日志
|
||
5. **Docker部署**: 容器化部署
|
||
6. **监控告警**: 服务健康监控
|
||
|
||
## 📞 使用帮助
|
||
|
||
启动服务后访问:
|
||
- API 文档: http://localhost:5000/
|
||
- 健康检查: http://localhost:5000/health
|
||
|
||
查看详细文档:
|
||
- [API 文档](./flask_api_README.md)
|
||
- [客户端示例](../examples/flask_api_client.py)
|
||
|
||
## 🎉 总结
|
||
|
||
Flask 数据服务已经完全实现，提供了：
|
||
|
||
✅ **RESTful API** - 统一的 HTTP 接口
|
||
✅ **自动资产识别** - 智能路由到正确数据源
|
||
✅ **SSH 隧道支持** - 自动管理代理连接
|
||
✅ **批量获取** - 高效的多标的数据获取
|
||
✅ **完整文档** - API 文档和客户端示例
|
||
✅ **易于部署** - 一键启动脚本
|
||
|
||
现在可以通过 HTTP API 获取任何支持的资产数据了！
|