AlphaFuturesPro/docs/开发文档/后端服务开发文档.md

后端服务开发文档

1. 项目结构

backend/
├── src/
│   ├── api/            # API路由
│   ├── config/         # 配置管理
│   ├── services/       # 业务服务
│   │   └── datasource/ # 数据源实现
│   ├── app.ts          # 应用入口
│   └── index.ts        # 导出模块
├── python_service/     # Python TQAPI服务
│   ├── api/            # Python API路由
│   ├── main.py         # Python服务入口
│   └── tqapi_service.py # TQAPI服务实现
├── config.json         # 配置文件
├── package.json        # Node.js依赖
└── tsconfig.json       # TypeScript配置

2. 核心功能

2.1 数据源管理

• TQDataSource：使用Python服务获取天勤量化数据
• MockDataSource：提供模拟数据，用于测试
• DataSourceFactory：数据源工厂，负责创建和管理数据源实例

2.2 Python TQAPI服务

• 功能：与天勤量化SDK交互，提供期货市场数据
• API端点：合约列表、合约详情、K线数据、Tick数据
• 端口配置：支持动态端口配置

2.3 集成服务

• 自动启动：当使用TQSDK数据源时，自动启动Python服务
• 端口同步：确保Python服务端口与Node.js连接端口一致

3. 关键修改

3.1 Python服务管理器修改

文件：backend/src/services/datasource/PythonServiceManager.ts

修改内容：

• 从配置中读取 pythonPort，默认8000
• 启动Python服务时传递端口参数
• 确保Python服务与Node.js服务端口一致

关键代码：

// 从配置中读取端口，默认8000
const port = config.dataSource?.tqsdk?.pythonPort || 8000;

// 启动Python服务，传递端口参数
this.pythonProcess = spawn('python', [pythonServicePath, '--port', port.toString()], {
  cwd: path.join(__dirname, '../../../python_service'),
  stdio: 'inherit',
  shell: true
});

3.2 Python服务入口修改

文件：backend/python_service/main.py

修改内容：

• 添加命令行参数解析
• 支持通过 --port 参数设置服务端口
• 默认端口为8000

关键代码：

# 解析命令行参数
parser = argparse.ArgumentParser(description="天勤量化 API 服务")
parser.add_argument("--port", type=int, default=8000, help="服务端口，默认8000")
parser.add_argument("--host", type=str, default="0.0.0.0", help="服务主机，默认0.0.0.0")
args = parser.parse_args()

# 启动服务
print(f"启动天勤量化 API 服务，监听 {args.host}:{args.port}")
uvicorn.run(app, host=args.host, port=args.port)

3.3 TQDataSource修改

文件：backend/src/services/datasource/TQDataSource.ts

修改内容：

• 从配置中读取 pythonPort，默认8000
• 动态构建Python服务URL，使用配置的端口
• 确保与Python服务端口一致

关键代码：

// 从配置中读取端口，默认8000
const port = config.pythonPort || 8000;
this.config = {
  // 其他配置...
  pythonServiceUrl: config.pythonServiceUrl || `http://127.0.0.1:${port}/api`
};

3.4 应用启动逻辑修改

文件：backend/src/app.ts

修改内容：

• 在启动时检查配置，自动启动Python服务
• 确保服务启动顺序正确

关键代码：

// 启动前检查是否需要启动Python TQAPI服务
async function startServer() {
  try {
    // 检查配置，是否使用TQSDK数据源
    if (config.dataSource?.defaultDataSource === 'tqsdk' || 
        (config.dataSource?.tqsdk && config.dataSource.tqsdk.enabled)) {
      console.log('检测到使用TQSDK数据源，准备启动Python服务...');
      const pythonStarted = await pythonServiceManager.start();
      if (!pythonStarted) {
        console.warn('Python服务启动失败，可能会影响TQSDK数据获取');
      }
    }

    // 启动Express服务器
    app.listen(port, () => {
      console.log(`服务器运行在 http://localhost:${port}`);
    });
  } catch (error) {
    console.error('启动服务器时出错:', error);
  }
}

4. 配置说明

4.1 配置文件结构

文件：config.json

{
  "server": {
    "port": 3007
  },
  "dataSource": {
    "tqsdk": {
      "enabled": true,
      "username": "你的天勤账号",
      "password": "你的天勤密码",
      "timeout": 30000,
      "retries": 3,
      "maxConnections": 5,
      "pythonPort": 8000
    },
    "defaultDataSource": "tqsdk"
  }
}

4.2 关键配置项

配置项	类型	默认值	说明
server.port	number	3007	Node.js服务端口
dataSource.tqsdk.enabled	boolean	true	是否启用TQSDK数据源
dataSource.tqsdk.username	string	""	天勤量化账号
dataSource.tqsdk.password	string	""	天勤量化密码
dataSource.tqsdk.pythonPort	number	8000	Python服务端口
dataSource.defaultDataSource	string	"tqsdk"	默认数据源

5. 启动方法

5.1 依赖安装

Node.js 依赖

在 backend 目录下执行：

npm install

Python 依赖

在 backend/python_service 目录下执行：

pip install -r requirements.txt

5.2 启动服务

方法一：使用启动脚本

执行 start_services.bat 脚本：

./start_services.bat

方法二：手动启动

1. 启动 Node.js 服务：

   cd backend
   npm run dev
   

2. 启动 Python 服务（自动启动，无需手动）：

   • 当使用TQSDK数据源时，Node.js服务会自动启动Python服务

5.3 服务验证

• Node.js 服务：访问 http://localhost:3007/health
• Python TQAPI 服务：访问 http://localhost:8000/health

6. 注意事项

6.1 端口配置

• 端口一致性：确保 config.json 中的 pythonPort 与 Python 服务实际使用的端口一致
• 端口冲突：避免使用已被其他程序占用的端口
• 默认端口：如果未配置 pythonPort，默认使用8000

6.2 依赖管理

• Python版本：建议使用 Python 3.7+
• Node.js版本：建议使用 Node.js 16+
• 依赖更新：定期更新依赖包，确保安全性和稳定性

6.3 数据源配置

• 天勤账号：确保天勤量化账号正确且已激活
• 网络连接：确保网络连接正常，能够访问天勤量化服务器
• 备用方案：当TQSDK数据源不可用时，可切换到MockDataSource

6.4 错误处理

• Python服务启动失败：检查Python是否安装，依赖是否完整
• TQSDK连接失败：检查网络连接，账号密码是否正确
• 数据获取失败：检查合约代码是否正确，网络连接是否稳定

6.5 性能优化

• 连接池：合理设置 maxConnections，避免连接过多
• 超时设置：设置合理的 timeout，避免请求等待时间过长
• 重试机制：通过 retries 配置，提高数据获取的可靠性

7. 故障排查

7.1 常见问题

问题1：Python服务启动失败

症状：

• Node.js服务启动时提示Python服务启动失败
• 日志显示Python相关错误

解决方案：

• 检查Python是否安装：python --version
• 检查Python依赖：pip install -r requirements.txt
• 检查端口是否被占用：netstat -ano | findstr :8000

问题2：TQSDK连接失败

症状：

• 日志显示"连接到天勤服务器失败"
• 数据获取API返回错误

解决方案：

• 检查天勤账号密码是否正确
• 检查网络连接是否正常
• 尝试手动登录天勤量化客户端，确认账号状态

问题3：端口不一致

症状：

• 日志显示"fetch failed"错误
• 提示连接到错误端口

解决方案：

• 检查 config.json 中的 pythonPort 配置
• 确保Python服务实际使用的端口与配置一致
• 重启服务，确保配置生效

7.2 日志查看

• Node.js日志：在启动Node.js服务的终端中查看
• Python日志：在启动Python服务的终端中查看
• API日志：通过访问API端点，查看返回结果和错误信息

8. 开发建议

8.1 代码规范

• TypeScript：使用TypeScript编写Node.js代码，提高代码质量
• ESLint：使用ESLint检查代码风格，确保代码一致性
• 注释：为关键代码添加注释，提高可维护性

8.2 测试策略

• 单元测试：为核心功能编写单元测试
• 集成测试：测试不同组件之间的集成
• Mock数据：使用MockDataSource进行测试，避免依赖外部服务

8.3 部署建议

• 环境变量：使用环境变量存储敏感信息
• 配置管理：使用配置文件管理不同环境的配置
• 监控告警：添加监控和告警机制，及时发现问题

8.4 扩展性

• 模块化：保持代码模块化，便于扩展和维护
• 接口设计：设计清晰的接口，便于添加新功能
• 数据源扩展：通过DataSourceFactory，可以方便地添加新的数据源实现

9. 总结

本开发文档提供了AI期货分析系统后端服务的详细说明，包括：

1. 项目结构：清晰的目录结构和文件组织
2. 核心功能：数据源管理、Python TQAPI服务和集成服务
3. 关键修改：端口配置、服务集成和启动逻辑
4. 配置说明：详细的配置项和默认值
5. 启动方法：多种启动方式和服务验证
6. 注意事项：端口配置、依赖管理和错误处理
7. 故障排查：常见问题和解决方案
8. 开发建议：代码规范、测试策略和部署建议

通过本文档，开发人员可以快速了解系统架构，掌握开发和部署流程，确保系统的稳定性和可靠性。