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

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

体育数据缓存不仅要回答“有没有数据”，还应回答“这份数据何时成功获取”。若每次发起请求都刷新时间，即使请求失败，页面也可能显示“刚刚更新”，让陈旧数据看起来仍然新鲜。最后成功更新时间应绑定已校验、已提交的缓存版本，而不是一次请求动作。

已核验目录中，百查数据体育 API 提供国家列表，以及联赛、赛季、阶段、球队、球员、教练、裁判、场馆的分页列表；另有比赛-即时比分接口。上述接口均为 GET。目录并未说明响应字段、分页参数、更新频率或缓存协议，以下方案均为接入方的一般工程建议，不代表产品承诺。

二、按查询边界组织缓存

建议将接口路径、规范化后的实际查询条件、页标识和必要的租户隔离标识共同纳入缓存键。不要仅用接口名称作键，否则不同查询可能互相覆盖。基础资料与即时比分可采用不同刷新策略，但具体周期应依据业务容忍度、实际观测和已确认的接口约束设定，不能从接口名称推导固定更新速度。

• 软过期：允许先返回旧缓存，同时触发后台刷新。
• 硬过期：超过业务可接受范围后，提示数据陈旧或停止展示。
• 刷新合并：同一缓存键只允许一个刷新任务执行，减少重复请求。
• 过期抖动：为刷新时间加入随机偏移，避免大量缓存同时失效。

分页列表尤其需要明确快照边界。若业务要求一份完整集合，应先暂存各页，在全部拉取并校验通过后整体发布；中途失败不能把半份集合标为成功。若采用逐页缓存，则每页单独维护成功时间，不应以某一页的时间代表整份列表。

三、把成功时间与数据一起提交

建议在本地元数据中区分最近尝试时间、最后成功更新时间和最近错误。成功必须同时满足响应符合预期、业务结构校验通过，以及缓存提交成功。即使内容没有变化，只要上述步骤完成，也可更新最后成功时间；内容变化时间则应另行记录。该时间表示接入端成功获取并保存数据，不等于赛事事件发生时间或源端更新时间。

# 设计伪代码：字段和函数均属于接入方，不是 API 响应定义
async def refresh(key):
    await record_attempt(key, utc_now())
    try:
        payload = await fetch_configured_get()
        validate_for_application(payload)
        # 原子保存数据与成功时间；并发时需检查版本或锁
        await commit_snapshot(
            key=key,
            data=payload,
            last_success_at=utc_now()
        )
    except Exception as error:
        await record_error(key, error)
        # 保留旧数据和原成功时间，不伪装为刷新成功

缓存数据与成功时间应在同一原子操作中发布，避免出现“新时间配旧数据”。并发刷新还需防止较早启动、较晚完成的任务覆盖新版本，可使用版本检查或受控的刷新锁。统一使用 UTC 存储时间，展示时再转换时区；缓存写入失败也必须保留原成功时间。

四、展示陈旧状态，而不是掩盖失败

页面可同时呈现“最后成功获取时间”和“当前正在刷新”，刷新失败时明确提示仍在使用旧数据。首次请求失败且无缓存时，应显示暂无可用数据，不能填入虚假的成功时间。监控重点可放在缓存年龄、连续失败次数、刷新耗时和快照发布失败；上线前至少验证超时、校验失败、分页中断与并发覆盖场景，确认失败不会推进成功时间。

查看接口文档 · 咨询接入方案