体育数据缓存设计：让“最后成功更新时间”真正可信

一、先明确接口事实与设计边界

百查数据体育 API 已核验目录包含国家列表，以及联赛、赛季、阶段、球队、球员、教练、裁判、场馆的分页列表；另有比赛-即时比分接口。上述接口均使用 GET。目录未说明刷新频率、缓存策略或响应字段，不能据此承诺数据时效。

例如，国家列表地址为 https://api.superscore.cn/football/base/countryList，比赛-即时比分地址为 https://api.superscore.cn/football/change/live。以下时间字段、缓存分层与刷新流程均为接入方的一般工程建议，不代表接口自带能力。

二、缓存按查询范围隔离

缓存键建议包含接口路径、规范化后的查询条件及必要的权限隔离标识，避免不同筛选范围相互覆盖。不要将访问凭证直接放入可展示的键名。基础资料与即时比分可采用不同刷新策略，但具体周期应由业务容忍度、实际观测及接入约束共同确定。

• 单页缓存：键中包含分页条件，更新时间只解释该页的成功提交。
• 集合快照：多页先写入临时区，确认本轮数据完整后再统一发布。
• 过期处理：区分需要刷新与禁止继续使用，允许读旧值时应明确提示。

三、成功时间必须跟随数据提交

建议分别记录 lastAttemptAt、lastSuccessAt 和 lastError。前者表示最近一次尝试，成功时间只在响应通过校验且缓存提交成功后推进。请求超时、解析失败、分页缺失或写入失败，都不能刷新 lastSuccessAt；否则旧数据会被包装成新数据。

HTTP 请求成功也不等于业务数据有效。应依据实际接口文档校验响应结构、业务状态和必要字段；空列表是否有效，需要结合查询语义判断。集合快照只有在全部目标分页完成后才能更新整体成功时间，不能用某一页成功代表整个集合成功。

# 接入方伪代码；字段并非接口响应字段
record_attempt(scope, now_utc())
try:
    candidate = fetch_and_validate(scope)
    with serialized_commit(scope):
        reject_obsolete_refresh(candidate)
        atomic_publish(scope, candidate, lastSuccessAt=now_utc())
except RefreshError as error:
    record_error(scope, error)  # 保留旧快照及其成功时间

数据与成功时间应作为同一快照原子发布。并发刷新还需使用锁、版本校验或同等机制，防止较早发起、较晚完成的任务覆盖新结果。这里的成功时间是本地提交时间，不是赛事事件发生时间，也不自动证明上游数据刚刚变化。

四、展示状态，并验证失败路径

页面宜展示“最近成功同步时间”，并注明时区。刷新失败但旧缓存仍可用时，可提示“本次刷新失败，当前展示上次成功数据”；从未成功时显示“暂无成功同步记录”，不要使用当前时间占位。监控应同时观察连续失败、快照年龄与提交异常。

上线前重点测试超时、有效空结果、部分分页失败、缓存写入失败与并发乱序。验收原则很简单：失败不推进成功时间，旧数据不冒充新数据，时间标签与实际展示的数据始终对应同一快照。

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