接入前的准备
动手写代码之前,先明确三件事:要覆盖哪些项目和联赛、要不要实时更新、要不要历史数据。只做五大联赛和做全球 1000+ 赛事,方案完全不同。
四步跑通接入链路
- 在开发者平台注册,试用额度当天就能用。
- 控制台创建应用,拿到
app_key/app_secret。密钥只放服务端。 - 先调赛程接口,验证签名和网络。
- REST 通了再订比分与事件流。
第一次调用:拉取今日赛程
参数少、返回结构直观。新手最常遇到两件事:签名顺序导致 401,以及把时间字段当本地小时直接截取。
GET /v1/fixtures?date=2026-08-25&sport=football
时间字段按带偏移的 ISO 8601 入库 UTC,展示时再转用户时区。
订阅实时更新
按赛事或比赛订阅,服务端只推差量。心跳按文档间隔发;断线后指数退避,重连带上本地最后一个 seq 请求补发。同一事件可能重复到达,用 seq 去重,不要「收到就加一分」。
工程实践建议
档案类数据每日同步,赛程类每小时同步,线上只打本地缓存。开发、测试、生产分开应用,避免测试脚本把生产额度打光。
常见问题排查清单
| 现象 | 大概率原因 | 排查方向 |
|---|---|---|
| 401 | 参数顺序或编码 | 对照文档核对签名原文 |
| 429 | 轮询过频 | 改成定时同步 + 本地缓存 |
| 收不到实时 | 心跳超时 / 未订成功 | 看心跳间隔与订阅回执 |
