跳转到主要内容

为何这对交易而言是安全的

重放窗口(resumeWindowMs,例如 60000)并非一个超过即丢失数据的脆弱时间限制 —— 它是实现零丢失快速恢复的缓冲区。恢复是一个分两级的、经过设计的故障转移机制:
  1. 在窗口内 —— 重新连接并从游标重放错过的更新,无间隙。这涵盖了绝大多数现实世界中的断连(网络抖动、重新部署),它们都会在数秒内解决。
  2. 在窗口外 —— 网关发出 snapshot_required,您通过单次快速 REST 快照恢复完整的当前状态。这是一条明确的、确定性的路径,而非错误。
窗口被有意设置得较短,因为对于实时交易而言,长时间间隙的正确恢复方式是获取当前市场的全新快照,而不是缓慢重放过时的价格。最坏情况只是一次 REST 调用 —— 有界且可预测,绝不会是无限期的中断。参见可靠性与运维。

“恢复”意味着什么

成功登录后,服务器在login_ok中返回一个resume块:
这告诉您:
  • serverEpoch — 标识当前网关会话(重启时更改)
  • resumeWindowMs — 可重放数据缓冲的时间长度
  • replayChannels — 符合重放条件的频道
  • serverEntryIds — 服务器每个频道的最新游标

发布时由服务器发起的重连

当我们部署新的网关版本或对节点进行再平衡时,服务器不会悄无声息地断开您的连接。 它会先向每个已连接的客户端推送一个控制帧:
这是一个 JSON 文本帧(控制帧),在所有 receiveType 模式下都会发送。发送之后, 服务器会在一个较短的宽限窗口(几秒钟)内继续推送数据,然后关闭连接。 您的客户端应该怎么做:
  1. 响应这条消息,而不是响应套接字错误。 一旦看到 type: "reconnect",就立即重新连接到 同一端点。不要等到最终的关闭(1006/4002)—— 按提示行动可以把发布期间的数据缺口降到最小。
  2. 接替的副本拥有新的 serverEpoch。因此,用您保存的 serverEpoch 恢复时会返回 snapshot_required,原因为 server_restarted(见下文)。这在发布期间属于预期行为 —— 为受影响的频道重新获取 REST 快照,然后继续即可。
无论 reason 是什么,都请把任何 reconnect 帧视为“立即重连”。今后可能会新增原因; 应对动作始终相同。

客户端必须持久化的内容

为安全恢复,请持久化:
  1. serverEpoch
  2. 每个频道您处理的最新entryId

entryId格式

每条流式消息包含一个entryId:
  • ts_ms — 服务器时间戳(UTC,毫秒)
  • seq — 每个频道的单调序列
重要:
  • entryId是一个游标,不是交付保证
  • 间隙是正常的(上游行为、合并、背压)

恢复登录示例

重新连接时,发送相同的serverEpoch和您存储的游标:
如果重放成功,服务器发送:

snapshot_required(当重放不可能时)

有时无法安全地进行重放。在这种情况下,服务器发送:

可能的原因

  • server_restarted — 网关重启,游标无效
  • resume_window_exceeded — 您的游标比重放缓冲区更旧
  • client_backpressure — 您的客户端无法足够快地消费重放

重要细节

重放资格取决于游标年龄,而不是断开连接持续时间:
如果您最后处理的消息已经很旧,即使非常短的断开连接也可能超过窗口。

客户端应如何处理snapshot_required

当您收到snapshot_required时:
  1. 通过REST为列出的频道获取新快照 (例如/fixtures、/fixtures/odds、/futures)
  2. 清除这些频道的lastSeenId
  3. 继续处理实时更新
网关在snapshot_required后继续流式传输。 此消息是您的信号,表明本地状态必须重建。

Python重新连接示例(完整模板)

此示例:
  • 持久化serverEpoch和每个频道的lastSeenId
  • 仅为可重放频道发送游标
  • 处理snapshot_required
  • 失败时自动重新连接