接入教程Python 3.11 · websockets 12
Python WebSocket 行情订阅与自动重连
用 Python websockets 库实现行情订阅、定时心跳、断线指数退避重连与自动重新订阅,附可直接复用的完整代码。
更新时间:
维护方:AllTick 官方技术团队
适用对象:需要实时接收行情推送的 Python 开发者
核心结论 · 30秒开发速览
一个可上线的 WebSocket 行情客户端需要四个部分:连接后发送订阅、按固定间隔发送心跳、断线后按指数退避重连、重连成功后重新发送订阅。下面的示例基于 AllTick 股票 WebSocket 接口实现这四点。
01
协议要点
| 项目 | AllTick 中的约定 |
|---|---|
| 股票连接地址 | wss://quote.alltick.co/quote-stock-b-ws-api?token=你的Token |
| 外汇/贵金属/大宗商品 | wss://quote.alltick.co/quote-b-ws-api?token=你的Token |
| 订阅最新成交 | cmd_id 22004,data.symbol_list 为标的列表 |
| 心跳 | cmd_id 22000,官方示例每 10 秒发送一次 |
02
完整代码
终端命令bash
pip install websocketsstream_quotes.pypython
import asyncio, json, os, random, uuidimport websocketsWS_URL = "wss://quote.alltick.co/quote-stock-b-ws-api?token={token}"CMD_SUBSCRIBE_TRADE = 22004CMD_HEARTBEAT = 22000HEARTBEAT_SECONDS = 10CODES = ["700.HK", "AAPL.US"]def message(cmd_id: int, data: dict) -> str: return json.dumps({"cmd_id": cmd_id, "seq_id": 1, "trace": str(uuid.uuid4()), "data": data})async def heartbeat(ws): while True: await asyncio.sleep(HEARTBEAT_SECONDS) await ws.send(message(CMD_HEARTBEAT, {}))async def run_once(url: str): async with websockets.connect(url, ping_interval=None) as ws: await ws.send(message(CMD_SUBSCRIBE_TRADE, {"symbol_list": [{"code": c} for c in CODES]})) beat = asyncio.create_task(heartbeat(ws)) try: async for raw in ws: handle(json.loads(raw)) finally: beat.cancel()def handle(msg: dict): if msg.get("cmd_id") == CMD_HEARTBEAT + 1: return print(msg)async def main(): token = os.getenv("ALLTICK_API_TOKEN", "YOUR_API_TOKEN") url = WS_URL.format(token=token) delay = 1 while True: try: await run_once(url) delay = 1 except (websockets.WebSocketException, OSError) as exc: wait = min(delay, 60) + random.uniform(0, 1) print(f"连接断开:{exc!r},{wait:.1f} 秒后重连") await asyncio.sleep(wait) delay *= 2if __name__ == "__main__": asyncio.run(main())03
代码设计说明
- 订阅放在 run_once 内部,因此每次重连都会自动重新订阅,不会出现“连上了但没数据”。
- 重连等待时间从 1 秒开始翻倍,上限 60 秒,并加入随机抖动,避免大量客户端同时重连。
- 心跳任务在连接关闭时被取消,不会向已关闭的连接写数据。
- ping_interval=None 关闭库自带的 ping,改用协议规定的应用层心跳。
- handle 中过滤了心跳回包;回包命令号以文档为准,可按需调整。
04
上线前补充
1把 print 替换为结构化日志,记录每次断线原因与重连耗时。
2对连续重连失败设置告警阈值。
3重连后用 REST 补齐断线期间的 K 线。
4控制单连接订阅数在套餐允许范围内。
规范来源与验证记录 · 2026-10-13
已根据下方一手资料核对相关端点、字段与交易所规则。
Python 示例已在 Python 3.14.0 上通过 ast.parse 语法解析;此检查不验证依赖安装、运行兼容性或网络响应。
本轮未使用真实 Token 执行 AllTick 请求,也未完成生产端到端测试。复现时请记录套餐、依赖版本、交易时段、ret/trace 与实际结果。
一手规范与规则
上线前建议复现
- 每 10 秒发送 cmd_id 22000 并检查 22001;文档超时阈值为 30 秒。断网后先停止旧心跳任务再重连。
- 恢复后重新订阅并核对确认消息;采用抖动和有上限的重试,避免并行重连超过 Token 连接额度。