Defuddle 源码剖析:X(Twitter)文章作者提取的 URL 回退机制——以 issue 161 测试夹具为例
Defuddle 源码剖析:X(Twitter)文章作者提取的 URL 回退机制——以 issue #161 测试夹具为例
本文以 Defuddle 仓库中 issue #161 的回归测试夹具(预期输出 与 HTML 输入)为切入点,剖析
XArticleExtractor在/status/:idURL 下、页面缺失结构化作者信息且og:title被本地化时的作者提取回退链。读完本文,你将掌握 Defuddle 站点提取器(site extractor)的变量注入、URL 正则解析、og:title兜底策略以及 fixture 测试的 hermetic 设计原理。
一、夹具速览:一条没有作者标记的本地化 X 页面
tests/expected/issues--161-x-status-url-author.md 是 Defuddle fixture 测试的预期输出文件,其内容非常简洁,仅包含一段 JSON 元数据前言和正文 Markdown:
{
"title": "Lorem Ipsum Dolor Sit Amet",
"author": "@janedoe",
"site": "X (Twitter)",
"published": ""
}
Lorem Ipsum Dolor Sit Amet
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
这份预期输出看似简单,背后却对应一个真实的提取难题。其配套输入 tests/fixtures/issues--161-x-status-url-author.html 的开头注释完整交代了场景:
<!-- {"url":"https://x.com/janedoe/status/1234567890123456789"} -->
<!-- X article rendered on a /status/:id URL with a localized og:title.
No itemprop="author" block is present, so author must be extracted
from the URL. getAuthorFromOgTitle() would return "Unknown" here
because the title is not in the English "Name on X: ..." format. -->
<html lang="ja">
<head>
<meta charset="UTF-8">
<title>Jane Doe さんの記事</title>
<meta property="og:title" content="Jane DoeさんはXを使っています:「記事のタイトル」">
</head>
关键事实有三个:
- 页面运行在
/status/:idURL 上,而非/article/:id;页面主体是一个被服务端渲染到该 URL 的 X 文章(data-testid="twitterArticleRichTextView")。 - 页面没有
itemprop="author"块,即缺失结构化的作者信息,无法通过语义标记直接读取作者。 og:title是日语本地化格式Jane DoeさんはXを使っています:「記事のタイトル」,不是英文的Name on X: ...形态,因此getAuthorFromOgTitle()会解析失败并返回"Unknown"。
三者叠加后,提取器唯一可靠的作者来源就是 URL 本身——/janedoe/status/... 路径段中的用户名。预期输出中 "author": "@janedoe" 正是这一策略生效的验证结果。
二、源码级回退链:作者提取的四级防线
作者提取的核心实现在 src/extractors/x-article.ts。XArticleExtractor 先定位容器,再依次走三级回退:
private extractAuthor(): string {
const authorContainer = this.document.querySelector(SELECTORS.AUTHOR);
if (!authorContainer) return this.getAuthorFromUrl();
const name = authorContainer.querySelector(SELECTORS.AUTHOR_NAME)?.getAttribute('content');
const handle = authorContainer.querySelector(SELECTORS.AUTHOR_HANDLE)?.getAttribute('content');
if (name && handle) return `${name} (@${handle})`;
return name || handle || this.getAuthorFromUrl();
}
提取逻辑为(按优先级从高到低):
| 优先级 | 来源 | 说明 |
|---|---|---|
| 1 | [itemprop="author"] 容器内的 meta[itemprop="name"] + meta[itemprop="additionalName"] |
二者齐备时输出 姓名 (@handle) 格式;只有其一则取其值 |
| 2 | URL 路径 | getAuthorFromUrl(),从 URL 中提取用户名并补 @ 前缀 |
| 3 | og:title 内容 |
getAuthorFromOgTitle(),仅识别英文 Name on X: ... 格式,否则返回 "Unknown" |
issue #161 的夹具正好卡在第一级缺失、第三级失效的场景,从而验证第二级(URL)能够正确兜底。这也是该测试的核心价值:确保 X 调整页面渲染(本地化 og:title、移除 itemprop 块)时,作者信息不会悄悄退化为 "Unknown"。
三、URL 正则解析:getAuthorFromUrl() 的实现细节
private getAuthorFromUrl(): string {
// match username before /article/ or /status/, excluding system paths like /i/
const match = this.url.match(/\/([a-zA-Z0-9_][a-zA-Z0-9_]{0,14})\/(article|status)\/\d+/);
return match ? `@${match[1]}` : this.getAuthorFromOgTitle();
}
该正则有三个值得注意的设计点:
- 用户名约束:
[a-zA-Z0-9_][a-zA-Z0-9_]{0,14}限定用户名以字母/数字/下划线开头、总长不超过 15 个字符,与 X 的 handle 规则一致,避免误匹配路径中的其他片段。 - 双路径支持:同时匹配
/article/与/status/两种路由,因为 X 文章既可能在/article/:id也可能(如本夹具所示)渲染在/status/:id上。 - 数字 ID 收尾:要求以
/\d+结束,防止把x.com/explore之类的系统路径当作用户名。
对本夹具 URL https://x.com/janedoe/status/1234567890123456789,正则捕获组 1 得到 janedoe,函数返回 @janedoe,与预期输出一致。若 URL 中也没有可匹配的用户名(例如 x.com/i/... 系统路径),则继续回退到 getAuthorFromOgTitle()。
四、og:title 兜底与 "Unknown" 边界:为什么本地化标题会失败
private getAuthorFromOgTitle(): string {
const ogTitle = this.document.querySelector('meta[property="og:title"]')?.getAttribute('content') || '';
// Match patterns like "(4) Heinrich on X: ..." or "Heinrich on X: ..."
const match = ogTitle.match(/^(?:\(\d+\)\s+)?(.+?)\s+on\s+X\s*:/);
return match ? match[1].trim() : 'Unknown';
}
该函数只识别两种英文形态:Heinrich on X: ... 与带计数前缀的 (4) Heinrich on X: ...(后者出现在会话时间线场景)。日语标题 Jane DoeさんはXを使っています:「記事のタイトル」 中不存在 on X: 分隔符,因此匹配失败,函数返回 'Unknown'。
这解释了夹具注释中 "getAuthorFromOgTitle() would return "Unknown" here" 的含义:若没有 URL 回退层,本次提取的作者会退化为无意义的 "Unknown"。extractAuthor() 的返回值随后被写入 extract() 返回的 variables:
variables: {
title,
author,
site: 'X (Twitter)',
description,
}
五、fixture 测试机制:hermetic 与元数据前言格式
这份预期文件由 tests/fixtures.test.ts 驱动,测试框架自动发现 tests/fixtures/ 下所有 .html 文件,用 Defuddle 解析后与 tests/expected/ 下的同名 .md 预期文件逐字比对。
元数据前言(preamble)
预期文件的 JSON 块并非人工维护,而是由 createComparableResult() 生成的固定格式(tests/fixtures.test.ts):
function createComparableResult(response: DefuddleResponse): string {
const metadataOnly = {
title: response.title,
author: response.author,
site: response.site,
published: response.published,
};
const jsonPreamble = '```json\n' + JSON.stringify(metadataOnly, null, 2) + '\n```\n\n';
return jsonPreamble + response.contentMarkdown;
}
即只取 title / author / site / published 四个元数据字段 + Markdown 正文。对 X 文章提取而言:title 来自 extractTitle()([data-testid="twitter-article-title"] 的文本,此处为 "Lorem Ipsum Dolor Sit Amet");author 来自本文剖析的回退链;site 恒为 'X (Twitter)';published 为空字符串——因为 XArticleExtractor 的 variables 不提供 published 字段,最终回落到页面元数据(此夹具页面不含可用的发布日信息)。
hermetic 网络隔离
测试还刻意保持夹具"离线自洽"(tests/fixtures.test.ts):
// Keep fixtures hermetic: extractors for /status/<id> URLs (e.g. X) otherwise
// hit publish.twitter.com/api.fxtwitter.com over the live network, which is slow
// and nondeterministic — a placeholder id can collide with a real tweet (see #272,
// where 1234567890 resolved to a real account). Failing the fetch forces the
// deterministic DOM-extraction path the fixtures are written to exercise.
const offlineFetch = (() => Promise.reject(new Error('network disabled in fixture tests'))) as unknown as typeof fetch;
const response = await Defuddle(doc, url, { separateMarkdown: true, fetch: offlineFetch });
/status/:id 类的 URL 会命中 X 的异步提取器(x-oembed.ts 中的 canExtractAsync() 对 /status|article/\d+ 返回 true,prefersAsync() 在 DOM 无渲染推文时优先走网络路径),真实测试中会请求 publish.twitter.com/oembed 与 api.fxtwitter.com。为避免慢速、不确定的联网(占位 ID 甚至可能解析成真实账号,参见 issue #272),fixture 测试注入一个永远 reject 的 offlineFetch,强制走确定性的 DOM 提取路径——这正是 options.fetch 可注入能力(定义于 src/extractors/_base.ts)的典型应用。
六、注册优先级:XArticleExtractor 为何先于 TwitterExtractor
作者回退链能被触发的前提是 XArticleExtractor 正确接管了本页面。这依赖 src/extractor-registry.ts 中的注册顺序:
// X Article extractor must be registered BEFORE Twitter to take priority
// DOM-based canExtract() determines if page has article content
this.register({
patterns: ['x.com', 'twitter.com'],
extractor: XArticleExtractor
});
this.register({
patterns: ['twitter.com', /\/x\.com\/.*/],
extractor: TwitterExtractor
});
两个提取器的 URL 模式都覆盖 x.com/twitter.com,区别在于 canExtract():XArticleExtractor 检查 <a href="https://link.gitcode.com/i/3a129afedd9baa6e7e5f2872558aeea4" target="_blank">data-testid="twitterArticleRichTextView"] 容器([src/extractors/x-article.ts),而 TwitterExtractor 检查推文 article<a href="https://link.gitcode.com/i/dc5a99ca7b2c94dd013e88492e68d25e" target="_blank">data-testid="tweet"]。注册表按顺序实例化并调用 canExtract()([src/extractor-registry.ts),因此含文章渲染容器的页面总是优先交给 XArticleExtractor——本夹具的 HTML 正包含该容器,从而进入 X 文章作者回退路径。
七、从 variables 到响应:作者元数据如何进入输出
最终 "author": "@janedoe" 出现在预期文件里,经历了 src/defuddle.ts 的 buildExtractorResponse() 装配:
author: extracted.variables?.author || metadata.author,
站点提取器返回的 variables 优先于通用页面元数据。STANDARD_VARIABLE_KEYS(src/defuddle.ts)定义了可从提取器变量映射到顶层响应字段的键集合(title / author / published / site / description / image / language),其中 author 与 site 正是本夹具验证的两项。同时,提取器的 HTML 输出会经过 _sanitizeExtractorHtml()(src/defuddle.ts)的 DOM 级清理与相对 URL 解析,确保提取器模板字符串拼接出的标记与主流水线一样安全。
八、总结与延伸
issue #161 的测试夹具以极小成本锁定了一条重要行为契约:X 文章的作者提取必须形成 itemprop → URL → og:title 的完整回退链,且 URL 回退不依赖 og:title 的本地化形态。当 X 调整页面渲染(本地化标题、移除结构化作者标记)时,Defuddle 仍能从 URL 路径稳定还原 @handle,而非退化为 "Unknown"。
进一步阅读建议:
- 完整的提取器实现:src/extractors/x-article.ts,除作者外还包含 Draft.js 段落转换、嵌入推文 blockquote 化、代码块语言提取、图片质量升级等逻辑;
- X 推文(非文章)的 DOM 提取与回复树构建:src/extractors/twitter.ts;
- X 异步网络提取(oEmbed / FxTwitter 兜底):src/extractors/x-oembed.ts;
- fixture 测试整体机制与新增/更新预期文件的方法:tests/fixtures.test.ts;
- 提取器输出类名白名单(
x-article、quoted-post等的存活契约):src/utils/comments.ts。