企业官网建设流程全解析

Substance.Data为何被弃用？迁移到Substance的完整路线图

【免费下载链接】dataA uniform interface for domain data (deprecated)项目地址: https://gitcode.com/gh_mirrors/data26/data

Substance.Data 是一个基于图的 JavaScript 数据框架，曾为开源出版平台 Substance 提供领域数据建模、遍历与查询能力，如今官方已宣布停止维护。如果你正维护旧项目，这篇 Substance.Data 迁移指南将帮你理清弃用原因，并提供一条从 Substance.Data 平滑迁移到 Substance 的完整路线图，全程少踩坑。

一、Substance.Data 是什么？它解决了什么问题

在 Substance 生态早期，文档编辑器需要一套统一的领域数据层：既能建模复杂对象关系，又能在浏览器与 Node.js 两端用同一套 API 读写。Substance.Data 正是为此而生，它用「图 + 节点 + 关系」的方式组织数据，并可整体序列化为 JSON。

它的核心能力可以概括为三句话：

• 🕸️ 用基于图的对象模型描述领域数据，序列化为 JSON 后自由传输
• 🔗 通过简单 API 遍历图，包括节点间的关系
• 💻 浏览器端（客户端）与 Node.js（服务端）使用完全相同的接口

核心代码分布在以下几个模块，读懂它们就理解了整个框架：

入口文件 index.js 只做了一件事：导出Data.Graph，可见图模型就是这个库的灵魂。

二、Substance.Data 被弃用的真正原因

弃用并不是因为框架"烂"，而是生态演进的必然结果。综合来看有四个原因：

1. 功能并入主库：官方明确表示 Substance.Data 不再维护，其能力被整合进 Substance 主项目，继续维护独立仓库会造成重复开发。
2. 架构代际差距：框架停留在 0.8.0 版本，CHANGELOG 显示其设计思路（如基于操作转换的增量更新、Chronicle 版本管理）已被更新的架构取代。
3. 依赖过于老旧：从 package.json 可以看到它仍依赖 underscore 1.5.x，要求 Node 版本 >= 0.8，与现代工程实践严重脱节。
4. 维护精力有限：开源项目的维护者资源有限，与其维护多个分仓库，不如聚焦统一的 Substance 数据层。

💡 一句话总结：Substance.Data 完成了它的历史使命，但它的设计理念——统一、跨端、基于图的数据接口——被 Substance 继承并发展了。

三、迁移目标：认识新的 Substance 数据层

迁移的第一步是明确"迁到哪"。Substance 是主项目，提供了更完整的文档编辑与数据能力。对大部分用户来说，迁移不是推倒重来，而是把数据层的 API 调用从substance-data切换到 Substance 内置的数据接口。

迁移前请先确认三件事：

• ✅ 你的项目是否仍在使用npm install substance-data安装的旧依赖
• ✅ 代码中是否大量出现Data.Graph、new Data.Graph(schema)之类的调用
• ✅ 是否依赖了 Store 持久化、Chronicle 版本回滚等扩展能力

四、从 Substance.Data 迁移到 Substance 的完整步骤

下面这套迁移路线图面向新手，按步骤执行即可。

步骤 1：盘点代码中的图模型 API

先做"体检"。全局搜索Data.Graph、graph.set、graph.get、schema等关键词，统计使用范围。旧框架的调用集中体现在：

• 初始化：new Graph(schema, options)（见 src/graph.js）
• 节点操作：add / set / get / delete
• 查询：find、索引过滤（见 graph_index.js）

建议用表格列出一份"API 使用清单"，每行记录：文件位置、使用的 API、新 API 对应方案。

步骤 2：安装并引入 Substance

在项目根目录执行依赖替换：

npm uninstall substance-data npm install substance

如果希望对照源码理解迁移细节，可以克隆本仓库参考旧实现：

git clone https://gitcode.com/gh_mirrors/data26/data

步骤 3：替换 Graph 与 Schema 调用

把Data.Graph的创建与节点操作迁移到 Substance 的数据模型。旧代码中基于 schema.js 的类型解析（string、number、boolean、date 等）在新数据层中都有对应概念，只是命名和挂载位置不同。

建议分批替换：先替换纯读取逻辑，再替换写入逻辑，最后处理索引查询，降低单次回归风险。

步骤 4：重写查询与索引逻辑

旧框架的索引机制（按类型过滤、按属性分组）比较独特，迁移时往往需要重写。这里提醒两点：

• 把"索引配置"与"业务查询"分开维护，方便对照测试
• 利用新数据层的官方查询能力，而非照搬旧 API 的参数结构

步骤 5：回归测试与验证

旧仓库自带测试体系可作参考，如 tests/run.js 和 tests/schema_test.js。迁移完成后，务必验证：

• ✔️ 数据序列化与反序列化结果一致
• ✔️ 关系遍历结果与迁移前相同
• ✔️ 持久化、版本回滚等扩展功能正常

五、迁移避坑指南

• ⚠️不要照搬旧 API 文档：Substance.Data 的 README 已声明不再维护，相关示例可能过时
• ⚠️警惕依赖链：旧库依赖substance-util，卸载时检查是否被其他模块引用
• ⚠️数据格式兼容：图数据序列化为 JSON 的结构若与旧版不一致，需准备数据迁移脚本

六、写在最后

Substance.Data 的弃用并不可怕，它恰恰说明 Substance 生态在走向统一。只要按"盘点 → 替换依赖 → 分批改造 → 回归测试"的路线图推进，从 Substance.Data 迁移到 Substance 就是一次低风险的升级。把握核心原则——用统一的 Substance 数据层替代分散的旧模块——你的项目就能顺利过渡，继续享受图数据模型带来的灵活与跨端一致体验。

【免费下载链接】dataA uniform interface for domain data (deprecated)项目地址: https://gitcode.com/gh_mirrors/data26/data