版本 v1.4
最后更新:2026-11-13
推送协议|WebSocket 订阅、心跳与续传 - FTLib
实时行情通过 WebSocket 推送。协议为 JSON 文本帧,包含鉴权、订阅、心跳与数据消息。客户端应实现断线重连、序列号续传与重复消息去重。
连接与鉴权
连接 wss://push.ftlib.com/v1/stream,在 onopen 后立即发送鉴权消息。鉴权成功后服务端返回 auth.ok,之后才能订阅。
json
{
"op": "auth",
"key": "your_api_key"
}
json
{
"op": "auth.ok",
"session": "sess_38f1c0",
"server_ts": 1794794400123,
"heartbeat_sec": 20
}
订阅与退订
订阅消息包含通道、证券列表与期望序列号。通道包括 quote.l1、quote.l2.book、quote.l2.trade、quote.l2.order。不同通道的字段不同,应按需订阅。
json
{
"op": "subscribe",
"channel": "quote.l2.trade",
"symbols": ["600519.SH", "000001.SZ"],
"seq": 4818292
}
退订使用 unsubscribe,参数与订阅一致。变更订阅时建议先退订旧列表,再订阅新列表,避免重复推送。
消息格式
数据消息包含通道、证券、序列号与业务字段。seq 单调递增,用于排序、去重与续传。
json
{
"op": "data",
"channel": "quote.l2.trade",
"symbol": "600519.SH",
"seq": 4818293,
"ts": 1794553200188,
"data": {
"price": 1688.00,
"volume": 100,
"side": "S",
"trade_id": "T20261113000124"
}
}
心跳与保活
服务端在鉴权成功消息中返回 heartbeat_sec。客户端应在该间隔内发送 ping,服务端返回 pong。连续多个周期无响应时,应主动关闭并重连。
json
{
"op": "ping",
"ts": 1794794420000
}
序列号与续传
每条数据消息带有 seq。客户端应持久化最后成功处理的序列号,重连后携带该值订阅。若缺口超出服务端保留窗口,服务端会返回 resume.failed,此时应通过 REST 重新对齐。
先持久化再确认
只有在校验并写入本地缓冲后,才更新最后处理的序列号。否则进程崩溃后可能丢失消息。
连接与配额
- 并发连接数、单连接订阅代码数与消息速率受接入方案约束。
- 订阅代码过多时应拆分连接或使用批量通道,避免单连接过载。
- 重连使用指数退避,建议从 1 秒开始,上限 30 秒,并加入随机抖动。
- 不要在断线时立即高频重连,以免触发服务端保护。
- 生产环境应监控消息延迟、序列号缺口与重连次数。