NewsBlur 对 JSON Feed 规范的完整支持:从内容协商到字段映射的实现解读

原创2026-10-14 18:16:351,433 阅读
文章标签:后端前端社交人工智能

NewsBlur 对 JSON Feed 规范的完整支持:从内容协商到字段映射的实现解读

2017 年 5 月,NewsBlur 官方博客宣布正式支持由 Manton Reece 与 Brent Simmons 发起的 JSON Feed 规范(详见仓库内的 官方公告原文)。本文以该公告为起点,结合当前仓库源码,完整还原 NewsBlur 对 JSON Feed 的接入方式:包括基于 Content-Type 的内容协商、JSON→Atom 的字段映射、WordPress REST JSON 兼容分支,以及订阅发现链路中的 JSON 探测,帮助读者理解这一“对读者透明、对开发者友好”的订阅格式究竟如何在 NewsBlur 内部落地。

JSON Feed:为避开 XML 而生的新规范

JSON Feed 是 RSS/Atom 之外的一种全新订阅格式,由开放网络倡导者 Manton Reece 和 Brent Simmons 于 2017 年 5 月提出。规范作者的原话是:

JSON 已经成为开发者在 API 领域的选择,开发者们往往愿意绕开 XML 走任何弯路。JSON 更易于读写,也更不容易引发 bug。

这一论断切中了传统订阅生态的痛点:RSS/Atom 基于 XML,格式啰嗦、解析繁琐,尤其是遇到编码问题(如字符集声明缺失、双重转义)时极易出错。而 JSON Feed 让站点可以直接用 JSON 发布文章列表,对发布者而言写作成本大幅降低,对阅读器而言解析也更为直接。

NewsBlur 官方公告的核心信息只有一句话:从 2017 年 5 月 23 日起,NewsBlur 正式支持 JSON Feed 规范,且用户无需做任何额外操作。如果一个网站以 JSON 格式同步发布文章,读者在 NewsBlur 上订阅、阅读这些内容的方式与订阅传统 RSS/Atom 完全一致——阅读体验无差异,但站点的发布成本却是数量级的下降。

抓取链路中的 JSON 识别:基于 Content-Type 的内容协商

NewsBlur 对 JSON Feed 的支持是“自动发现”式的,核心实现在 utils/feed_fetcher.py 的 FetchFeed.fetch() 中。抓取器在拿到 HTTP 响应后,首先检查 Content-Type 响应头:

  • application/feed+json(JSON Feed 规范的标准媒体类型)
  • application/json(宽松匹配,兼容未正确声明媒体类型的站点)

只要响应头命中其中任一值且响应体非空,就进入 JSON 分支(utils/feed_fetcher.py#L757-L784):

json_feed_content_type = any(
    json_feed in raw_feed.headers.get("Content-Type", "")
    for json_feed in ["application/feed+json", "application/json"]
)
if raw_feed.content and json_feed_content_type:
    # JSON Feed
    json_feed = self.fetch_json_feed(address, raw_feed)
    ...
    self.fpf = feedparser.parse(processed_json_feed)
    # Inject HTTP metadata for JSON feeds too
    self.fpf["status"] = raw_feed.status_code
    etag_header = raw_feed.headers.get("ETag")
    if etag_header:
        self.fpf["etag"] = etag_header
    modified_header = raw_feed.headers.get("Last-Modified")
    if modified_header:
        self.fpf["modified"] = modified_header

这段实现有几个值得注意的细节:

  1. 转换后统一走 feedparser:JSON 正文先经 JSONFetcher 转换为 Atom XML,再交给 feedparser.parse(),与后续的 XML 解析管线完全打通——这正是“对读者透明”的底层原因。
  2. 注入 HTTP 缓存元数据:JSON 分支同样把 ETag、Last-Modified 写回解析结果,使 JSON Feed 也能参与 NewsBlur 的增量抓取与 304 缓存判定,不会因为格式差异丢失带宽优化。
  3. 编码预处理兜底:转换后的 Atom 字符串会经过 preprocess_feed_encoding()(utils/feed_fetcher.py#L104-L143)。该函数原本用于修复 The Verge 等站点常见的“UTF-8 字节被误读为 Latin-1/Windows-1252 再被 HTML 转义”问题(例如 Apple’s),对 JSON 转换结果同样生效,进一步降低解析出错概率。

核心转换器:JSONFetcher 的字段映射全解

JSON Feed 到 Atom 的转换由 utils/json_fetcher.py 中的 JSONFetcher 类完成。fetch() 方法先读取 JSON 根对象,再构造 Django 的 feedgenerator.Atom1Feed:

data = {}
data["title"] = json_feed.get("title", "[Untitled]")
data["link"] = json_feed.get("home_page_url", "")
data["description"] = json_feed.get("title", "")
data["lastBuildDate"] = datetime.datetime.utcnow()
data["generator"] = "NewsBlur JSON Feed - %s" % settings.NEWSBLUR_URL
data["feed_url"] = json_feed.get("feed_url")

rss = feedgenerator.Atom1Feed(**data)
for item in json_feed.get("items", []):
    story_data = self.json_feed_story(item)
    rss.add_item(**story_data)
return rss.writeString("utf-8")

Feed 级字段映射如下:

JSON Feed 字段 映射到的 Atom 字段 说明
title title / description 缺失时回退为 [Untitled]
home_page_url link 站点主页 URL
feed_url feed_url Feed 自身的 URL
— lastBuildDate 使用抓取时刻的 UTC 时间
items 逐条 add_item() 通过 json_feed_story() 逐条转换

单篇文章的字段映射在 json_feed_story()(utils/json_fetcher.py#L137-L155)中完成,是理解“JSON 写的省力、读的省心”的关键:

def json_feed_story(self, item):
    date_published = datetime.datetime.now()
    pubdate = item.get("date_published") or item.get("date_modified")
    if pubdate:
        date_published = dateutil.parser.parse(pubdate)
    authors = item.get("authors", item.get("author", {}))
    if isinstance(authors, list):
        author_name = ", ".join([author.get("name", "") for author in authors])
    else:
        author_name = authors.get("name", "")
    story = {
        "title": item.get("title", ""),
        "link": item.get("external_url", item.get("url", "")),
        "description": item.get("content_html", item.get("content_text", "")),
        "author_name": author_name,
        "categories": item.get("tags", []),
        "unique_id": str(item.get("id", item.get("url", ""))),
        "pubdate": date_published,
    }
    return story

映射要点与默认值行为:

  • external_url 优先于 url:JSON Feed 规范中 external_url 用于指向外部原文,url 则指向 Feed 内页面;NewsBlur 优先采用 external_url,保证读者点开的是原始文章。
  • content_html 优先于 content_text:有富文本正文时使用 content_html,否则回退到纯文本 content_text,与规范“二者择一”的建议一致。
  • 作者兼容两种写法:规范要求 authors 为数组(V1.1),旧版允许 author 为对象(V1);代码对 list 与对象两种形态均做了兼容,数组时以 , 连接多个作者。
  • 发布时间回退链:优先 date_published,其次 date_modified,均缺失时使用当前时间;日期解析借助 dateutil.parser,能容忍多种 ISO 8601 变体。
  • tags 直接映射为分类:JSON Feed 的 tags 字符串数组原样成为 Atom 的 categories,读者在 NewsBlur 中可按标签筛选。

意外的兼容分支:WordPress REST API JSON

JSONFetcher 还内置了一个超出 JSON Feed 规范的兼容分支:当解析出的 JSON 是一个数组而非对象,且首元素满足 title 为对象、含 rendered 键、同时存在 link 键时(is_wp_json() 判定,utils/json_fetcher.py#L46-L56),会被识别为 WordPress REST API 的 /wp-json/wp/v2/posts 响应,转而走 fetch_wp_json() 转换流程:

  • 站点标题取自 URL 的主机名,link 取协议与主机部分;
  • 正文优先取 content.rendered,缺失时回退到 excerpt.rendered;
  • 若 _embedded.wp:featuredmedia 提供特色图且未包含在正文中,会在正文前拼接 <img> 标签;
  • 作者从 _embedded.author[0].name 提取,分类从 _embedded.wp:term 分组中汇总。

这一分支意味着 NewsBlur 不仅能订阅规范的 JSON Feed,还能直接消化部分 WordPress 站点暴露的 REST JSON 接口,进一步降低站点接入成本。对应的抓取入口在 apps/rss_feeds/models.py#L935-L955:订阅发现时若请求返回的 Content-Type 含 application/json,会直接以该 URL 创建 Feed 记录,再由抓取管线完成后续解析。

订阅发现链路:让 JSON Feed 被“找得到”

除了抓取阶段的内容协商,NewsBlur 在发现/订阅环节也全面纳入了 JSON 形态,相关逻辑集中在 utils/feedfinder_forman.py:

  1. 正文判定:is_feed_data() 通过统计 <rss、<rdf、<feed 以及字符串 jsonfeed.org 的出现次数判断一段文本是否为 Feed——JSON Feed 的 version 字段固定为 https://jsonfeed.org/version/1 或 /1.1,因此这一特征串可直接命中。
  2. URL 后缀识别:is_feed_url() 将 .json 列入后缀白名单(与 .rss、.rdf、.xml、.atom 并列),is_feedlike_url() 也会把含 json 的 URL 视为潜在 Feed。
  3. 页面扫描:find_feeds() 在解析 <link> 标签时,将 application/json 纳入可接受类型;在猜测常见 Feed 路径时,index.json 也出现在候选文件名列表中(utils/feedfinder_forman.py#L124-L131 与 L168)。
  4. 精确判定:url_is_feed()(utils/feedfinder_forman.py#L83-L98)只回答“该 URL 返回的文档本身就是 Feed 吗”,用于 Web Feed 流程中将真实 Feed URL 转交给普通订阅,JSON Feed 同样适用。

测试用例佐证:两处关键验证

仓库内的测试明确印证了上述实现:

  • apps/rss_feeds/test_rss_feeds.py#L1414-L1432 的 test_json_feed_over_https_is_tagged_for_migration:模拟 http:// 地址失效、https:// 地址返回 Content-Type: application/feed+json 且正文为 {"version": "https://jsonfeed.org/version/1.1"} 的 JSON Feed,验证抓取器能识别 JSON Feed 并将其地址标记为可升级为 HTTPS 迁移。
  • apps/webfeed/tests.py#L420-L441 定义了 JSON_FEED = '{"version":"https://jsonfeed.org/version/1","title":"X","items":[{"id":"1"}]}',test_json_feed_url_is_feed 验证 url_is_feed() 对 JSON Feed URL 返回 True,与 Atom、RSS 测试并列,确认 JSON Feed 在订阅发现链路中与 XML 家族地位等同。

读者视角:如何亲自体验

按照官方公告,体验方式极其简单:找到任何一个提供 JSON Feed 的站点,把其 feed.json(或类似)地址直接粘贴到 NewsBlur 的添加订阅框中即可。公告中举的示例是 Daring Fireball 的 JSON Feed 地址,其浏览器直接打开时的可读性也优于 XML 版本——JSON 本身就是给人读的设计。

对普通读者而言,整个流程与订阅 RSS/Atom 没有任何区别:NewsBlur 在后台自动完成 Content-Type 检测、JSON→Atom 转换与 feedparser 解析,最终呈现的是无差别的阅读体验。而对站点开发者而言,产出 JSON Feed 比维护 XML 模板简单一个数量级——这正是该规范“降低发布成本、保持开放网络”初衷的体现,也是 NewsBlur 当年第一时间接入的原因。

登录后查看全文
NewsBlur