数据库NoSQL嵌入式数据库实时数据库【免费下载链接】rxdbThe local-first database that runs on every JS runtime and replicates with your existing backend - no vendor, no lock-in - https://rxdb.info/项目地址https://gitcode.com/gh_mirrors/rx/rxdb点击查看免费下载RxDB 维护团队在仓库中维护着一份面向下一个大版本next major的规划清单 orga/before-next-major.md集中记录所有必须做、但会造成破坏性变更的事项以及一批也许以后再说Maybe later的候选变更。本文以这份规划文档为主线结合仓库源码梳理每一项变更的背景、影响范围与落地细节重点剖析其中的头号任务——用社区 forkthaunknown/simple-peer替换已停止维护的simple-peer帮助读者理解 RxDB 主版本升级时为什么会产生这些破坏以及维护者计划如何处理。一、这份规划文档在仓库中的定位orga/目录是 RxDB 的内部组织与规划目录其中 before-next-major.md 的定位非常明确它收集的是必须完成、但会带来 breaking change的事项因此不能放在普通的 minor/patch 版本里只能随下一个 major 版本一起发布。文档将内容划分为两大部分发布前必须完成的事项目前主要是 WebRTC 复制底层依赖simple-peer的替换Maybe later暂不确定是否要做包括禁止 Schema 类型混合、key-compression 增强、RxStorage.info()、品牌重命名、data-migrator 重构等五个候选变更。阅读这份清单时需要注意它是规划文档而非发布说明其中列出的方案代表了维护者的意图与调研结论而仓库当前源码仍处于变更前的状态——这正好让我们可以对照源码看清每一项变更将要动到的具体代码位置。二、首要任务用thaunknown/simple-peer替换simple-peer2.1 为什么必须替换simple-peer 已经停止维护WebRTC 复制replication-webrtc、Google Drive 复制和 Microsoft OneDrive 复制这三个插件都依赖simple-peer这个 npm 包。规划文档给出的替换理由是硬性的simple-peer已无人维护最后一个 release 是2022 年 2 月的 9.11.1且其仓库积压了超过 100 个未关闭的 issue它依赖buffer、readable-stream、randombytes、get-browser-rtc、queue-microtask、err-code、debug等一系列 Node.js shim这些 shim 会以传递依赖的形式泄漏给最终用户带来一系列真实问题例如来自randombytes的ReferenceError: global is not defined会直接破坏 Angular 构建Cannot read properties of undefined (reading call) at _Peer.Readable等运行时崩溃npm audit报告rxdb - Depends on vulnerable versions of simple-peer的安全告警为了兼容它RxDB 不得不专门引入错误码RC7仅用于提示用户需要 polyfillprocess.nextTick()见 error-messages.ts为了绕开 simple-peer 会修改 WebRTC polyfill 返回的RTCSessionDescription对象这一行为还需要维护createSimplePeerWrtc()这种兼容层。这些兼容代码在 connection-handler-simple-peer.ts 中都能找到实际实现ensureProcessNextTickIsSet()第 324-331 行在process.nextTick缺失时直接抛出RC7错误createSimplePeerWrtc()第 87-108 行则通过继承并重写createOffer()/createAnswer()把 polyfill 返回的对象重新包装成{ type, sdp }纯对象避免 simple-peer 对只读属性的修改操作崩溃。2.2 RxDB 实际只用到了 simple-peer 的哪一部分替换方案之所以可行前提是 RxDB 对 simple-peer 的使用面非常窄。对照 connection-handler-simple-peer.ts 的源码可以确认RxDB 只用到了构造函数调用new Peer({ initiator, config, trickle })第 214-219 行其中initiator通过比较双方 peerId 的字符串大小决定trickle: truesignal、connect、data、close、error五个事件第 224-270 行.signal()、.send()、.destroy()三个方法分别用于接收信号、发送消息、销毁连接。因此换一个 API 兼容的 fork在代码层面是可行的。thaunknown/simple-peer正是这样一个 API 兼容的维护中 fork它的关键差异在于是ESM包用streamx和Uint8Array替代了readable-stream与buffer从根上消掉了那一串 Node.js shim 依赖提供lite.js入口只包含数据通道data channel代码不包含 MediaStream 处理——而后者恰恰是 RxDB 根本用不到的部分。2.3 迁移中必须处理的五个关键点替换本身很小但规划文档列出了试用 fork 后发现的、必须逐一处理的五个坑它们正是为什么这是一次破坏性变更的答案① 必须是可选 peer dependency而不是普通依赖。fork 依赖webrtc-polyfill而它又依赖node-datachannel——这是一个带 install 脚本的原生 NAPI addon。如果作为普通依赖每次用户npm install rxdb时包括纯浏览器应用都会触发原生模块安装。因此必须像firebase、mongodb一样声明为可选 peer dependency这也成为本次变更的主要破坏来源。② 永远不能用require()加载。webrtc-polyfill的exportsmap 中没有require条件require()会报ERR_PACKAGE_PATH_NOT_EXPORTED同时webrtc-polyfill/lib/Blob.js以顶层 awaittop-level await开头在任何 Node.js 版本上都会触发ERR_REQUIRE_ASYNC_MODULE。单纯提高engines字段无济于事。正确做法是用动态import()加载——babel 和 tsx 都不会改写它——否则 CommonJS 构建中的require(rxdb/plugins/replication-webrtc)会直接挂掉。Google Drive 与 OneDrive 复制的测试用例经由 tsx 运行同样受此影响。③data事件发射的是Uint8Array而非 Node.jsBuffer。规划文档指出三个调用点目前都用toString()或 解码载荷这在Uint8Array上会得到逗号分隔的字节值而不是 JSON 字符串。当前代码确实如此connection-handler-simple-peer.ts第 235 行就是JSON.parse(messageOrResponse.toString())。迁移后必须改用TextDecoder解码否则每一条消息都会解析失败。④ React Native 仍需要 WebRTC 实现。fork 移除了wrtc选项改为从webrtc-polyfill读取 API——它覆盖了浏览器原生 API 与 Node.js 的node-datachannel但 React Native 两者都不是且webrtc-polyfill没有react-nativeexport 条件。规划中的对策是由于 fork 在加载时只从全局作用域读取一次 API可以在惰性import()之前把wrtc写进全局作用域从而让旧选项继续生效另外 Metro 需要被配置为把webrtc-polyfill解析到浏览器构建否则它会选中带原生模块的 Node.js 版本。⑤ 测试脚本的忽略模块。thaunknown/simple-peer需要被加入test:deps脚本的忽略列表中与ws并列因为dependency-check只识别静态 import而 fork 只能通过动态import()加载会被误报为缺失依赖。规划文档提到一个 CI 全绿的完整实现已经存在于 PR #8900可作为迁移参考实现。2.4 可以随之移除的兼容层RC7 与 ensureProcessNextTickIsSet()替换的收益之一是能删掉两个为 simple-peer 量身定做的兼容机制RC7错误码error-messages.ts的存在意义仅仅是提示SimplePeer requires to have process.nextTick() polyfilledensureProcessNextTickIsSet()connection-handler-simple-peer.ts在运行时检测process.nextTick并抛错。由于 fork 使用streamx而streamx内部用的是queueMicrotask()这两个针对process.nextTick的兼容层都可以整体删除。2.5 类型声明收窄带来的破坏性影响types/simple-peer可以随之丢弃但 fork 本身不提供类型因此 RxDB 必须自行声明所用到的 API 子集。这里有一个容易被忽略的破坏点只声明用到的部分会收窄公开的SimplePeer类型从而破坏那些在connect$和message$里调用 peer 其他方法的用户构建。也就是说即使运行时行为完全兼容类型层面的收窄依然是 breaking change。2.6 小结为什么这些细节值得关心从源码结构看这次替换触及的是 WebRTC 复制插件的连接处理器核心connection-handler-simple-peer.ts以及三个复制插件的共同底层。它涉及的不仅是换一个包而是依赖形态peer dependency、模块系统ESM 动态 import、数据编码TextDecoder、多端运行时React Native / Metro和公开类型面SimplePeer 类型收窄的多重变更——这正是它被列在必须随 major 版本发布清单首位的原因。三、储备清单Maybe later暂不确定是否执行的变更规划文档的第二部分是五个也许以后再说的候选变更它们同样具有破坏性但维护者尚未下定决心。3.1 禁止 Schema 中的类型混合Do not allow type mixing当前RxJsonSchema中字段的type可以是一个类型也可以是类型数组。从 rx-schema.d.ts 可以看到实际定义type?: JsonSchemaTypes | JsonSchemaTypes[] | readonly JsonSchemaTypes[];规划文档认为这种设计不好且不应使用每个字段应恰好只有一个类型。理由是类型混合会带来语义混乱例如字段类型是[string, number]时执行$gt: 10这样的查询选择器无法确定字符串foobar是否应该被匹配。这一变更会影响所有使用多类型字段的既有 schema属于典型的前向不兼容约束。3.2 key-compression 插件新增 enum-compression 并更名规划建议给 key-compression 插件增加枚举压缩enum-compression能力同时把插件更名为更通用的compression。当前插件实现位于 key-compression/index.ts它基于jsonschema-key-compression库构建压缩表通过wrapRxStorageInstance包装底层存储实例在写路径上compressObject/ 读路径上decompressObject并对query、count等方法做查询压缩还会手工把index字段压缩后重新写回因为压缩库不认识它。更名为compression意味着所有addRxPlugin(RxDBKeyCompressionPlugin)的用户需要改用新插件名是典型的命名级破坏。3.3 RxStorage 增加 RxStorage.info() 方法规划提议为RxStorage增加一个.info()方法并且要求它能向上传递调用父级存储的信息。用途是方便调试与问题上报例如发送诊断报告。从仓库结构看RxStorage 的接口定义集中在 rx-storage.interface.d.ts任何新方法都会对所有存储实现memory、dexie、sqlite、foundationdb、mongodb 等产生实现层面的影响。3.4 RxDB Premium 更名为 RxDB Enterprise规划认为大多数普通用户并不需要 premium 访问权限更名可以让该产品是面向公司销售的这一意图更清晰。这是一项纯品牌/命名层面的变更属于对用户可见的破坏性调整。3.5 重构>赞分享数据库NoSQL嵌入式数据库实时数据库【免费下载链接】rxdbThe local-first database that runs on every JS runtime and replicates with your existing backend - no vendor, no lock-in - https://rxdb.info/项目地址https://gitcode.com/gh_mirrors/rx/rxdb点击查看免费下载相关推荐DataHub Cloud v1.0.0 发布解析从 1.0 主版本到 v1.0.3 热修的完整变更、破坏性变更与迁移要点DataHub Cloud v1.0.0 发布解析从 1.0 主版本到 v1.0.3 热修的完整变更、破坏性变更与迁移要点 本篇基于 DataHub 仓库中的数据目录数据治理数据血缘后端前端数据工程数据集成Bevy 迁移指南机制详解主版本间破坏性变更如何被记录、编写与发布Bevy 迁移指南机制详解主版本间破坏性变更如何被记录、编写与发布 Bevy 采用约每 3 个月一次的大版本发布节奏每个大版本都会引入 API 破坏性变更游戏开发图形学AI SDK 大版本发布模式破坏性变更的兼容策略与迁移实践AI SDK 大版本发布模式破坏性变更的兼容策略与迁移实践 本文基于仓库 skills/major version mode/SKILL.md https:/人工智能AI 应用AI Agent工具调用MCP Clients创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 RxDB 下一个主版本发布前的破坏性变更规划：simple-peer 替换与迁移路线图
数据库NoSQL嵌入式数据库实时数据库【免费下载链接】rxdbThe local-first database that runs on every JS runtime and replicates with your existing backend - no vendor, no lock-in - https://rxdb.info/项目地址https://gitcode.com/gh_mirrors/rx/rxdb点击查看免费下载RxDB 维护团队在仓库中维护着一份面向下一个大版本next major的规划清单 orga/before-next-major.md集中记录所有必须做、但会造成破坏性变更的事项以及一批也许以后再说Maybe later的候选变更。本文以这份规划文档为主线结合仓库源码梳理每一项变更的背景、影响范围与落地细节重点剖析其中的头号任务——用社区 forkthaunknown/simple-peer替换已停止维护的simple-peer帮助读者理解 RxDB 主版本升级时为什么会产生这些破坏以及维护者计划如何处理。一、这份规划文档在仓库中的定位orga/目录是 RxDB 的内部组织与规划目录其中 before-next-major.md 的定位非常明确它收集的是必须完成、但会带来 breaking change的事项因此不能放在普通的 minor/patch 版本里只能随下一个 major 版本一起发布。文档将内容划分为两大部分发布前必须完成的事项目前主要是 WebRTC 复制底层依赖simple-peer的替换Maybe later暂不确定是否要做包括禁止 Schema 类型混合、key-compression 增强、RxStorage.info()、品牌重命名、data-migrator 重构等五个候选变更。阅读这份清单时需要注意它是规划文档而非发布说明其中列出的方案代表了维护者的意图与调研结论而仓库当前源码仍处于变更前的状态——这正好让我们可以对照源码看清每一项变更将要动到的具体代码位置。二、首要任务用thaunknown/simple-peer替换simple-peer2.1 为什么必须替换simple-peer 已经停止维护WebRTC 复制replication-webrtc、Google Drive 复制和 Microsoft OneDrive 复制这三个插件都依赖simple-peer这个 npm 包。规划文档给出的替换理由是硬性的simple-peer已无人维护最后一个 release 是2022 年 2 月的 9.11.1且其仓库积压了超过 100 个未关闭的 issue它依赖buffer、readable-stream、randombytes、get-browser-rtc、queue-microtask、err-code、debug等一系列 Node.js shim这些 shim 会以传递依赖的形式泄漏给最终用户带来一系列真实问题例如来自randombytes的ReferenceError: global is not defined会直接破坏 Angular 构建Cannot read properties of undefined (reading call) at _Peer.Readable等运行时崩溃npm audit报告rxdb - Depends on vulnerable versions of simple-peer的安全告警为了兼容它RxDB 不得不专门引入错误码RC7仅用于提示用户需要 polyfillprocess.nextTick()见 error-messages.ts为了绕开 simple-peer 会修改 WebRTC polyfill 返回的RTCSessionDescription对象这一行为还需要维护createSimplePeerWrtc()这种兼容层。这些兼容代码在 connection-handler-simple-peer.ts 中都能找到实际实现ensureProcessNextTickIsSet()第 324-331 行在process.nextTick缺失时直接抛出RC7错误createSimplePeerWrtc()第 87-108 行则通过继承并重写createOffer()/createAnswer()把 polyfill 返回的对象重新包装成{ type, sdp }纯对象避免 simple-peer 对只读属性的修改操作崩溃。2.2 RxDB 实际只用到了 simple-peer 的哪一部分替换方案之所以可行前提是 RxDB 对 simple-peer 的使用面非常窄。对照 connection-handler-simple-peer.ts 的源码可以确认RxDB 只用到了构造函数调用new Peer({ initiator, config, trickle })第 214-219 行其中initiator通过比较双方 peerId 的字符串大小决定trickle: truesignal、connect、data、close、error五个事件第 224-270 行.signal()、.send()、.destroy()三个方法分别用于接收信号、发送消息、销毁连接。因此换一个 API 兼容的 fork在代码层面是可行的。thaunknown/simple-peer正是这样一个 API 兼容的维护中 fork它的关键差异在于是ESM包用streamx和Uint8Array替代了readable-stream与buffer从根上消掉了那一串 Node.js shim 依赖提供lite.js入口只包含数据通道data channel代码不包含 MediaStream 处理——而后者恰恰是 RxDB 根本用不到的部分。2.3 迁移中必须处理的五个关键点替换本身很小但规划文档列出了试用 fork 后发现的、必须逐一处理的五个坑它们正是为什么这是一次破坏性变更的答案① 必须是可选 peer dependency而不是普通依赖。fork 依赖webrtc-polyfill而它又依赖node-datachannel——这是一个带 install 脚本的原生 NAPI addon。如果作为普通依赖每次用户npm install rxdb时包括纯浏览器应用都会触发原生模块安装。因此必须像firebase、mongodb一样声明为可选 peer dependency这也成为本次变更的主要破坏来源。② 永远不能用require()加载。webrtc-polyfill的exportsmap 中没有require条件require()会报ERR_PACKAGE_PATH_NOT_EXPORTED同时webrtc-polyfill/lib/Blob.js以顶层 awaittop-level await开头在任何 Node.js 版本上都会触发ERR_REQUIRE_ASYNC_MODULE。单纯提高engines字段无济于事。正确做法是用动态import()加载——babel 和 tsx 都不会改写它——否则 CommonJS 构建中的require(rxdb/plugins/replication-webrtc)会直接挂掉。Google Drive 与 OneDrive 复制的测试用例经由 tsx 运行同样受此影响。③data事件发射的是Uint8Array而非 Node.jsBuffer。规划文档指出三个调用点目前都用toString()或 解码载荷这在Uint8Array上会得到逗号分隔的字节值而不是 JSON 字符串。当前代码确实如此connection-handler-simple-peer.ts第 235 行就是JSON.parse(messageOrResponse.toString())。迁移后必须改用TextDecoder解码否则每一条消息都会解析失败。④ React Native 仍需要 WebRTC 实现。fork 移除了wrtc选项改为从webrtc-polyfill读取 API——它覆盖了浏览器原生 API 与 Node.js 的node-datachannel但 React Native 两者都不是且webrtc-polyfill没有react-nativeexport 条件。规划中的对策是由于 fork 在加载时只从全局作用域读取一次 API可以在惰性import()之前把wrtc写进全局作用域从而让旧选项继续生效另外 Metro 需要被配置为把webrtc-polyfill解析到浏览器构建否则它会选中带原生模块的 Node.js 版本。⑤ 测试脚本的忽略模块。thaunknown/simple-peer需要被加入test:deps脚本的忽略列表中与ws并列因为dependency-check只识别静态 import而 fork 只能通过动态import()加载会被误报为缺失依赖。规划文档提到一个 CI 全绿的完整实现已经存在于 PR #8900可作为迁移参考实现。2.4 可以随之移除的兼容层RC7 与 ensureProcessNextTickIsSet()替换的收益之一是能删掉两个为 simple-peer 量身定做的兼容机制RC7错误码error-messages.ts的存在意义仅仅是提示SimplePeer requires to have process.nextTick() polyfilledensureProcessNextTickIsSet()connection-handler-simple-peer.ts在运行时检测process.nextTick并抛错。由于 fork 使用streamx而streamx内部用的是queueMicrotask()这两个针对process.nextTick的兼容层都可以整体删除。2.5 类型声明收窄带来的破坏性影响types/simple-peer可以随之丢弃但 fork 本身不提供类型因此 RxDB 必须自行声明所用到的 API 子集。这里有一个容易被忽略的破坏点只声明用到的部分会收窄公开的SimplePeer类型从而破坏那些在connect$和message$里调用 peer 其他方法的用户构建。也就是说即使运行时行为完全兼容类型层面的收窄依然是 breaking change。2.6 小结为什么这些细节值得关心从源码结构看这次替换触及的是 WebRTC 复制插件的连接处理器核心connection-handler-simple-peer.ts以及三个复制插件的共同底层。它涉及的不仅是换一个包而是依赖形态peer dependency、模块系统ESM 动态 import、数据编码TextDecoder、多端运行时React Native / Metro和公开类型面SimplePeer 类型收窄的多重变更——这正是它被列在必须随 major 版本发布清单首位的原因。三、储备清单Maybe later暂不确定是否执行的变更规划文档的第二部分是五个也许以后再说的候选变更它们同样具有破坏性但维护者尚未下定决心。3.1 禁止 Schema 中的类型混合Do not allow type mixing当前RxJsonSchema中字段的type可以是一个类型也可以是类型数组。从 rx-schema.d.ts 可以看到实际定义type?: JsonSchemaTypes | JsonSchemaTypes[] | readonly JsonSchemaTypes[];规划文档认为这种设计不好且不应使用每个字段应恰好只有一个类型。理由是类型混合会带来语义混乱例如字段类型是[string, number]时执行$gt: 10这样的查询选择器无法确定字符串foobar是否应该被匹配。这一变更会影响所有使用多类型字段的既有 schema属于典型的前向不兼容约束。3.2 key-compression 插件新增 enum-compression 并更名规划建议给 key-compression 插件增加枚举压缩enum-compression能力同时把插件更名为更通用的compression。当前插件实现位于 key-compression/index.ts它基于jsonschema-key-compression库构建压缩表通过wrapRxStorageInstance包装底层存储实例在写路径上compressObject/ 读路径上decompressObject并对query、count等方法做查询压缩还会手工把index字段压缩后重新写回因为压缩库不认识它。更名为compression意味着所有addRxPlugin(RxDBKeyCompressionPlugin)的用户需要改用新插件名是典型的命名级破坏。3.3 RxStorage 增加 RxStorage.info() 方法规划提议为RxStorage增加一个.info()方法并且要求它能向上传递调用父级存储的信息。用途是方便调试与问题上报例如发送诊断报告。从仓库结构看RxStorage 的接口定义集中在 rx-storage.interface.d.ts任何新方法都会对所有存储实现memory、dexie、sqlite、foundationdb、mongodb 等产生实现层面的影响。3.4 RxDB Premium 更名为 RxDB Enterprise规划认为大多数普通用户并不需要 premium 访问权限更名可以让该产品是面向公司销售的这一意图更清晰。这是一项纯品牌/命名层面的变更属于对用户可见的破坏性调整。3.5 重构>赞分享数据库NoSQL嵌入式数据库实时数据库【免费下载链接】rxdbThe local-first database that runs on every JS runtime and replicates with your existing backend - no vendor, no lock-in - https://rxdb.info/项目地址https://gitcode.com/gh_mirrors/rx/rxdb点击查看免费下载相关推荐DataHub Cloud v1.0.0 发布解析从 1.0 主版本到 v1.0.3 热修的完整变更、破坏性变更与迁移要点DataHub Cloud v1.0.0 发布解析从 1.0 主版本到 v1.0.3 热修的完整变更、破坏性变更与迁移要点 本篇基于 DataHub 仓库中的数据目录数据治理数据血缘后端前端数据工程数据集成Bevy 迁移指南机制详解主版本间破坏性变更如何被记录、编写与发布Bevy 迁移指南机制详解主版本间破坏性变更如何被记录、编写与发布 Bevy 采用约每 3 个月一次的大版本发布节奏每个大版本都会引入 API 破坏性变更游戏开发图形学AI SDK 大版本发布模式破坏性变更的兼容策略与迁移实践AI SDK 大版本发布模式破坏性变更的兼容策略与迁移实践 本文基于仓库 skills/major version mode/SKILL.md https:/人工智能AI 应用AI Agent工具调用MCP Clients创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考