1. 状态:快照加实时流
- 先连接 WebSocket,再拉取 REST 快照并合并。按键比较,
changedAt较新的一方胜出。 - 以
oddsId为键存储赔率。该键在 REST、WebSocket、历史与结算中完全一致,一份存储即可服务四处。 - 登录时用
sportIds、tournamentIds和bookmakers过滤到您实际交易的范围。数据流越小,处理越快,也越不容易触发背压。 - 选定
receiveType。zstd可将odds流量压到 JSON 的约五到六分之一,解码只需一行。
2. 重连与续传
- 持久化
serverEpoch以及每个频道最后处理的entryId。 - 重连时携带
serverEpoch和lastSeenId登录,并等待resume_complete。 - 处理
snapshot_required:为所列频道重新拉取 REST 快照,清除其游标,继续消费。 - 收到
reconnect控制帧后立即重连。每次发布前我们都会发送该帧,不要等到连接被关闭。 - 遇到关闭码
1006和1011时短暂退避后重连。4002(背压)和4003(连接数过多)是需要解决的问题,不应盲目重试。
resumeWindowMs 后以快照恢复。记录第二种情况的耗时,它就是您的最坏恢复时间。
详见:续传与重放、故障排查。
3. 博彩商数据过期
- 在订阅
odds的同时订阅bookmakers频道。 - 按
fixtureId:bookmaker组合保存staleOdds,在使用价格之前先检查它。 - 当其为
true时,暂停该赛事上的该博彩商,或切换到其他博彩商。恢复为false后再继续。 - 将它与
suspended、active、marketActive区分开。后三者是博彩商自身的停盘,staleOdds反映的是我们对该博彩商的可见性。 - 博彩商整体故障会表现为每场赛事一条消息,而不是单独一条消息。
4. 速率限制与连接数
- 赔率接口每个
apiKey每秒 10 次请求,其余接口每分钟 200 次。 - 读取
X-RateLimit-Remaining,遇到429时按Retry-After给出的时间退避。 - 快照和回补用 REST,变更用实时流。循环轮询赔率是触发限流最常见的原因。
- 每个
apiKey组的并发 WebSocket 连接不超过 8 个。如需更多,请在设计前联系我们。
5. 监控
- 跟踪传输延迟:您的接收时间减去消息的
ts。请先运行 NTP,否则 100 毫秒以下的读数意义不大。 - 按博彩商跟踪观测延迟:
changedAt − bookmakerChangedAt,并与GET /bookmakers中的maxDelayLiveInSec和maxDelayPregameInSec对照。 - 对重连次数、
snapshot_required次数,以及每个博彩商被标记staleOdds的赛事占比设置告警。 - 订阅状态页,获取故障与维护通知。
- 如果延迟重要,请部署在靠近我们的位置:德国中部或美国东部。
6. 变更与支持
- 关注更新日志。标记为重大变更的条目需要您这边采取行动。
- 忽略响应中的未知字段。任何一次发布都可能新增字段。
- 用
X-API-Key请求头而不是查询参数传递密钥,避免其出现在 URL 和日志中。 - 向 contact@55-tech.com 报告问题时,请提供受影响的频道或接口、UTC 时间戳,以及您的
serverEpoch和entryId。
满足以下条件即可上线
- 强制断线后能无缺口续传,长时间断线能通过快照恢复,且恢复耗时已经实测。
staleOdds标记能自动停止该博彩商在该赛事上的交易,无需人工介入。- 遇到
429时客户端会减速,而不是出错。 - 您自己的监控面板能看到每个博彩商的传输延迟、观测延迟和过期占比。