动手前先钉死这 3 个问题
接入体育数据 API 之前，有三个问题如果没和产品、运营对齐，后面写多少代码都是返工。它们不涉及签名算法，但直接决定你拉什么数据、怎么缓存、怎么降级。
覆盖范围。你要的是足球、篮球，还是两项都要？联赛是只做五大联赛，还是包含杯赛、预选赛、青年队赛事？这决定了你请求里的 sport、league 参数怎么传，也决定了你拿到的赛程列表里会不会突然冒出一场你前端根本没做展示模板的比赛。我们见过团队上线后才发现接口返回了女足赛事，前端把队名截断了。覆盖清单应该在注册后第一件事就找对接人确认，而不是等联调时靠返回值猜。
实时性要求。比分推送是秒级、分钟级还是只做赛后统计？这三种需求对应完全不同的接入方式。秒级走 WebSocket 或长连接订阅，分钟级可以轮询 REST，赛后统计直接拉历史接口就行。很多 401 的排查时间其实浪费在「我明明订阅了为什么没数据」——结果发现订阅的是 A 赛事，轮询的是 B 赛事。先把实时性写进技术方案，再动手。
历史深度。你需要回溯多久？一周、一个赛季还是三年？历史数据的存储和查询接口通常和实时接口是分开的，鉴权方式可能一致但参数不同。如果产品要做「近十场交锋」，你得确认接口能不能按两队 ID 查历史，而不是自己攒数据。这一点在注册阶段就要问清楚，否则后期补数据迁移成本很高。
这三个问题钉死之后，你才能确定：用哪个环境、调哪组接口、签名覆盖哪些参数。下面进入实际链路。
最小可跑通链路：注册 → 密钥 → 第一个 REST → 实时订阅
别一上来就写完整业务。先跑通一条最小链路，把签名、时区、编码这三个变量隔离出来验证。
第一步，注册与获取密钥。到开发者平台 https://dev.apiballs.com/#/user_register 完成注册，在控制台拿到 app_id 和 app_secret。注意：密钥只在创建时完整展示一次，之后控制台只显示前缀。如果你没保存，只能重置。我们建议在团队密码管理工具里存一份，别贴在聊天记录里。
第二步，确认环境域名。测试环境和生产环境的域名不同，密钥也可能不同。很多 401 是因为拿测试密钥打了生产域名。控制台里会标明每个密钥绑定的环境，核对一下。
第三步，发第一个 REST 请求。选一个不依赖实时性的接口，比如「赛事列表」或「球队信息」。这类接口参数少，签名容易核对。请求里通常包含：app_id、timestamp、sign，以及业务参数。
第四步，验证实时订阅。REST 通了之后，再试订阅。订阅的鉴权通常在握手阶段完成，签名规则和 REST 一致，但时间戳的有效窗口更短。如果 REST 通了订阅不通，先看握手时的参数是不是漏了 sign 或 timestamp。
这条链路跑通的标准是：你能在日志里看到一次完整的请求参数、一次成功的响应、一次订阅的心跳。把这三段日志留着，后面排查全靠它们。
第一次调用示例（含示意请求）
下面是一个示意请求，用来核对签名结构。具体参数名以你控制台文档为准，这里只演示顺序和编码。
POST /v1/match/list HTTP/1.1
Host: api.example-sports.com
Content-Type: application/json
X-App-Id: your_app_id
X-Timestamp: 1710000000
X-Sign: 3f8a...c2d1
{
"sport": "football",
"date": "2025-03-15",
"page": 1,
"page_size": 20
}
签名串的拼接顺序，常见的是：app_id + timestamp + 业务参数按 key 字典序 + app_secret。注意几个坑：
- 业务参数里如果嵌套了 JSON，要确认是拍平还是整体参与签名。两种规则都有，看文档。
- 空值参数参不参与签名？有的接口要求过滤掉
null和空字符串，有的要求保留。这一点最容易出错。 - 时间戳是秒还是毫秒？文档会写，但很多人复制示例代码时没改。
- 签名字符串拼接后，是直接做哈希还是先 URL 编码？顺序反了结果完全不同。
一个可用的核对方法：在本地把签名串打印出来，和文档里的示例逐字符比对。如果文档没给示例，用同一组参数发两次请求，看签名是否稳定。不稳定说明有时间戳或随机数参与，稳定但 401 说明拼接规则错了。
# 示意：签名串拼接（顺序以文档为准）
params = {"sport": "football", "date": "2025-03-15", "page": 1}
sorted_items = sorted(params.items())
raw = app_id + str(timestamp) + "".join(f"{k}{v}" for k, v in sorted_items) + app_secret
sign = hashlib.md5(raw.encode("utf-8")).hexdigest()
这段代码的关键不是算法，是 sorted 和 str(timestamp)。我们见过团队用 timestamp 的毫秒值去拼，结果和服务端的秒值对不上，一直 401。
签名 / 时区两个高频 4xx
401 和 403 是接入阶段最常见的两个状态码。401 通常是签名校验失败，403 是权限或覆盖范围问题。这里只谈 401。
时区问题。时间戳本身是 Unix 时间，不带时区。但如果你在生成 date 参数时用了本地时区，而服务端按 UTC 解析，就会查到错误的数据，甚至因为日期格式不匹配触发签名失败。比如你在东八区写 2025-03-15，服务端按 UTC 算可能还是 2025-03-14。解决办法：所有日期参数统一用 UTC 生成，或者在请求里显式带时区偏移。日志里看到 date 和 timestamp 对不上，先查这里。
空格与编码。签名串里如果包含空格、中文、特殊字符，编码方式必须和服务端一致。常见错误是客户端对参数做了 URL 编码，服务端用原始值签名，或者反过来。还有一种情况：参数值末尾有空格，肉眼看不出来，签名结果却不同。排查时把签名串用 repr() 打印出来，看有没有隐藏字符。
参数顺序。字典序不是「你代码里的顺序」，是 ASCII 码顺序。大写字母在小写字母前面，数字在字母前面。如果参数名有下划线和驼峰混用，顺序很容易错。建议直接按文档给的顺序表核对，别自己猜。
密钥本身。如果以上都排除了，再怀疑密钥。检查有没有多余空格、有没有复制错行、有没有用测试密钥打生产。密钥轮换后旧密钥通常有短暂宽限期，但宽限期一过就 401。控制台里能看到密钥的最后使用时间，对一下就知道是不是用错了。
实时订阅必须处理的心跳、幂等、撤回
实时订阅和 REST 的排查思路不同。REST 是一次请求一次响应，订阅是长连接，出问题往往不是 401，而是「连上了但没数据」。
心跳。大多数订阅协议要求客户端定期发心跳，服务端也回心跳。如果客户端不发，服务端可能在 30 秒到 2 分钟后断开。断开后重连，如果签名时间戳过期，就会 401。所以心跳间隔要小于服务端超时时间，重连时要重新生成签名。日志里看到「连接建立 → 无消息 → 断开 → 重连 401」，先查心跳。
幂等。订阅推送的消息可能重复，尤其是网络抖动重连后。客户端要用消息 ID 做去重，别直接把每条消息都写库。我们见过比分被重复累加的案例，就是没做幂等。消息 ID 通常在推送体里，字段名可能是 event_id 或 seq，看文档。
撤回。比分数据有撤回场景：进球被 VAR 取消、事件归属修改。订阅协议里通常有 retract 或 revoke 类型的消息。客户端收到这类消息，要把之前那条事件标记为无效，而不是删除。前端展示时用「已取消」状态覆盖。如果只做追加不做撤回，用户会看到不存在的进球。
// 示意：订阅消息处理骨架
ws.onmessage = (msg) => {
const data = JSON.parse(msg.data);
if (data.type === "heartbeat") return;
if (seen.has(data.event_id)) return; // 幂等
seen.add(data.event_id);
if (data.type === "retract") {
markAsRetracted(data.event_id); // 撤回
} else {
upsertEvent(data);
}
};
心跳、幂等、撤回这三件事，建议在联调第一天就写进代码，别等上线后补。补的时候往往已经有一批脏数据了。
排查表：现象 / 原因 / 怎么查
把常见现象整理成表，联调时直接对照。这张表按「从外到内」的顺序排：先查请求本身，再查签名，最后查密钥和环境。
| 现象 | 可能原因 | 怎么查 |
|---|---|---|
| 所有接口都 401 | 密钥错、环境错、时间戳格式错 | 核对控制台密钥前缀，确认域名，打印时间戳位数 |
| 部分接口 401 | 该接口参数多，签名漏了参数 | 对比文档参数表，检查空值是否参与签名 |
| 偶发 401 | 时间戳过期、客户端时钟漂移 | 检查服务器 NTP，看请求间隔是否超过有效窗口 |
| 订阅握手 401 | 握手参数漏了 sign 或 timestamp | 抓包看握手帧，对比 REST 请求头 |
| 连上后无数据 | 订阅的赛事 ID 不对、心跳没发 | 查订阅参数，看心跳日志 |
| 数据重复 | 没做幂等 | 查消息 ID 去重逻辑 |
| 比分不更新 | 没处理撤回、缓存没失效 | 查撤回消息日志，看前端缓存策略 |
| 日期查不到 | 时区不一致 | 统一用 UTC 生成日期参数 |
这张表里，「偶发 401」最容易被误判成密钥问题。实际上客户端时钟漂移几分钟，时间戳就过期了。服务器上跑 ntpd 或 chrony，容器里注意宿主机时间同步。
上线前建议做的三件事
第一，把签名逻辑封装成独立模块，输入参数、输出签名，别散落在各个请求里。这样排查时只需要看一个地方。第二，日志里记录完整的签名串（脱敏后），但别记密钥。401 发生时，把签名串和文档示例比对，比看状态码有用。第三，准备一个「最小请求」脚本，只发一个固定参数的请求，用来快速判断是环境问题还是业务问题。
接入体育数据 API，签名和时区是绕不过去的两道坎。把这两道坎的排查顺序固定下来，401 就不再是玄学。全速数据的开发者平台在 https://dev.apiballs.com/#/user_register ，注册后先跑最小链路，再扩业务，比反过来省时间。
