rss-feeds缓存与增量更新机制揭秘:merge_entries如何做到不重复、不丢历史文章

原创2026-11-03 20:25:431,753 阅读

rss-feeds缓存与增量更新机制揭秘:merge_entries如何做到不重复、不丢历史文章

rss-feeds 是一个为没有 RSS 源的博客自动生成 RSS Feed 的开源项目。本文带你揭秘它的核心机制:缓存(cache)+ 增量更新,以及 merge_entries 函数如何做到"文章不重复、历史不丢失、订阅者 GUID 不变"。

一、先认识这个项目

很多你常看的博客(Cursor、Weaviate、xAI 等)根本不提供 RSS 源。rss-feeds 的思路很简单:

  • 每个博客对应一个 Python 生成脚本,存放在 feed_generators/
  • 定时任务每小时运行一次,抓取博客页面并生成 XML
  • 生成的 Feed 保存在 feeds/ 目录,例如 feed_cursor.xml
  • 所有 Feed 的注册信息集中在 feeds.yaml 这份"单一事实来源"里

📌 你可以直接把任意一个 feed_*.xml 的原始链接订阅到自己的 RSS 阅读器。

二、为什么必须搞"缓存 + 增量更新"?

如果每次运行都把博客的所有页面从头抓一遍,会有三个问题:

  1. 慢且浪费:一个博客可能有几十页历史文章,每小时全量抓一次纯属浪费;
  2. 请求过多:对源站不友好,容易触发限流(HTTP 429);
  3. 身份不稳:如果每次重新生成 GUID,订阅者的 RSS 阅读器会认为"老文章全变了、新文章又出现",体验极差。

rss-feeds 的解法是:首次全量抓取并落盘缓存,之后只抓第 1 页(最新文章),再和缓存合并。

三、三层"记忆体":JSON 缓存、历史档案、发布 XML

项目里其实有三份数据在协作,各司其职:

层级 文件位置 职责 加载函数
🗂️ 工作缓存 cache/<feed>_posts.json(gitignore,本地生成) 存放最近一次合并后的文章列表,增量更新的基础 load_cache()
📚 历史档案 feeds/feed_*.xml 已发布的 XML 即使 JSON 缓存丢了,也能从已发布的 Feed 里恢复全部历史文章 load_feed_history()
📢 发布产物 feeds/feed_*.xml 给订阅者拉取,由 save_rss_feed() 原子写入 —

关键设计:

  • load_cache() 读缓存时容错——文件损坏就告警并从零开始(utils.py);
  • save_cache() 自动把 datetime 序列化成 ISO 字符串落盘,读取时再由 deserialize_entries() 还原回真正的日期对象——这一步很关键,ISO 字符串直接参与排序会得到错误顺序(这也是 AGENTS.md 里的硬性规定);
  • 对于博客改版/迁移导致的 URL 变化,feed_history.py 提供了 merge_feed_history(),可以按旧 URL 甚至文章标题找回老文章,并沿用旧的 GUID,让订阅者无感知。

四、merge_entries 逐行拆解:去重、刷新、GUID 保护

merge_entries() 是整个增量更新的心脏,逻辑只有三步:

# 1. 以"链接"为身份,把缓存文章放进字典(天然去重)
merged = {entry[id_field]: entry for entry in deserialize_entries(cached_entries)}

# 2. 新抓的文章逐条覆盖进去;元数据刷新,但 GUID 保持不变
for entry in deserialize_entries(new_entries):
    previous = merged.get(entry[id_field], {})
    merged[entry[id_field]] = {**previous, **entry}
    if previous.get("guid"):
        merged[entry[id_field]]["guid"] = previous["guid"]

# 3. 排序(新文章在前)后返回
return sort_posts_for_feed(list(merged.values()), date_field=date_field)

三步各自解决一个问题:

  • 不重复:用 link(URL)作为字典键,新抓的和缓存里的同一篇文章只会保留一条记录;
  • 不丢历史:缓存里的老文章先整体装入字典,新文章只"追加或覆盖",绝不会把历史条目挤掉;
  • 订阅者身份稳定:如果缓存中已有 GUID,合并后强制沿用旧 GUID,即使抓取到的新数据里 GUID 不同。老文章的标题、描述、摘要会被新数据刷新,但 RSS 阅读器看到的"文章指纹"不变,不会重复弹出"更新"。

排序交给 sort_posts_for_feed(),它有一个反直觉的细节:feedgen 写 XML 时会反转顺序,所以这里故意按"旧→新"升序排,最终 Feed 里就是"新→旧"。日期相同的文章还会按 GUID/链接二次排序,保证输出稳定。

对应的离线测试在 test_publication.py:

def test_cache_deduplicates_and_refreshes_without_changing_guid(self):
    ...
    merged = merge_entries([new, new], [old, old])
    self.assertEqual(len(merged), 1)          # 重复条目被合并成 1 条
    self.assertEqual(merged[0]["guid"], "stable")  # GUID 保持旧值

五、一次增量更新的完整流程(以 Cursor Blog 为例)

打开 cursor_blog.py 的 main(),流程一目了然:

  1. 读缓存:load_cache() + deserialize_entries(),把 JSON 还原成带日期对象的条目;
  2. 判断模式:没有缓存(或显式 --full)→ 抓取全部页面;有缓存 → 只抓第 1 页(增量模式);
  3. 空抓取熔断:第 1 页一篇都没解析出来时,require_posts() 直接抛 ValueError——拒绝用旧缓存假装成功,防止"网站改版导致静默失败";
  4. 合并:merge_entries(新文章, 缓存文章) 得到去重后的完整列表;
  5. 历史兜底:merge_feed_history() 再和已发布的 XML 对齐,保住 URL 迁移的老文章;
  6. 原子发布:save_rss_feed() 先校验(缺日期、重复 link/GUID、空 Feed 全部拒绝),只有内容真的变化时才替换文件;只变 lastBuildDate 则保留原字节,避免产生无意义的提交。

上层调度由 run_all_feeds.py 统一把关:生成脚本超时(10 分钟)、退出码非 0、输出文件没被刷新、XML 校验失败,都会被判定为失败并写入 CI 报告——"退出码 0 但什么都没写"这种假成功是过不了关的。

六、边界防御:那些容易被忽略的细节

  • 坏日期不炸:缓存里的日期无法解析时,stable_fallback_date() 用 URL/标题的哈希算出一个固定的兜底日期——同一篇文章每次算出来都一样,不会引起缓存反复抖动;
  • 时区归一:老缓存里的"裸日期"(无时区)会被统一补成 UTC(见 测试用例),避免新旧条目比较时 TypeError;
  • 发布前二次去重:save_rss_feed() 在 XML 层面再按 link 和 GUID 去重一遍,并给缺失 GUID 的条目补上 isPermaLink="false" 的兜底值(utils.py);
  • 原子替换:新内容先写临时文件再 os.replace() 覆盖目标,校验失败时旧 XML 原封不动(docs/feed-reliability.md 的"Validation boundaries"一节有完整说明)。

七、动手体验:本地跑一个 Feed

想亲眼看看这套机制?三步即可:

git clone https://gitcode.com/gh_mirrors/rs/rss-feeds
cd rss-feeds
uv run feed_generators/run_all_feeds.py --feed cursor

第一次运行会全量抓取并在 cache/ 生成 cursor_posts.json;再跑一次,日志里就会看到 Running incremental update (page 1 only)——增量模式生效了。

离线验证(不需要网络):

make dev_test_unit
uv run feed_generators/validate_feeds.py

八、小结

rss-feeds 的缓存与增量更新机制可以浓缩成四句话:

  • 🔁 增量抓取:有缓存只抓第 1 页,省请求、低延迟;
  • 🧩 字典合并:merge_entries() 以 URL 为键,天然去重、刷新元数据;
  • 🆔 GUID 锁定:老文章身份永远不变,订阅阅读器零打扰;
  • 🛡️ 层层兜底:空抓取熔断、历史 XML 恢复、发布前校验、原子写入,任何一环失败都不会污染已发布的 Feed。

这套模式(抓取 → 缓存 → 合并 → 校验 → 原子发布)对任何做内容聚合的项目都很实用,值得借鉴。

登录后查看全文
rss-feeds