从2500次请求降至24次：GitHub重构Star历史API

GitHub 工程团队近日发布了一篇架构优化博客，详细介绍了他们如何重构 Star History（星标历史）API，将每次获取趋势数据所需的请求从约 2,500 次降至 24 次，同时不再返回具体的 stargazers 身份信息，也不再依赖无界的数据库查询。这背后是对隐私、性能与架构的一次系统性取舍。

旧方案的问题：2500 次请求与身份暴露

在旧实现中，要绘制一个仓库的 star 增长曲线，后端需要查询并返回每一个 stargazer 的账号信息或时间戳。对于一个拥有数万 star 的热门仓库，这意味着 2,500 次甚至更多的分页请求，以及大量重复的身份数据传递。

这种设计带来三个直接问题：

• 性能瓶颈：请求数与 star 数量线性相关，热门仓库的 API 响应极慢，数据库压力巨大。
• 隐私风险：返回个体身份信息并非趋势展示所必需，却扩大了数据暴露面。
• 无界查询：随着仓库 star 持续增长，数据库工作量没有上限，难以做容量规划。

GitHub 团队意识到，用户真正需要的是“趋势”，而非“谁在什么时候点了 star”。

分页请求是 REST API 处理大批量结果时的常见机制：由于单次响应有大小限制，服务端会把结果切成若干页，客户端必须携带页码或游标逐页拉取，直到取完为止。这种机制的代价在于，总请求数与被读取的记录总数成正比——要枚举一个有 5 万 star 的仓库的全部 stargazer，就可能需要数百甚至上千次往返。

与之相关的是无界查询的概念：当查询返回的行数没有硬性上限，且会随业务数据自然增长而持续膨胀时，这个查询就是无界的。无界查询在数据量小时看不出问题，一旦某个热门仓库的 star 数暴增，就会同时拖垮响应延迟、数据库连接池和下游客户端的超时设置。判断一个查询是否有界，可以问两个问题：返回行数是否由输入参数（如时间窗口、分页大小）决定，还是由表的总数据量决定？后者就是需要警惕的信号。

核心思路：只保留趋势，不保留身份

重构的关键决策是：Star History API 不再返回单个 stargazer 的身份，只返回聚合后的时间序列趋势。

这意味着后端可以把数据预聚合为按天或按小时分桶的计数，而不是在每次请求时实时遍历所有 stargazer 记录。查询从“无界”变为“有界”——无论仓库有多少 star，返回的数据点数量都由时间窗口决定，而不是由 star 总数决定。

据 GitHub 工程博客描述，这一改变让单次趋势查询所需的请求数从约 2,500 次压缩到 24 次。请求数的下降并非简单的缓存命中率提升，而是数据模型层面的重新设计。

时间序列分桶是指将离散的、按事件发生时刻记录的数据点，归并到固定长度的时间区间（如一天或一小时）内，并以该区间的计数作为存储和查询的基本单位。例如，把某仓库在 2024 年 3 月 1 日收到的 47 个 star 合并为「2024-03-01 → 47」这一条记录，而不是保留 47 条带时间戳的个体记录。

分桶粒度决定了数据的精度与体量：粒度越粗（按天），存储和查询成本越低，但无法还原小时级的突发波动；粒度越细（按小时），精度更高，但数据点数量成倍增加。对于 star 增长曲线这类以「天」为观察单位的趋势展示，按天分桶通常已经足够。分桶还有一个重要特性：无论仓库总共积累了多少 star，返回的数据点数量只取决于所选时间窗口的长度，这让 API 的响应体大小和查询成本都变得可预测。

工程取舍：24 次请求从何而来

把 2,500 次降到 24 次，并不是一个魔法数字。它反映的是聚合粒度与查询范围之间的平衡。

• 聚合而非列举：趋势数据按时间桶存储，查询只读取桶计数，不再扫描个体记录。
• 有界查询：请求数量由时间窗口和分桶粒度决定，与仓库 star 规模解耦。
• 放弃身份维度：不再返回 stargazer 列表，直接消除了大量分页请求和身份数据传输。

这种取舍的代价是 API 能力的收窄——开发者无法再通过该接口获取“谁 star 了这个仓库”。但对于展示 star 历史趋势这一核心场景，聚合数据已经足够。

对开发者和平台的意义

这次重构释放出几个信号：

1. API 设计应匹配真实用例。大多数调用 Star History 的场景是画图或展示增长趋势，而非做社交图谱分析。按用例裁剪返回字段，能大幅降低系统复杂度。
2. 隐私与性能可以同向优化。去除身份信息既是隐私保护，也直接减少了数据库和网络开销，二者并不矛盾。
3. 有界查询是可运维性的基础。无界数据库工作在流量增长时必然成为隐患，把查询复杂度与数据规模解耦是长期可维护的关键。

对于依赖 GitHub API 的开发者而言，如果现有代码仍在解析 stargazer 身份字段，需要关注该接口的返回结构变化，并转向使用聚合趋势数据。

小结

GitHub 这次 Star History API 重构，本质上是一次“减法”工程：去掉身份维度、去掉无界查询、去掉与展示目标无关的数据。2,500 到 24 的请求数变化，是数据模型重新设计后的自然结果，而不是靠堆缓存或加机器换来的。对于正在设计类似趋势类 API 的团队，这个案例提供了一个清晰的参考：先问清楚用户要的是趋势还是明细，再决定要不要保留身份和无界查询。