9.4 KiB

Raw Blame History Unescape Escape

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

统一数据获取接口开发文档

1. 概述

本开发文档描述了AlphaFutures系统中统一数据获取接口的设计与实现。该接口采用适配器设计模式，支持多种数据源（TQSDK、RQData等），为系统提供统一的数据获取出口，实现业务逻辑与数据获取的解耦。

1.1 设计目标

统一接口：为所有数据源提供一致的API接口
可扩展性：支持轻松添加新的数据源适配器
配置灵活：通过配置选择不同的数据源
容错处理：包含错误处理和降级机制
模拟数据：支持无账号时的模拟数据功能

1.2 技术栈

Python 3.8+
抽象基类（ABC）
工厂模式
依赖注入
环境变量配置

2. 架构设计

2.1 整体架构

业务逻辑层
    ↑
    | 依赖注入
    ↓
统一数据获取层 (DataFetcher)
    ↑
    | 工厂模式
    ↓
适配器抽象层 (BaseDataAdapter)
    ↑
    | 继承实现
    ↓
具体适配器实现
├── TQSdkAdapter
├── RQDataAdapter
└── 其他适配器...

2.2 核心设计模式

适配器模式：将不同数据源的接口转换为统一接口
工厂模式：根据配置创建对应的适配器实例
依赖注入：业务逻辑通过统一接口获取数据，不直接依赖具体实现

3. 核心组件

3.1 抽象基类 (BaseDataAdapter)

定义了所有数据适配器必须实现的接口方法，确保一致性。

文件路径：qihuo_analyzer/data/api_adapters/base_adapter.py

核心方法：

connect() - 连接数据源
disconnect() - 断开连接
get_kline_data() - 获取K线数据
get_tick_data() - 获取tick数据
get_contract_info() - 获取合约信息
get_market_data() - 获取市场数据
get_all_symbols() - 获取所有品种列表

3.2 具体适配器

3.2.1 TQSDK适配器

文件路径：qihuo_analyzer/data/api_adapters/tqsdk_adapter.py

实现了TQSDK的所有接口方法，包含错误处理和模拟数据支持。

3.2.2 RQData适配器

文件路径：qihuo_analyzer/data/api_adapters/rqdata_adapter.py

实现了RQData的所有接口方法，包含错误处理和模拟数据支持。

3.3 适配器工厂

文件路径：qihuo_analyzer/data/api_adapters/adapter_factory.py

根据配置创建对应的适配器实例，支持通过环境变量选择数据源类型。

3.4 统一数据获取器

文件路径：qihuo_analyzer/data/data_fetcher.py

使用统一接口获取数据，替代直接API调用，为业务逻辑提供一致的数据获取方式。

4. 实现细节

4.1 配置管理

4.1.1 环境变量配置

环境变量	说明	默认值
DATA_ADAPTER_TYPE	数据适配器类型 (tqsdk/rqdata)	tqsdk
TQSDK_USERNAME	TQSDK账号	无
TQSDK_PASSWORD	TQSDK密码	无
RQDATA_USERNAME	RQData账号	无
RQDATA_PASSWORD	RQData密码	无

4.1.2 账号配置

TQSDK：设置TQSDK_USERNAME和TQSDK_PASSWORD环境变量
RQData：设置RQDATA_USERNAME和RQDATA_PASSWORD环境变量
未配置账号：自动使用模拟数据

4.2 错误处理

所有适配器都包含完整的错误处理机制：

连接错误：捕获连接异常，返回错误信息并使用模拟数据
数据获取错误：捕获API调用异常，返回错误信息并使用模拟数据
参数错误：验证输入参数，返回错误信息

4.3 模拟数据

当API连接失败或未配置账号时，自动使用模拟数据：

K线数据：生成随机波动的价格数据
Tick数据：生成随机的成交数据
合约信息：返回基本合约信息
市场数据：返回模拟的市场行情
品种列表：返回内置的品种列表

4.4 数据格式统一

所有适配器返回的数据格式保持一致：

K线数据：包含时间、开盘价、最高价、最低价、收盘价、成交量
Tick数据：包含时间、最新价、成交量、持仓量、买价、买量、卖价、卖量
合约信息：包含合约代码、交易所、品种类型、合约大小等
市场数据：包含最新价、涨跌幅、成交量、持仓量等
品种列表：包含品种代码、交易所、品种名称等

5. 使用方法

5.1 基本使用

from qihuo_analyzer.data.data_fetcher import DataFetcher

# 创建数据获取器实例（自动使用配置的适配器）
fetcher = DataFetcher()

# 获取K线数据
kline_data = fetcher.get_kline_data(
    symbol="SHFE.rb2409",
    interval=3600,  # 1小时
    start_time="2024-01-01 00:00:00",
    end_time="2024-01-02 00:00:00"
)

# 获取Tick数据
tick_data = fetcher.get_tick_data(
    symbol="SHFE.rb2409",
    start_time="2024-01-01 09:00:00",
    end_time="2024-01-01 11:30:00"
)

# 获取合约信息
contract_info = fetcher.get_contract_info("SHFE.rb2409")

# 获取市场数据
market_data = fetcher.get_market_data(["SHFE.rb2409", "DCE.i2409"])

# 获取所有品种列表
symbols = fetcher.get_all_symbols()

5.2 手动指定适配器

from qihuo_analyzer.data.api_adapters.adapter_factory import DataAdapterFactory

# 手动创建特定适配器
adapter = DataAdapterFactory.create_adapter("rqdata")
adapter.connect()

# 使用适配器获取数据
data = adapter.get_kline_data("SHFE.rb2409", 3600, start_time, end_time)

# 断开连接
adapter.disconnect()

6. 配置说明

6.1 Windows环境变量配置

打开系统属性：右键"此电脑" → "属性" → "高级系统设置"
环境变量：点击"环境变量"按钮
添加系统变量：在"系统变量"区域点击"新建"
设置变量：
- 变量名：DATA_ADAPTER_TYPE
- 变量值：tqsdk 或 rqdata
设置账号变量（可选）：
- TQSDK：添加 TQSDK_USERNAME 和 TQSDK_PASSWORD
- RQData：添加 RQDATA_USERNAME 和 RQDATA_PASSWORD
重启应用：配置生效需要重启应用程序

6.2 临时配置

在Python代码中临时设置环境变量：

import os

# 设置适配器类型
os.environ["DATA_ADAPTER_TYPE"] = "rqdata"

# 设置RQData账号
os.environ["RQDATA_USERNAME"] = "your_username"
os.environ["RQDATA_PASSWORD"] = "your_password"

# 然后创建DataFetcher实例
from qihuo_analyzer.data.data_fetcher import DataFetcher
fetcher = DataFetcher()

7. 测试验证

7.1 测试脚本

文件路径：test_data_adapters.py

测试脚本验证了所有适配器的功能：

连接测试
数据获取测试
错误处理测试
模拟数据测试

7.2 运行测试

# 在项目根目录运行测试
python test_data_adapters.py

7.3 测试结果

测试输出示例：

=== 测试 tqsdk 适配器 ===
创建TQSDK数据适配器
连接API...
TQSDK账号密码未配置，将使用模拟数据
连接结果: 失败
API连接失败，跳过测试

=== 测试 rqdata 适配器 ===
创建RQData数据适配器
连接API...
RQData账号密码未配置，将使用模拟数据
连接结果: 失败
API连接失败，跳过测试

=== 测试完成 ===

8. 未来扩展

8.1 添加新适配器

要添加新的数据源适配器，只需：

创建适配器类：继承BaseDataAdapter
实现接口方法：实现所有抽象方法
注册适配器：在工厂类中添加适配器类型

示例：

# 在adapter_factory.py中添加
ADAPTERS = {
    "tqsdk": TQSdkAdapter,
    "rqdata": RQDataAdapter,
    "new_adapter": NewAdapter  # 新适配器
}

8.2 增强功能

未来可考虑的增强功能：

缓存机制：添加数据缓存，减少重复API调用
多数据源融合：支持从多个数据源获取数据并融合
数据源健康检查：定期检查数据源可用性
数据质量监控：监控数据完整性和准确性
异步数据获取：支持异步API调用，提高性能

9. 故障排除

9.1 常见问题

API连接失败
- 检查账号配置是否正确
- 检查网络连接
- 检查API服务是否正常
数据获取失败
- 检查合约代码是否正确
- 检查时间范围是否合理
- 检查API权限是否足够
适配器初始化失败
- 检查环境变量配置
- 检查依赖包是否安装
- 检查Python版本是否兼容

9.2 日志与调试

日志级别：可通过配置调整日志级别
调试模式：设置环境变量DEBUG=True启用调试模式
错误信息：详细的错误信息会记录到日志中

10. 依赖管理

10.1 核心依赖

依赖包	版本	用途
tqsdk	^1.9.15	TQSDK数据源支持
rqdatac	^2.0.0	RQData数据源支持
pandas	^1.3.0	数据处理
numpy	^1.20.0	数值计算

10.2 安装依赖

# 安装依赖包
pip install -r requirements.txt

11. 总结

统一数据获取接口的实现成功解决了多数据源集成的问题，为AlphaFutures系统提供了：

灵活性：支持多种数据源，可根据需要切换
可靠性：包含错误处理和降级机制
可扩展性：支持轻松添加新的数据源
一致性：为业务逻辑提供统一的数据接口
可维护性：代码结构清晰，易于维护和测试

该设计不仅满足了当前的需求，也为未来的功能扩展和性能优化奠定了基础。

9.4 KiB Raw Blame History Unescape Escape