如何快速升级Feedsmith 3.0:破坏性变更完整清单与2.x迁移步骤指南
如何快速升级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。
升级后如何验证 🧪
- 跑一遍完整测试与构建,TypeScript 编译器会把大部分不兼容用法直接标红
- 重点回归 feed 生成逻辑:diff 一下 2.x 与 3.0 生成的 XML 输出,确认无字段丢失
- 检查所有
catch (e) { ... }分支,把泛型Error判断替换为四种专用错误类型
按照这份清单逐项执行,从 Feedsmith 2.x 到 3.0 的升级通常只需半天时间。完成迁移后,你将获得更完整的解析数据、更可靠的错误处理和更强大的类型系统——这是一次值得尽快完成的升级。