FTLib
版本 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 秒,并加入随机抖动。
  • 不要在断线时立即高频重连,以免触发服务端保护。
  • 生产环境应监控消息延迟、序列号缺口与重连次数。