# 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 获取任何支持的资产数据了！