注意事项
下面是接入 WebSocket 过程中最容易踩坑、也最值得在写代码前先了解清楚的行为约定。- 先连后订：握手成功后必须发送订阅消息，才会开始收数据。
- 必填字段不要漏：所有请求都要有
code、trace；订阅还必须有data（即使是{}）。 - api_key 至少传一处：URL 或订阅
data.api_key。 - 按需订阅：只订阅套餐已开通的产品；无权限会返回
40301。 - 只收一场比赛：在订阅
data中设置match_id。 - 断线需重订：重连后订阅状态不会保留，需重新发送订阅。
- 订阅失败不断连：收到
40301等错误后连接仍在，可改参重试。 - 限频：同一连接入站消息不要超过 60 条/分钟，否则会被断开。
- 心跳：建议每 30 秒发一次
20010。 - 连接数：超出套餐连接数配额时，握手可能返回
429。 - 重连：建议指数退避（1s → 2s → …，上限 30s）；遇到
429时不要立即狂重连。 - 取消订阅后连接仍在：可继续心跳，或订阅其他产品。
- 推送字段兼容：业务字段可能缺失，客户端勿强依赖每个字段必现。
常见问题
连接成功但没有数据？ 需发送对应订阅 code（含必填trace、data）并收到成功应答；同时确认当前是否有实时赛事更新。收到 connected 只代表连接建立，不代表已经订阅——这是最常见的排查盲点。
能同时订多种数据吗？
可以。同一连接分别发送 20000 / 20200 / 20100 / 20300 即可。
如何只收一场比赛？
订阅 data 中设置 "match_id": "比赛ID"。
订阅失败连接会断吗？
不会。会收到 40301 等错误 JSON，可重试。
心跳要带 data 吗？
不用。心跳只需 code=20010 和 trace。
重连之后订阅还生效吗？
不会自动生效。每次连接都是独立的会话，重连成功收到 connected 后，需要重新发送全部订阅请求。