aszer/etf

Files

- 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 说明、使用示例、架构设计

2026-05-07 21:20:03 +08:00

8.1 KiB

Raw Blame History

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 私钥权限自动修复
✅ 命令行参数解析
✅ 彩色输出提示
✅ 帮助文档

用法:

./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 转换示例

使用:

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. 启动服务

# 进入项目目录
cd /Users/aszer/Documents/vscode/etf

# 启动服务（仅A股）
./start_flask_server.sh

# 或启动服务（支持港美股，需要SSH隧道）
./start_flask_server.sh --with-ssh

2. 测试 API

# 健康检查
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 调用

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 响应示例

单只标的响应

{
  "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"]
}

批量获取响应

{
  "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"
}

🔧 配置说明

环境变量

# 必需
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 文件

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	是

📝 注意事项

Tushare Token: 获取A股数据必需
SSH 隧道: 获取港美股/加密货币需要
私钥权限: 自动修复为 600
网络环境: 中国大陆直接访问 YFinance 受限
日期格式: 统一使用 YYYY-MM-DD

🔄 与现有代码的关系

现有代码:
  UniversalDataFetcher
    └─ HybridDataSource
         ├─ Tushare (A股)
         ├─ YFinance (港美股) - 需要SSH
         └─ CCXT (加密货币) - 需要SSH

新增代码:
  Flask API Server
    └─ UniversalDataFetcher
         └─ ... (同上)

客户端:
  DataFetcherClient
    └─ HTTP requests
         └─ Flask API Server

✅ 功能清单

API 功能

健康检查
资产类型检测
单只标的K线获取
批量标的K线获取
支持的代码列表
统一的JSON响应
错误处理
CORS支持

部署功能

环境检查
依赖安装
SSH配置
命令行参数
彩色输出
帮助文档

客户端功能

Python客户端类
健康检查
资产检测
数据获取
批量获取
DataFrame转换

🚀 下一步建议

添加认证: API Key 或 JWT 认证
添加限流: 防止滥用
添加缓存: Redis 缓存常用数据
添加日志: 请求日志和错误日志
Docker部署: 容器化部署
监控告警: 服务健康监控

📞 使用帮助

启动服务后访问:

API 文档: http://localhost:5000/
健康检查: http://localhost:5000/health

查看详细文档:

🎉 总结

Flask 数据服务已经完全实现，提供了：

✅ RESTful API - 统一的 HTTP 接口 ✅ 自动资产识别 - 智能路由到正确数据源 ✅ SSH 隧道支持 - 自动管理代理连接 ✅ 批量获取 - 高效的多标的数据获取 ✅ 完整文档 - API 文档和客户端示例 ✅ 易于部署 - 一键启动脚本

现在可以通过 HTTP API 获取任何支持的资产数据了！

8.1 KiB Raw Blame History Unescape Escape