AlphaFuturesPro/docs/开发文档/合约数据获取逻辑.md

合约数据获取逻辑

核心流程

系统启动后，根据合约数据使用配置的数据源获取合约具体数据的整体逻辑如下：

1. 系统初始化：

   • 后端服务启动时加载配置文件（config.ts）
   • 注册市场相关API路由（market.ts）

2. 数据源管理：

   • 通过DataSourceFactory创建和管理数据源实例
   • 支持多种数据源类型：TQSDK（实盘数据）、测试数据源（模拟数据）

3. 数据获取流程：

   • 客户端请求市场数据时，marketService中的方法被调用
   • 方法首先检查数据源配置，确定使用哪个数据源
   • 尝试使用配置的数据源获取合约数据
   • 如果主数据源失败，自动切换到备用数据源
   • 处理数据并返回给客户端

4. 合约数据处理：

   • 使用预定义的合约列表（futuresList）作为基础
   • 为每个合约构建完整的合约符号（如SHFE.rb2505）
   • 调用数据源的方法获取实时行情、K线等数据
   • 转换数据格式为前端需要的结构

代码位置

数据源管理

• 数据源工厂：backend/src/services/datasource/DataSourceFactory.ts

  • 负责创建和管理数据源实例
  • 支持数据源的初始化、切换和关闭

• 数据源接口：backend/src/services/datasource/DataSource.ts

  • 定义了数据源必须实现的方法，如获取合约列表、合约详情、K线数据等

• TQSDK数据源实现：backend/src/services/datasource/TQDataSource.ts

  • 基于TQSDK库实现的实盘数据源
  • 提供获取合约数据的具体方法

数据服务

• 市场服务：backend/src/services/marketService.ts
  • 实现了获取市场概览、品种详情、K线数据等方法
  • 处理数据源的选择和切换逻辑
  • 提供数据转换和错误处理

API接口

• 市场API：backend/src/api/market.ts
  • 提供RESTful API接口，如/api/market/overview、/api/market/detail/:symbol等
  • 调用市场服务的方法获取数据并返回给客户端

配置管理

• 配置文件：backend/src/config/index.ts
  • 存储数据源配置信息，如TQSDK的启用状态和参数

数据源切换机制

系统实现了智能的数据源切换机制：

1. 优先使用配置的主数据源（如TQSDK）
2. 如果主数据源失败，自动尝试使用备用数据源（如测试数据源）
3. 如果所有数据源都不可用，返回友好的错误提示

数据获取示例

以获取市场概览为例：

1. 客户端请求 /api/market/overview
2. marketService.fetchMarketOverview() 被调用
3. 检查数据源配置，确定使用TQSDK还是测试数据源
4. 如果使用TQSDK，创建TQSDK数据源实例并初始化
5. 遍历合约列表，为每个合约构建完整符号
6. 调用数据源的 getTickData() 方法获取实时行情
7. 处理数据并返回给客户端
8. 如果TQSDK失败，自动切换到测试数据源

主力合约获取

核心流程

1. 主力合约获取机制：

   • 系统通过TQSDK的query_quotes()方法获取主力合约数据
   • 支持实盘数据和模拟数据两种模式
   • 实现了异常处理和超时机制，确保获取过程稳定

2. 数据处理：

   • 从TQSDK获取主力合约列表
   • 提取品种代码和对应的主力合约代码
   • 转换为主力合约映射表，便于查询

3. API接口：

   • 提供/api/main-contracts接口，返回主力合约数据
   • 接口返回格式包含品种代码、品种名称和主力合约代码

代码位置

• TQSDK适配器：backend/service_implementation/qihuo_analyzer/data/api_adapters/tqsdk_adapter.py

  • 实现了get_main_contracts()方法，使用TQSDK获取主力合约数据
  • 提供了模拟数据作为fallback

• 数据获取器：backend/service_implementation/qihuo_analyzer/data/data_fetcher.py

  • 实现了get_main_contracts()方法，作为适配器方法的包装
  • 提供了统一的主力合约获取接口

• API服务：backend/service_implementation/service/app.py

  • 添加了/api/main-contracts接口，返回主力合约数据
  • 处理数据格式转换和错误处理

使用方法

1. 通过API接口获取：

   GET http://localhost:5000/api/main-contracts
   

2. 在代码中获取：

   from qihuo_analyzer.data.data_fetcher import DataFetcher
   
   data_fetcher = DataFetcher()
   data_fetcher.connect()
   main_contracts = data_fetcher.get_main_contracts()
   print(main_contracts)  # 输出：{'AU': 'AU2603', 'AG': 'AG2603', ...}
   

技术实现细节

• TQSDK接口：使用query_quotes(ins_class='FUTURE')获取主力合约数据
• 数据处理：通过get_quote()获取合约详细信息，提取underlying_symbol和instrument_id
• 异常处理：实现了多层异常捕获，确保系统稳定性
• 模拟数据：当TQSDK不可用时，使用预定义的模拟数据

技术特点

1. 工厂模式：使用工厂模式管理数据源实例，提高代码可维护性
2. 接口隔离：通过接口定义数据源行为，便于扩展新的数据源类型
3. 容错机制：实现了数据源故障自动切换，提高系统可靠性
4. 配置驱动：数据源配置通过配置文件管理，便于运维和部署
5. 模块化设计：将数据获取逻辑与API接口分离，提高代码可读性
6. 主力合约支持：实现了主力合约的自动获取和管理，方便用户快速访问主要交易合约