CheckMyGit源码揭秘:无API抓取GitHub Trending的正则解析与SWR缓存设计

原创2026-11-08 11:46:362,219 阅读

CheckMyGit源码揭秘:无API抓取GitHub Trending的正则解析与SWR缓存设计

CheckMyGit 是一个把任意 GitHub 个人主页秒变可视化作品集的开源项目,它的 Explore 模块还提供 GitHub Trending 热榜。多数热榜实现依赖官方接口,而本项目走了一条"野路子":直接抓取 github.com/trending 的 HTML 页面,用正则表达式解析出榜单数据,再叠加一套基于 SWR(Stale-While-Revalidate,过期可重验)策略的边缘缓存。本文带你拆解 trending.ts 的核心逻辑,看看这套"零 API 依赖"的方案是如何做到又快又稳的。

CheckMyGit 深色模式作品集界面,展示 GitHub 贡献热力图、星标统计与技术栈图表

项目速览:CheckMyGit 是什么?

CheckMyGit 基于 SvelteKit + Tailwind CSS 构建,部署在 Cloudflare Pages 上。输入任意 GitHub 用户名,几秒内即可生成包含贡献图、语言占比、精选项目的个人作品集页面,支持三种模板和 PNG 导出。

在 explore/ 目录下,它还提供三个"数据窗口"页面:

  • Trending(+page.svelte):GitHub 热门仓库榜,本文主角
  • Rankings(+page.svelte):基于 GraphQL 接口的星标/粉丝排行
  • Globe(+page.svelte):全球开发者分布

有趣的是,三个页面的数据获取策略完全不同——Trending 页面恰好是"无 API 抓取"的代表。

为什么不用 GitHub API 抓 Trending?

答案很简单:GitHub 根本没有 Trending 接口。

github.com/trending 是一个普通 HTML 页面,官方 API(REST / GraphQL)都不提供"当前热门"数据。要实现热榜功能,通常有三条路:

  1. 爬 HTML 页面自己解析(本项目选择)
  2. 用第三方聚合服务(引入外部依赖)
  3. 用 GraphQL 按 stars:>1000 sort:stars 搜索近似模拟(本项目用作兜底)

方案一的好处是数据最"正宗"——能拿到 Trending 页独有的"今日新增 Star 数",这在 GraphQL 搜索接口里是拿不到的。代价则是:页面结构一变,正则就可能失效,所以整套代码围绕"解析失败怎么办"做了大量防御。

正则解析:从 HTML 到结构化数据

抓取请求的"伪装"

抓取逻辑在 fetchAndParse() 中。两个关键细节:

  • 自定义 User-Agent: CheckMyGit/1.0,声明身份而非冒用浏览器
  • 请求头携带 cf.cacheTtl 与 cacheEverything,让 Cloudflare 边缘节点顺带缓存原始 HTML,减少回源

语言和时间窗口通过 URL 拼接,例如 ?since=weekly 或 /trending/python?since=daily,构建逻辑见 buildTrendingUrl()。

七组正则,拆出整张榜单

解析的核心是 parseTrendingHtml(),思路分两步:先切片,再提取。

正则常量 作用
ARTICLE_RE 按 <article class="Box-row"> 把页面切成一个个仓库卡片
REPO_HREF_RE 从卡片标题链接中提取 owner/repo
DESC_RE 提取项目描述(HTML 转义文本)
LANG_NAME_RE 提取编程语言名称
LANG_COLOR_RE 提取语言标签的背景色(用于前端渲染色点)
STARS_RE / FORKS_RE 提取总 Star / Fork 数
PERIOD_STARS_RE 提取本期新增 Star 数(热榜的灵魂数据)

定义见 trending.ts#L30-L37。用 while + exec 循环遍历每个卡片块,逐块跑其余正则——比一次性对整页跑正则更省内存,也更易维护。

健壮性细节:优雅降级而非抛错

针对"页面结构变化"这一最大风险,代码做了多层防御:

  • 单个字段缺失不致命:描述、语言、周期 Star 解析失败时置 null 或 0,仅仓库链接缺失时才 continue 跳过该卡片
  • HTML 实体解码:decodeHtmlEntities() 处理描述文本中的 &amp;、&#39; 等转义
  • 千分位数字清洗:parseNumberWithCommas() 把 "12,345" 还原为数字
  • 零结果视为失败:解析出 0 个仓库会主动抛错(trending.ts#L153),避免把空榜单写进缓存污染后续请求

数据结构

解析结果统一映射为 TrendingRepository 类型:包含排名、仓库地址、描述、语言名+颜色、Star/Fork 总数、周期 Star 数等字段,与前端表格组件(TrendingTable.svelte)一一对应。

SWR 缓存设计:三级 TTL 策略

每个时间窗口独立的过期策略

缓存 TTL 定义在 TTL_BY_WINDOW,采用"新鲜期 + 可重验期"的 SWR 双阶段模型:

时间窗口 fresh(新鲜期,直接命中) swr(可重验期,先返回旧数据再后台刷新)
daily 1 小时 6 小时
weekly 6 小时 24 小时
monthly 24 小时 7 天

设计逻辑很直观:榜单数据变化越快,缓存越短。Daily 榜单一天内会多次"变天",所以新鲜期只有 1 小时;Monthly 榜单基本稳定,可放心缓存一整天。

写入缓存时,Cache-Control 头同时声明两个参数(trending.ts#L156-L161):

public, max-age=3600, stale-while-revalidate=21600

这正是 SWR 的精髓:在 max-age 内所有请求零开销;进入 stale-while-revalidate 窗口后,用户立刻拿到旧数据(不卡顿),边缘节点在后台悄悄回源刷新——用户永远感觉页面是"秒开"的。

缓存键:给 Daily 榜单加"日期戳"

buildCacheKey() 生成形如 trending/daily/all/2026-11-08 的键。注意一个巧思:只有 daily 窗口带日期后缀。

注释里写明了原因:daily 的 SWR 窗口长达 6 小时,如果不加日期,午夜过后 6 小时内用户看到的"今日热榜"实际上是昨天的数据;加上 UTC 日期后缀,跨天自然生成新键、强制回源。而 weekly / monthly 数据变化缓慢,靠 TTL 本身就够了,无需额外区分。

三条数据路径:live、cache、fallback

TrendingResult.source 字段只有三个取值,对应三种数据来源:

请求进来
  ├─ 缓存命中 ──────────► source: 'cache'(毫秒级返回)
  └─ 缓存未中 → 抓取+正则解析
        ├─ 成功 ────────► source: 'live'(顺手写缓存)
        └─ 失败 → GraphQL 兜底
              ├─ 成功 ──► source: 'fallback'(短 TTL 写入)
              └─ 失败 ──► success: false

GraphQL 兜底:失败不白失败

当 Trending 页面结构大改、正则全军覆没时,fetchTrendingLive() 会降级调用 fetchTopRepositories(),用 GitHub GraphQL 的 stars:>1000 sort:stars 搜索查询凑出一份"准热榜"。

兜底数据有一个刻意的设计:缓存 TTL 被压缩为 min(fresh, 1800)——最多 30 分钟。注释解释得很清楚:既不能太短(否则 Trending 页面故障期间每次请求都打爆 GraphQL API),也不能太长(要等页面结构修复后快速恢复正常数据)。

两种消费姿势:流式渲染 vs 阻塞读取

同一个数据源,页面和 API 走的是两套加载策略。

页面端:冷缓存也能"秒开"

页面加载器 explore/trending/+page.server.ts 的逻辑:

  1. 先查 tryCachedTrending()——纯缓存查找,查不到返回 null,绝不等网络
  2. 命中:整页 HTML 直接携带完整榜单数据(含 JSON-LD,利于 SEO)
  3. 未命中:把 fetchTrendingLive() 的 Promise 本身(不 await)塞进返回数据。SvelteKit 会立刻发出 HTML 外壳 + 骨架屏(TrendingTableSkeleton.svelte),数据就绪后前端再填充

CheckMyGit 浅色模式作品集展示 GitHub 开发者数据统计与项目贡献可视化

这就是"骨架屏流式加载":缓存热时快如闪电,缓存冷时也不白屏——用户最多看到 1 秒左右的加载动画。

API 端:简单粗暴地阻塞

JSON 接口 api/trending/+server.ts 调用的是组合函数 fetchTrending():先查缓存、未中则同步等抓取结果。API 调用方要的就是"给我一个结果",没有骨架屏可言,阻塞反而最简单。

💡 一个小细节:页面端写入缓存时用 waitUntil 把 caches.default.put() 挂到请求生命周期之外(trending.ts#L162-L164)——存缓存不阻塞响应返回,进一步压低首字节延迟。

值得抄进你项目的 5 个设计点

  1. SWR 双 TTL 按数据新鲜度分级:变化快的数据短 fresh + 短 swr,慢数据反之,一套表(TTL_BY_WINDOW)管全局
  2. 缓存键编码时间语义:daily 窗口加日期后缀,让"过期可重验"不会跨越业务边界(跨天)
  3. 解析失败 ≠ 服务失败:正则兜底链(HTML 抓取 → GraphQL 搜索 → 报错)层层降级,用户端几乎无感
  4. 兜底数据用更短的 TTL:30 分钟上限,兼顾保护上游 API 与快速恢复正常
  5. 冷热双路径加载:缓存命中返回完整 HTML,未命中流式 Promise + 骨架屏,两条路都体面

关键文件导航

文件 说明
trending.ts 核心:正则解析 + SWR 缓存 + 兜底链
explore/trending/+page.server.ts 页面加载器:缓存优先 + 流式冷加载
api/trending/+server.ts JSON API 端点
rankings.ts GraphQL 兜底数据源
trending.ts(类型) 时间窗口与结果类型定义
constants.ts 全站缓存常量(浏览量缓存的 TTL 配置)
TrendingTable.svelte 前端热榜表格组件

总结:CheckMyGit 的 Trending 实现证明了一个朴素的道理——没有现成 API 时,"抓 HTML + 正则 + 多层缓存"依然是生产级可用的方案。关键在于把"上游会变"当作第一假设:正则解析要容错、失败要有兜底、缓存要分级、兜底要快过期。这套组合拳,比任何单一技巧都更值得借鉴。

登录后查看全文
checkmygit