如何快速升级Feedsmith 3.0:破坏性变更完整清单与2.x迁移步骤指南

原创2026-11-13 15:07:111,630 阅读

如何快速升级Feedsmith 3.0:破坏性变更完整清单与2.x迁移步骤指南

Feedsmith 是一款快速、一站式的 JavaScript feed 解析器与生成器,支持 RSS、Atom、RDF 和 JSON Feed,并兼容主流命名空间与 OPML。3.0 版本已正式发布:它在解析精度、类型安全和错误处理上做了大量改进,但同时也引入了一批破坏性变更(Breaking Changes)。本文为你整理一份完整的变更清单,并给出从 Feedsmith 2.x 升级到 3.0 的分步迁移指南,帮你少走弯路、平滑完成 feed 解析库的升级。

3.0 最大的变化:宽松模式成为默认 🔄

2.x 中,生成函数默认强制校验规范必填字段,想让所有字段可选必须显式传 { lenient: true }。3.0 完全反转了这个逻辑:

  • 默认宽松:所有字段可选,日期字符串也能直接传入
  • 严格模式改为选开:需要编译期校验必填字段时,显式传 { strict: true }
// 2.x 中这样写是"宽松模式"
generateRssFeed(data, { lenient: true })

// 3.0 中默认就是宽松,想要严格则改为:
generateRssFeed(data, { strict: true })

[!IMPORTANT] 如果你的项目依赖 2.x 的默认严格行为,迁移时务必把关键生成调用补上 { strict: true },否则 TypeScript 将不再帮你拦截缺失的必填字段。

严格模式的详细用法见官方文档 docs/generating/strict-mode.md。

迁移检查清单:照着做不遗漏 ✅

官方迁移指南 docs/migration/v2-to-v3.md 给出了完整检查项,这里浓缩为 6 步:

步骤 操作
1 更新依赖:npm install feedsmith@latest
2 移除所有 { lenient: true }(已是默认行为)
3 需要严格校验的地方改为传 { strict: true }
4 把 feedsmith/types 的导入全部改为从 feedsmith 主入口导入
5 按下方清单修正 Atom 文本字段、RSS 人物字段和各命名空间字段
6 重命名类型:Rss → RssFeed、Atom → AtomFeed、Json → JsonFeed、Rdf → RdfFeed

安装与版本信息可参考 README.md 和 package.json。

类型系统变更:三处需要手动修改 🧩

1. DeepPartial 工具类型被移除

3.0 中所有类型字段默认就是可选的,因此不再需要 DeepPartial 包裹,直接使用基础类型即可:

// 2.x
import type { DeepPartial, Rss } from 'feedsmith/types'
const processFeed = (feed: DeepPartial<Rss.Feed<string>>) => { ... }

// 3.0
import type { RssFeed } from 'feedsmith'
const processFeed = (feed: RssFeed.Feed<string>) => { ... }

2. feedsmith/types 入口被移除

所有类型现在统一从主包 feedsmith 导出。同时 2.x 的泛型别名(如 RssFeed<TDate>)已移除,改为命名空间下的 .Feed<TDate> 形式。

3. 需要编译期强制必填时,追加 true 类型参数

// 宽松(默认):字段全可选
const entry: AtomFeed.Entry<Date> = { title: { value: 'Post' } }

// 严格:编译期强制 id / title / updated 等必填字段
const strictEntry: AtomFeed.Entry<Date, true> = {
  id: 'https://example.com/post/1',
  title: { value: 'Post' },
  updated: new Date('2024-01-01'),
}

Atom 解析变更:文本从字符串变成对象 📝

这是 3.0 中对业务代码影响最大的变更。2.x 会把 Atom 的文本字段"拍平"成纯字符串,导致 type、src 等属性丢失;3.0 改为使用完整的 AtomFeed.Text / AtomFeed.Content 对象,完整保留属性信息(类型定义见 src/feeds/atom/common/types.ts)。

受影响字段:

位置 字段
Feed / Entry / Source title、subtitle、rights、summary
Entry content

修改方式很机械:

// 读取:改为 .value
const title = feed.title?.value            // 2.x 中是 feed.title(string)
const content = feed.entries?.[0]?.content?.value

// 生成:字符串改为对象
generateAtomFeed({
  title: { value: 'My Blog' },
  entries: [{ content: { value: '<p>Hello</p>', type: 'html' } }],
})

额外收益:type: 'xhtml' 的内容现在按 RFC 4287 规范解析为纯 HTML——自动剥掉包裹的 <div>、去掉 xhtml: 前缀,你的旧清洗代码可以删掉了。

RSS 人物字段:字符串 → 结构化对象 👤

managingEditor、webMaster 和 item 的 authors 字段,2.x 中是 'editor@example.com (Editor Name)' 这样的裸字符串,3.0 中变为 RssFeed.Person 对象:

// 读取
const editor = feed.managingEditor // { email: 'editor@example.com', name: 'Editor Name' }

// 生成
generateRssFeed({
  managingEditor: { email: 'editor@example.com', name: 'Editor Name' },
  items: [{ authors: [{ email: 'john@example.com', name: 'John Doe' }] }],
})

[!NOTE] RssFeed.Person 上的 link 属性仅用于解析(从字符串中的 URL 提取),生成时不会输出到 XML。

命名空间字段改名清单 📦

2.x 中标记为弃用的字段在 3.0 中正式移除,以下是三类命名空间的改名对照表(类型源码分别在 src/namespaces/media/、src/namespaces/podcast/、src/namespaces/dc/ 与 src/namespaces/dcterms/):

Media 命名空间(Media RSS)

2.x 3.0
media.group media.groups?.[0]

Podcast 命名空间(Podcasting 2.0)

2.x 3.0
podcast.location podcast.locations?.[0]
podcast.value podcast.values?.[0]
podcast.chats?.[0] podcast.chat

Dublin Core / Dublin Core Terms

这两个命名空间遵循"所有元素可重复"的规范,单数字段统一改为复数数组:

  • dc.title → dc.titles?.[0]、dc.creator → dc.creators?.[0]、dc.date → dc.dates?.[0](subject、description、publisher、language 等全部同理)
  • 名字保留但变为数组的字段:dc.coverage → dc.coverage?.[0]、dcterms.created → dcterms.created?.[0]

如果你的项目没有用到这些命名空间,这一步可以直接跳过。

3.0 的新能力:升级顺便用起来 ✨

① 专用错误类型 —— 不再只能 catch 泛型 Error,源码见 src/common/errors.ts:

错误类型 抛出时机
DetectError 输入不匹配预期的 feed 格式
MalformedError 内容畸形(如非法 XML)
ParseError 语法有效但解析结果为空/无效
GenerateError 生成 feed 失败
try {
  parseFeed(content)
} catch (error) {
  if (error instanceof DetectError) { /* 格式无法识别 */ }
}

详细说明见 docs/parsing/errors.md。

② parseFeed 返回类型 AnyFeed 正式导出(定义在 src/common/parse.ts),可以直接给返回值标注类型。

③ 自定义日期解析 parseDateFn —— 解析函数支持传入自己的日期转换函数,feed 中所有日期字段都会经过它处理,可配合 date-fns 等库使用,见 docs/parsing/dates.md。

④ 命名空间类型与工具类型导出 —— ItunesNs、DcNs、MediaNs、PodcastNs 等命名空间类型,以及 DateLike、XmlStylesheet 工具类型现在都可直接从主包导入。

⑤ XML 命名空间支持 —— RSS、Atom、RDF 的 feed 与 item 层现在都提供 xml 属性,可读取 xml:lang、xml:base、xml:space、xml:id。

升级后如何验证 🧪

  1. 跑一遍完整测试与构建,TypeScript 编译器会把大部分不兼容用法直接标红
  2. 重点回归 feed 生成逻辑:diff 一下 2.x 与 3.0 生成的 XML 输出,确认无字段丢失
  3. 检查所有 catch (e) { ... } 分支,把泛型 Error 判断替换为四种专用错误类型

按照这份清单逐项执行,从 Feedsmith 2.x 到 3.0 的升级通常只需半天时间。完成迁移后,你将获得更完整的解析数据、更可靠的错误处理和更强大的类型系统——这是一次值得尽快完成的升级。

登录后查看全文
feedsmith