Defuddle 源码剖析:X(Twitter)文章作者提取的 URL 回退机制——以 issue 161 测试夹具为例

原创2026-10-14 13:35:381,333 阅读
文章标签:网页爬虫开发工具

Defuddle 源码剖析:X(Twitter)文章作者提取的 URL 回退机制——以 issue #161 测试夹具为例

本文以 Defuddle 仓库中 issue #161 的回归测试夹具(预期输出 与 HTML 输入)为切入点,剖析 XArticleExtractor 在 /status/:id URL 下、页面缺失结构化作者信息且 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>

关键事实有三个:

  1. 页面运行在 /status/:id URL 上,而非 /article/:id;页面主体是一个被服务端渲染到该 URL 的 X 文章(data-testid="twitterArticleRichTextView")。
  2. 页面没有 itemprop="author" 块,即缺失结构化的作者信息,无法通过语义标记直接读取作者。
  3. 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();
}

该正则有三个值得注意的设计点:

  1. 用户名约束:[a-zA-Z0-9_][a-zA-Z0-9_]{0,14} 限定用户名以字母/数字/下划线开头、总长不超过 15 个字符,与 X 的 handle 规则一致,避免误匹配路径中的其他片段。
  2. 双路径支持:同时匹配 /article/ 与 /status/ 两种路由,因为 X 文章既可能在 /article/:id 也可能(如本夹具所示)渲染在 /status/:id 上。
  3. 数字 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"。

进一步阅读建议:

登录后查看全文
defuddle