Reaction 数据库迁移机制全解Migrations 系统原理与 2.x 升级 3.x 的 6 个避坑要点【免费下载链接】reactionProject has been discontinued ////// Mailchimp Open Commerce is an API-first, headless commerce platform built using Node.js, React, GraphQL. Deployed via Docker and Kubernetes.项目地址: https://gitcode.com/gh_mirrors/re/reactionReactionMailchimp Open Commerce是一个基于 Node.js、React 与 GraphQL 构建的 API 优先、无头headless电商平台。它的数据库迁移Migrations系统是保障 MongoDB 数据结构随版本演进的核心机制。理解它的运作原理不仅能让你在升级 Reaction 3.0 时不踩坑也为自研插件编写安全的迁移脚本打下基础。本文将带你从零看懂 Migrations 系统的设计并给出一份 2.x 升级到 3.x 的实战避坑清单。为什么需要数据库迁移系统电商平台的数据库结构会随功能迭代不断变化给账户加一个adminUIShopIds字段、给邮件表补上createdAt时间戳……如果每次升级都要求用户手动改库风险极高。Migrations 系统的作用就是把「结构变更」封装成一段段可重复、可校验、可追踪的脚本。它回答三个关键问题问题Migrations 系统的回答我现在是什么版本通过命名空间namespace 版本号记录当前状态我该升到什么版本读取插件声明的目标版本并逐级执行升级前数据是否安全用db-version-check先校验再动库 一句话记忆先校验版本 → 再执行迁移 → 后更新版本号这就是整个系统的灵魂。3.0 新系统从「单一版本」到「多轨道命名空间」在 2.x 时代Reaction 用一个集合里的单一文档追踪「全局版本号」所有插件共享一个数字。到了 3.0这套系统被彻底重构为更精细的多轨道multi-track命名空间模型——每个插件拥有独立的版本轨道互不干扰。一个插件如何声明迁移以accounts插件为例它在migrations/目录下组织文件。核心的 index.js 通过tracks数组声明自己的轨道export default { tracks: [ { namespace: migrationsNamespace, // accounts migrations: { 2: migration2, 3: migration3 } } ] };namespace轨道的命名空间来自 migrationsNamespace.js例如accounts。migrations版本号到迁移脚本的映射2: migration2表示从版本 1 升到版本 2 的动作。authorization-simple插件则声明了更长的版本链版本从 2 一路排到 6可见不同插件的迁移节奏是独立演进的这正是多轨道设计的价值namespace: authorization-simple, migrations: { 2: migration2, 3: migration3, 4: migration4, 5: migration5, 6: migration6 }完整源码见 packages/api-plugin-authorization-simple/migrations/index.js。up 与 down一对可逆的迁移函数每个迁移文件如2.js都导出up和down两个函数。up({ db, progress })负责把数据库向上迁移一个版本down负责回滚。看 packages/api-plugin-accounts/migrations/2.jsasync function up({ db, progress }) { // 找出所有缺少 adminUIShopIds 的账户关联其 Groups const accountsWithoutAdminUIShopIds await db.collection(Accounts).aggregate([...]); // 逐个补全并回写进度 progress(100); } export default { down, up };两个细节值得新手注意progress(n)回调迁移脚本通过它向上层报告进度0~100CLI 工具据此渲染进度条。长任务应周期性调用例如progress(Math.floor((index / total) * 100))。down可以声明为unnecessary有些迁移不可逆比如批量补默认值此时可像 packages/api-plugin-email/migrations/2.js 那样写down: unnecessary明确告诉工具「无需回滚」。版本校验动库前的安全网在执行任何数据库命令前官方提供 packages/db-version-check/ 包导出唯一函数doesDatabaseVersionMatch。它会比对「期望版本」与「库中当前版本」不匹配就报错从而避免在错误的数据状态上运行迁移const ok await doesDatabaseVersionMatch({ db, expectedVersion: 2, namespace: my-package-name, // 若库中查不到该轨道版本如何处置新库可直接置为期望版本 async setToExpectedIfMissing() { const anyAccount await db.collection(Accounts).findOne(); return !anyAccount; } }); if (!ok) throw new Error(Database needs migrating.);这套校验与reactioncommerce/migratorCLI 工具配套使用构成「CLI 驱动 版本门禁」的迁移闭环。2.x 升级到 3.x6 个避坑要点Reaction 3.0 是一个破坏性升级——它移除了旧的单文档迁移系统并强制要求「先跑完所有 2.x 迁移」。以下是升级前必须核对的清单。1. 先升级到 2.7.0再升 3.0这是最容易翻车的一点。3.0 启动时会读取旧Migrations集合里的control文档检查版本。若版本低于76直接抛错拒绝启动Detected a migration version (...) for the previous migration system, which is less than 76. You must complete the upgrade to at least 2.7.0 before upgrading to 3.0.0 or higher.这段守卫逻辑位于 packages/api-core/src/ReactionAPICore.js。⚠️坑不要试图跳过 2.7.0 直接上 3.0。正确路径是2.x 当前版本 → 2.7.0跑完全部旧迁移→ 3.0。2. 读懂启动检查的三种情形3.0 的守卫逻辑对Migrations集合中的control文档有三种处理理解它才能判断自己的库处于什么状态库中状态3.0 行为含义无control文档正常启动视为全新库或已手动清理旧迁移记录control.version 76抛错拒绝启动还有 2.x 迁移没跑完control.version 76正常启动2.x 迁移已全部完成可安全升级3. 升级前务必备份 MongoDB多轨道迁移一旦在错误版本上运行数据可能难以回滚。升级前执行一次完整的数据库备份mongodump并确认备份可还原是成本最低的风险对冲。4. 确认迁移工具与 Node 版本匹配3.0 使用独立的reactioncommerce/migratorCLI 与 packages/db-version-check/ 校验包。升级前检查项目依赖是否更新到对应版本避免 CLI 与代码库版本错位导致迁移脚本加载失败。5. 逐插件核对命名空间版本由于新系统按插件分轨道升级后每个含migrations/目录的插件都应有独立的版本记录。建议升级后逐个核对accounts、authorization-simple、email、tags等确认它们都跑到了各自声明的最新版本而不是只升级了全局。6. 自研插件要规范声明 tracks如果你开发了插件且涉及数据变更必须按新规范在migrations/index.js中用tracks数组声明命名空间与版本映射并在每个迁移脚本里正确实现up/down与progress。可参考 packages/api-plugin-accounts/migrations/ 的目录结构作为模板。常见问题FAQQ全新部署 Reaction 3.0 需要手动跑迁移吗通常不需要。3.0 初始化时会为新库建立各命名空间的基线版本。只有从 2.x 升级的场景才需要手动走完 2.7.0。Q为什么 3.0 要移除旧的单版本系统单一全局版本号无法表达「不同插件以不同节奏演进」的现实。多轨道命名空间让每个插件独立管理自己的数据版本升级粒度更细、冲突更少。Q迁移脚本能回滚吗看脚本本身。实现了down函数的可回滚声明为down: unnecessary的不可逆。执行任何变更前先备份库。Q升级卡在哪一步日志怎么看启动时守卫失败会打印上述「less than 76」的错误。看到它就说明还没跑完 2.x 迁移回到 2.7.0 完成全部旧迁移即可。小结2.x → 3.0 是破坏性升级旧系统用单一Migrations文档记录全局版本3.0 改为按插件的多轨道命名空间模型。升级铁律先把 2.x 升到2.7.0跑完全部旧迁移版本 ≥ 76再升 3.0守卫逻辑见 ReactionAPICore.js。迁移三要素up/down可逆函数 progress进度回调 db-version-check版本门禁。动库前必备份并逐插件核对命名空间版本。理解了这套机制你不仅能安全完成 2.x 到 3.x 的升级也能为自研插件写出健壮、可校验的数据迁移脚本。延伸阅读核心启动与升级守卫packages/api-core/src/ReactionAPICore.js多轨道声明示例packages/api-plugin-accounts/migrations/index.js版本链最长的插件packages/api-plugin-authorization-simple/migrations/版本校验工具packages/db-version-check/不可逆迁移写法packages/api-plugin-email/migrations/2.js【免费下载链接】reactionProject has been discontinued ////// Mailchimp Open Commerce is an API-first, headless commerce platform built using Node.js, React, GraphQL. Deployed via Docker and Kubernetes.项目地址: https://gitcode.com/gh_mirrors/re/reaction创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Reaction 数据库迁移机制全解：Migrations 系统原理与 2.x 升级 3.x 的 6 个避坑要点
Reaction 数据库迁移机制全解Migrations 系统原理与 2.x 升级 3.x 的 6 个避坑要点【免费下载链接】reactionProject has been discontinued ////// Mailchimp Open Commerce is an API-first, headless commerce platform built using Node.js, React, GraphQL. Deployed via Docker and Kubernetes.项目地址: https://gitcode.com/gh_mirrors/re/reactionReactionMailchimp Open Commerce是一个基于 Node.js、React 与 GraphQL 构建的 API 优先、无头headless电商平台。它的数据库迁移Migrations系统是保障 MongoDB 数据结构随版本演进的核心机制。理解它的运作原理不仅能让你在升级 Reaction 3.0 时不踩坑也为自研插件编写安全的迁移脚本打下基础。本文将带你从零看懂 Migrations 系统的设计并给出一份 2.x 升级到 3.x 的实战避坑清单。为什么需要数据库迁移系统电商平台的数据库结构会随功能迭代不断变化给账户加一个adminUIShopIds字段、给邮件表补上createdAt时间戳……如果每次升级都要求用户手动改库风险极高。Migrations 系统的作用就是把「结构变更」封装成一段段可重复、可校验、可追踪的脚本。它回答三个关键问题问题Migrations 系统的回答我现在是什么版本通过命名空间namespace 版本号记录当前状态我该升到什么版本读取插件声明的目标版本并逐级执行升级前数据是否安全用db-version-check先校验再动库 一句话记忆先校验版本 → 再执行迁移 → 后更新版本号这就是整个系统的灵魂。3.0 新系统从「单一版本」到「多轨道命名空间」在 2.x 时代Reaction 用一个集合里的单一文档追踪「全局版本号」所有插件共享一个数字。到了 3.0这套系统被彻底重构为更精细的多轨道multi-track命名空间模型——每个插件拥有独立的版本轨道互不干扰。一个插件如何声明迁移以accounts插件为例它在migrations/目录下组织文件。核心的 index.js 通过tracks数组声明自己的轨道export default { tracks: [ { namespace: migrationsNamespace, // accounts migrations: { 2: migration2, 3: migration3 } } ] };namespace轨道的命名空间来自 migrationsNamespace.js例如accounts。migrations版本号到迁移脚本的映射2: migration2表示从版本 1 升到版本 2 的动作。authorization-simple插件则声明了更长的版本链版本从 2 一路排到 6可见不同插件的迁移节奏是独立演进的这正是多轨道设计的价值namespace: authorization-simple, migrations: { 2: migration2, 3: migration3, 4: migration4, 5: migration5, 6: migration6 }完整源码见 packages/api-plugin-authorization-simple/migrations/index.js。up 与 down一对可逆的迁移函数每个迁移文件如2.js都导出up和down两个函数。up({ db, progress })负责把数据库向上迁移一个版本down负责回滚。看 packages/api-plugin-accounts/migrations/2.jsasync function up({ db, progress }) { // 找出所有缺少 adminUIShopIds 的账户关联其 Groups const accountsWithoutAdminUIShopIds await db.collection(Accounts).aggregate([...]); // 逐个补全并回写进度 progress(100); } export default { down, up };两个细节值得新手注意progress(n)回调迁移脚本通过它向上层报告进度0~100CLI 工具据此渲染进度条。长任务应周期性调用例如progress(Math.floor((index / total) * 100))。down可以声明为unnecessary有些迁移不可逆比如批量补默认值此时可像 packages/api-plugin-email/migrations/2.js 那样写down: unnecessary明确告诉工具「无需回滚」。版本校验动库前的安全网在执行任何数据库命令前官方提供 packages/db-version-check/ 包导出唯一函数doesDatabaseVersionMatch。它会比对「期望版本」与「库中当前版本」不匹配就报错从而避免在错误的数据状态上运行迁移const ok await doesDatabaseVersionMatch({ db, expectedVersion: 2, namespace: my-package-name, // 若库中查不到该轨道版本如何处置新库可直接置为期望版本 async setToExpectedIfMissing() { const anyAccount await db.collection(Accounts).findOne(); return !anyAccount; } }); if (!ok) throw new Error(Database needs migrating.);这套校验与reactioncommerce/migratorCLI 工具配套使用构成「CLI 驱动 版本门禁」的迁移闭环。2.x 升级到 3.x6 个避坑要点Reaction 3.0 是一个破坏性升级——它移除了旧的单文档迁移系统并强制要求「先跑完所有 2.x 迁移」。以下是升级前必须核对的清单。1. 先升级到 2.7.0再升 3.0这是最容易翻车的一点。3.0 启动时会读取旧Migrations集合里的control文档检查版本。若版本低于76直接抛错拒绝启动Detected a migration version (...) for the previous migration system, which is less than 76. You must complete the upgrade to at least 2.7.0 before upgrading to 3.0.0 or higher.这段守卫逻辑位于 packages/api-core/src/ReactionAPICore.js。⚠️坑不要试图跳过 2.7.0 直接上 3.0。正确路径是2.x 当前版本 → 2.7.0跑完全部旧迁移→ 3.0。2. 读懂启动检查的三种情形3.0 的守卫逻辑对Migrations集合中的control文档有三种处理理解它才能判断自己的库处于什么状态库中状态3.0 行为含义无control文档正常启动视为全新库或已手动清理旧迁移记录control.version 76抛错拒绝启动还有 2.x 迁移没跑完control.version 76正常启动2.x 迁移已全部完成可安全升级3. 升级前务必备份 MongoDB多轨道迁移一旦在错误版本上运行数据可能难以回滚。升级前执行一次完整的数据库备份mongodump并确认备份可还原是成本最低的风险对冲。4. 确认迁移工具与 Node 版本匹配3.0 使用独立的reactioncommerce/migratorCLI 与 packages/db-version-check/ 校验包。升级前检查项目依赖是否更新到对应版本避免 CLI 与代码库版本错位导致迁移脚本加载失败。5. 逐插件核对命名空间版本由于新系统按插件分轨道升级后每个含migrations/目录的插件都应有独立的版本记录。建议升级后逐个核对accounts、authorization-simple、email、tags等确认它们都跑到了各自声明的最新版本而不是只升级了全局。6. 自研插件要规范声明 tracks如果你开发了插件且涉及数据变更必须按新规范在migrations/index.js中用tracks数组声明命名空间与版本映射并在每个迁移脚本里正确实现up/down与progress。可参考 packages/api-plugin-accounts/migrations/ 的目录结构作为模板。常见问题FAQQ全新部署 Reaction 3.0 需要手动跑迁移吗通常不需要。3.0 初始化时会为新库建立各命名空间的基线版本。只有从 2.x 升级的场景才需要手动走完 2.7.0。Q为什么 3.0 要移除旧的单版本系统单一全局版本号无法表达「不同插件以不同节奏演进」的现实。多轨道命名空间让每个插件独立管理自己的数据版本升级粒度更细、冲突更少。Q迁移脚本能回滚吗看脚本本身。实现了down函数的可回滚声明为down: unnecessary的不可逆。执行任何变更前先备份库。Q升级卡在哪一步日志怎么看启动时守卫失败会打印上述「less than 76」的错误。看到它就说明还没跑完 2.x 迁移回到 2.7.0 完成全部旧迁移即可。小结2.x → 3.0 是破坏性升级旧系统用单一Migrations文档记录全局版本3.0 改为按插件的多轨道命名空间模型。升级铁律先把 2.x 升到2.7.0跑完全部旧迁移版本 ≥ 76再升 3.0守卫逻辑见 ReactionAPICore.js。迁移三要素up/down可逆函数 progress进度回调 db-version-check版本门禁。动库前必备份并逐插件核对命名空间版本。理解了这套机制你不仅能安全完成 2.x 到 3.x 的升级也能为自研插件写出健壮、可校验的数据迁移脚本。延伸阅读核心启动与升级守卫packages/api-core/src/ReactionAPICore.js多轨道声明示例packages/api-plugin-accounts/migrations/index.js版本链最长的插件packages/api-plugin-authorization-simple/migrations/版本校验工具packages/db-version-check/不可逆迁移写法packages/api-plugin-email/migrations/2.js【免费下载链接】reactionProject has been discontinued ////// Mailchimp Open Commerce is an API-first, headless commerce platform built using Node.js, React, GraphQL. Deployed via Docker and Kubernetes.项目地址: https://gitcode.com/gh_mirrors/re/reaction创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考