rss-feeds缓存与增量更新机制揭秘:merge_entries如何做到不重复、不丢历史文章
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 阅读器。
二、为什么必须搞"缓存 + 增量更新"?
如果每次运行都把博客的所有页面从头抓一遍,会有三个问题:
- 慢且浪费:一个博客可能有几十页历史文章,每小时全量抓一次纯属浪费;
- 请求过多:对源站不友好,容易触发限流(HTTP 429);
- 身份不稳:如果每次重新生成 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(),流程一目了然:
- 读缓存:
load_cache()+deserialize_entries(),把 JSON 还原成带日期对象的条目; - 判断模式:没有缓存(或显式
--full)→ 抓取全部页面;有缓存 → 只抓第 1 页(增量模式); - 空抓取熔断:第 1 页一篇都没解析出来时,require_posts() 直接抛
ValueError——拒绝用旧缓存假装成功,防止"网站改版导致静默失败"; - 合并:
merge_entries(新文章, 缓存文章)得到去重后的完整列表; - 历史兜底:
merge_feed_history()再和已发布的 XML 对齐,保住 URL 迁移的老文章; - 原子发布:
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。
这套模式(抓取 → 缓存 → 合并 → 校验 → 原子发布)对任何做内容聚合的项目都很实用,值得借鉴。