sanguo_vnpy_v2/tests/WEBSOCKET_TESTING.md

WebSocket 测试指南

概述

Phase 3 实现了 WebSocket 实时数据推送功能，包括：

• WebSocket 连接管理
• 事件监听器（Tick, Order, Trade, Position, Account, Log, Contract）
• 订阅管理
• 心跳机制

启动服务器

cd /Users/chufeng/.openclaw/sanguo_projects/sanguo_vnpy_v2

# 启动 FastAPI 服务器
uvicorn sanguo_web.api:app --host 0.0.0.0 --port 8000 --reload

测试方法

方法 1: 使用 HTML 测试页面

1. 在浏览器中打开：

   file:///Users/chufeng/.openclaw/sanguo_projects/sanguo_vnpy_v2/tests/websocket_test.html
   

2. 点击"连接"按钮建立 WebSocket 连接

3. 选择要订阅的数据类型：

   • 行情 (Tick)
   • 订单 (Order)
   • 成交 (Trade)
   • 持仓 (Position)
   • 账户 (Account)
   • 日志 (Log)
   • 合约 (Contract)

4. 可选：输入品种代码（如：IF2501.CFFEX,IH2501.CFFEX）并订阅

5. 查看实时消息日志

方法 2: 使用 Python 测试脚本

# 安装依赖
pip install websockets

# 运行测试
cd /Users/chufeng/.openclaw/sanguo_projects/sanguo_vnpy_v2
python tests/test_websocket.py

测试脚本会执行以下测试：

1. 基本连接测试
2. 订阅功能测试
3. 消息接收测试
4. 心跳机制测试
5. 错误处理测试
6. 认证连接测试

方法 3: 使用 wscat 命令行工具

# 安装 wscat
npm install -g wscat

# 连接 WebSocket
wscat -c ws://localhost:8000/ws

# 发送订阅消息
{"type":"subscribe","data":{"subscription":["tick","order","trade"]}}

# 发送心跳
{"type":"ping","data":{}}

# 订阅品种
{"type":"subscribe_symbol","data":{"symbol":["IF2501.CFFEX"]}}

方法 4: 使用 JavaScript 控制台

在任何网页中打开浏览器控制台，运行：

// 创建 WebSocket 连接
const ws = new WebSocket('ws://localhost:8000/ws');

// 监听连接事件
ws.onopen = () => {
    console.log('Connected');

    // 订阅行情数据
    ws.send(JSON.stringify({
        type: 'subscribe',
        data: { subscription: ['tick', 'order', 'trade'] }
    }));
};

// 监听消息
ws.onmessage = (event) => {
    const message = JSON.parse(event.data);
    console.log('Received:', message);
};

// 发送心跳
ws.send(JSON.stringify({ type: 'ping', data: {} }));

WebSocket 消息格式

订阅消息（客户端 -> 服务器）

{
  "type": "subscribe",
  "data": {
    "subscription": ["tick", "order", "trade"]
  }
}

订阅品种（客户端 -> 服务器）

{
  "type": "subscribe_symbol",
  "data": {
    "symbol": ["IF2501.CFFEX", "IH2501.CFFEX"]
  }
}

心跳消息（客户端 -> 服务器）

{
  "type": "ping",
  "data": {}
}

推送消息（服务器 -> 客户端）

{
  "type": "tick",
  "data": {
    "vt_symbol": "IF2501.CFFEX",
    "symbol": "IF2501",
    "exchange": "CFFEX",
    "last_price": 3500.0,
    "bid_price_1": 3499.0,
    "ask_price_1": 3501.0,
    "volume": 12345,
    "datetime": "2025-01-01T09:30:00"
  }
}

订阅类型

类型	说明	事件类型
tick	行情数据	eTick.
order	订单数据	eOrder.
trade	成交数据	eTrade.
position	持仓数据	ePosition.
account	账户数据	eAccount.
log	日志数据	eLog
contract	合约数据	eContract.

验收标准

Phase 3 完成验收：

• WebSocket 管理器完成
• WebSocket 路由完成
• 事件监听器完成
• 心跳机制完成
• 订阅管理完成
• WebSocket 集成到 FastAPI
• 测试脚本和页面创建

故障排查

连接失败

1. 检查服务器是否运行
2. 检查 URL 是否正确
3. 检查防火墙设置

没有收到消息

1. 检查是否已订阅相应数据类型
2. 检查 VeighNa 网关是否连接
3. 检查是否有行情数据

心跳无响应

1. 检查服务器负载
2. 检查网络连接稳定性