D
DSG54562/topic-66-model
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

足球赛程平台周月视图切换接口优化

问题背景

足球赛程平台提供周视图与月视图两种赛程展示形态。用户在两种视图之间切换时,前端每次都会重新发起赛程查询请求,现有实现存在以下问题:

  • 参数口径不一致:周视图与月视图的请求参数各自定义,服务端需要分别解析并组装查询语句,同一时间段的数据被重复查询。
  • 缓存利用率低:同一时间段的赛程在周、月两种粒度下分别缓存,未共享基础赛程数据,切换视图时缓存命中率不高。
  • 切换抖动:视图切换瞬间并发请求的返回顺序不确定,页面可能出现赛程数据短暂回退或闪烁。

本 README 围绕「周月视图切换」场景,描述一种以「视图类型归一化 + 统一赛程查询接口 + 区间结果缓存 + 指纹校验」为核心的最小优化方案。

实现方案

方案要点:

  1. 统一查询入口:前端无论切换周视图还是月视图,都调用同一个赛程查询接口,仅传入视图类型(week / month)与参考日期。
  2. 服务端区间归一化:服务端根据视图类型计算查询区间。周视图取参考日期所在自然周(周一至周日),月视图取参考日期所在自然月(月初至月末),统一转换为 [startDate, endDate] 区间。
  3. 区间结果缓存:以归一化后的时间区间为缓存键,缓存赛程负载与数据指纹。命中且指纹一致时直接返回缓存;未命中或指纹不一致时查询数据库并回填缓存。
  4. 指纹校验:写入缓存时记录负载的 SHA-256 指纹,读取时先比对指纹。布隆过滤器或摘要命中后必须通过精确记录确认,不得直接跳过新内容或已有内容的更新。

代码示例

以下示例均未实际运行,统一标注「待验证」。正文描述、代码行为与验证步骤保持一致,不声明任何实测数据。

依赖与执行方式

  • 运行环境:Python 3.9+
  • 依赖库:FastAPI 0.100+、uvicorn 0.23+、redis-py 4.5+

执行方式(待验证):

pip install "fastapi>=0.100" "uvicorn>=0.23" "redis>=4.5"
python main.py

预期结果:服务启动后,可通过 GET /api/schedules?view=week&ref_date=2026-10-15 等请求获取归一化区间。以下示例尚未执行,预期结果为设计预期而非实测结论。

配置变量与区间归一化

示例使用命名配置变量承接视图类型与时间区间计算,不包含额外示例域名。

# config.py
from datetime import date, timedelta


class ScheduleViewConfig:
    VIEW_TYPES = ("week", "month")

    @staticmethod
    def normalize_interval(view_type: str, ref_date: date) -> tuple[date, date]:
        # 待验证:以下实现尚未实际运行
        if view_type == "week":
            start = ref_date - timedelta(days=ref_date.weekday())
            end = start + timedelta(days=6)
        elif view_type == "month":
            start = ref_date.replace(day=1)
            end = (start + timedelta(days=32)).replace(day=1) - timedelta(days=1)
        else:
            raise ValueError(f"unsupported view type: {view_type}")
        return start, end

统一赛程查询接口

# main.py
from datetime import date

from fastapi import FastAPI, Query

from config import ScheduleViewConfig

app = FastAPI()

# 待验证:以下接口示例尚未实际运行
@app.get("/api/schedules")
def list_schedules(
    view: str = Query(..., pattern="^(week|month)$"),
    ref_date: date = Query(...),
):
    start, end = ScheduleViewConfig.normalize_interval(view, ref_date)
    return {"view": view, "start": start.isoformat(), "end": end.isoformat()}

缓存与指纹校验

# cache.py
import hashlib
import json


# 待验证:以下示例依赖可用的 redis 实例,尚未实际运行
class ScheduleCache:
    def __init__(self, redis_client):
        self.redis = redis_client

    @staticmethod
    def _key(start: str, end: str) -> str:
        return f"schedule:interval:{start}:{end}"

    @staticmethod
    def _fingerprint(payload: str) -> str:
        return hashlib.sha256(payload.encode("utf-8")).hexdigest()

    def get(self, start: str, end: str):
        key = self._key(start, end)
        raw = self.redis.get(key)
        if raw is None:
            return None
        data = json.loads(raw)
        # 布隆过滤器或摘要命中后必须通过精确记录确认,
        # 不得直接跳过新内容或已有内容的更新
        if data.get("fingerprint") != self._fingerprint(data.get("payload", "")):
            return None
        return data

    def set(self, start: str, end: str, payload: str):
        key = self._key(start, end)
        data = {"payload": payload, "fingerprint": self._fingerprint(payload)}
        self.redis.set(key, json.dumps(data, ensure_ascii=False))

预期结果(待验证):对同一归一化区间重复请求时,首次请求查询并写入缓存,后续请求命中缓存且指纹一致时直接返回;赛程内容更新后指纹变化,缓存视为失效并回源查询。若示例支持批量写入,则应在实际提交中逐条批量提交;若示例支持内容更新,则应在实际提交中同步更新指纹与负载。以上均未实际执行。

验证方法

验证步骤(均未实际执行,待验证):

  1. 区间一致性:对同一参考日期分别请求 view=week 与 view=month,确认返回的 start/end 与自然周(周一至周日)、自然月(月初至月末)一致。
  2. 缓存命中:对同一区间连续请求两次,确认第二次返回数据与第一次一致,且未重复触发数据库查询。
  3. 内容更新:修改赛程数据后重新请求同一区间,确认指纹变化导致缓存失效,并返回更新后的数据。
  4. 视图切换:在周视图与月视图之间来回切换,确认接口始终返回与当前视图一致的区间数据,页面不出现数据回退。

以上验证未在本仓库执行,本 README 不提供通过记录、性能数据或压测结论。

局限性

  • 缓存键仅覆盖时间区间,未包含球队、赛事类型等附加筛选条件;如需支持,需要将筛选条件并入缓存键。
  • 指纹校验基于负载文本,未覆盖数据库记录级变更的完整语义,也未接入布隆过滤器的精确回查实现。
  • 示例代码未经过性能压测,不声明任何吞吐量、延迟或命中率数据。
  • 本 README 仅描述优化思路与示例代码,不代表目标仓库已实现上述功能;仓库现有功能、测试记录与性能数据均未被虚构或引用。

用户提供的网址(未核验)

以下网址由用户作为纯文本输入提供,本 README 未访问、抓取或读取其内容,未核验其相关性与可访问性,不将其作为任何技术结论的依据。

GitHub 链接(3 条)

https://github.com/pedrommcbride/avhpdh/blob/main/2026%E5%B9%B410%E6%9C%88%E6%B7%B1%E5%BA%A6%E4%B8%93%E5%AE%B6%E9%A2%84%E6%B5%8B-%E8%B6%B3%E7%90%83%E6%AF%94%E5%88%86_%E8%B6%B3%E7%90%83%E5%8D%B3%E6%97%B6%E6%AF%94%E5%88%86_%E8%B6%B3%E7%90%83%E6%AF%94%E5%88%86%E7%9B%B4%E6%92%AD-%E7%9A%87%E5%86%A0%E4%BD%93%E8%82%B2-%E9%87%91%E5%8D%B0%E8%B4%A2%E7%BB%8F.md

https://github.com/pedrommcbride/avhpdh/blob/main/2027%E5%B9%B410%E6%9C%88%E8%80%83%E6%83%85%E8%B6%8B%E5%8A%BF%E9%A2%84%E6%B5%8B-%E8%B6%B3%E7%90%83%E6%AF%94%E8%B5%9B%E6%8E%A8%E8%8D%90%E7%BE%8E%E6%B4%B2%E6%9D%AF-%E9%92%B1%E5%A1%98%E8%B4%A2%E7%BB%8F.md

https://github.com/pedrommcbride/hfufbp/blob/main/2027%E5%B9%B410%E6%9C%88%E7%90%86%E6%80%A7%E6%8E%A8%E6%BC%94%E9%A2%84%E6%B5%8B-%E4%BB%8A%E6%97%A5%E6%AC%A7%E8%81%94%E8%B6%B3%E7%90%83%E7%AB%9E%E5%BD%A9%E6%8E%A8%E8%8D%90-%E6%95%B0%E8%BF%9C%E8%B4%A2%E7%BB%8F.md

外部链接(3 条)

https://bshsms.northrex.cn/article/bei-dan

https://bshsms.northrex.cn/article/ba-xi-zu

https://bshsms.northrex.cn/article/shi-yu-sai