体育 API 接入指南：服务端密钥、超时与错误处理

体育数据接入不只是发出一次请求。密钥放在哪里、请求多久放弃、失败后是否重试，都会影响业务安全与稳定性。本文先列出已核验的接口事实，再说明通用工程建议；示例中的配置名称、超时值与处理逻辑均不是百查数据的平台承诺。

一、明确接口目录与实现边界

已核验目录包含国家、联赛、赛季、阶段、球队、球员、场馆列表，以及比赛即时比分、赛程赛果和赛季比赛接口，方法均为 GET。以下列出三个请求地址。目录本身不说明鉴权位置、参数、响应字段、业务错误码或调用限制，接入时应另行确认，不能凭接口名称推断。

接口	方法	地址
球队列表	GET	https://api.superscore.cn/basketball/base/teamPage
比赛-即时比分	GET	https://api.superscore.cn/basketball/change/live
比赛-赛程赛果	GET	https://api.superscore.cn/basketball/change/matchList

二、密钥留在服务端，不进入公开链路

一般工程建议：让浏览器或移动端访问自己的业务服务，由服务端读取凭据并请求上游。不要把密钥写入前端代码、公开仓库、截图或报错页面；环境变量可用于注入配置，正式部署也可使用专门的秘密管理系统。

• 隔离开发与生产凭据，限制读取配置的账号和进程。
• 日志不记录完整鉴权字段；若凭据出现在 URL 中，访问日志也要脱敏。
• 发现泄露后及时替换凭据，并排查仓库历史、构建产物与日志副本。
• 凭据发放、权限设置及轮换方式须以实际接入说明为准，不能由目录推定。

三、设置等待边界，避免无条件重试

一般工程建议：分别设置连接超时与读取超时，并在业务层约束整体耗时。读取超时通常不是整次请求的总时限；下面的数值仅供演示，应结合业务预算调整。超时也不等于上游没有处理请求，只表示调用方未在等待期限内取得预期结果。

不要对所有失败立即重试。对临时网络故障或部分服务端错误，可评估采用有次数上限的退避与随机抖动；鉴权、参数问题应先修正。若收到限流响应，应根据实际响应和接入规则处理，避免多个任务同时重试造成请求放大。

import json
import os
import requests

url = 'https://api.superscore.cn/basketball/change/live'
# 本地示例配置名，并非平台规定的鉴权字段。
# 仅在确认鉴权采用请求头后使用；其他方式需调整。
headers = json.loads(os.environ['SPORTS_REQUEST_HEADERS'])
try:
    response = requests.get(url, headers=headers, timeout=(3, 8))
    response.raise_for_status()
except requests.Timeout:
    raise RuntimeError('上游请求超时') from None
except requests.RequestException:
    # 不向客户端暴露原始异常、完整 URL 或凭据。
    raise RuntimeError('上游请求失败') from None
else:
    # 响应格式与业务成功条件须按实际文档解析。
    body = response.content

四、区分错误层级，保留排障线索

一般工程建议：把错误分为网络异常、HTTP 非成功状态、响应解析失败和业务失败。HTTP 成功并不必然代表业务成功；业务判定只能依据已确认的响应协议，不能自设某个字段或数值为成功标志。示例只处理请求层，不构成完整业务校验。

内部日志可记录请求标识、接口路径、状态码、耗时和错误类别，不记录密钥或未经筛选的响应正文。对外返回稳定、可理解的提示；若业务允许展示缓存结果，应标明更新时间，不能把旧数据伪装成最新数据。上线前模拟超时、非成功状态与格式异常，验证失败路径同样可控。

查看接口文档 · 了解数据产品