MST用户注意：mobx-keystone与mobx-state-tree的10大核心差异+迁移指南

MST用户注意：mobx-keystone与mobx-state-tree的10大核心差异+迁移指南

【免费下载链接】mobx-keystoneA MobX powered state management solution based on data trees with first class support for Typescript, support for snapshots, patches and much more项目地址: https://gitcode.com/gh_mirrors/mo/mobx-keystone

如果你正在使用mobx-state-tree（MST）做 TypeScript 状态管理，或正在评估是否迁移到mobx-keystone——这个基于数据树的 MobX 状态管理方案，这篇文章值得你花 10 分钟读完。下面梳理了两者最容易踩坑的 10 大核心差异，并附上一份可直接执行的迁移指南，帮你低成本完成切换。

📊 一张表看懂：功能对照总览

先说结论：mobx-keystone借鉴了 MST 的大量思想，但整体设计对 TypeScript 更友好。核心能力对照如下：

💡 一句话总结：能力基本对齐，类型体验显著升级，生命周期更可控。

🔍 10大核心差异详解

差异 1：模型定义 ——types.modelvs TypeScript 类

MST 用链式函数声明模型，mobx-keystone直接让你写TypeScript 类：

// MST 风格 const Todo = types.model("Todo", { text: types.string, done: types.optional(types.boolean, false) }) // mobx-keystone 风格（类模型，见 apps/site/docs/classModels.mdx） @model("myApp/Todo") class Todo extends Model({ text: prop<string>(), done: prop(false), }) {}

好处：IDE 补全、重构、继承全部"原生可用"，学习曲线更平。

差异 2：selfvsthis

MST 里跨"块"访问要用self，同块访问用this，经常让人困惑。mobx-keystone一律使用this，计算属性直接用标准的 MobX@computed装饰器。

差异 3：运行时类型校验完全可选

MST 的类型校验是强制的（types.string等 schema 必写）。mobx-keystone提供两种模式：

• 只信 TypeScript：用prop<T>()，零运行时开销；
• 需要运行时校验（如不可信数据源）：用tProp(types.string)。

差异 4：递归 / 交叉引用模型变简单

MST 里自递归或相互引用的模型需要types.late、types.optional等绕弯子，类型推断经常失效。mobx-keystone中直接互相引用类即可，无需 late 类型、无需强制类型转换。

差异 5：引用从"字符串标识符"变成显式Ref对象

⚠️这是持久化数据迁移的最大坑：旧快照里的引用形态与新系统不同，需要数据转换（下文迁移指南有方案）。

差异 6：生命周期钩子从 4 个减到 2 个

MST 有beforeCreate/afterCreate/afterAttach/beforeDetach等钩子，且节点是懒初始化的——你写的afterCreate可能在节点内容被访问前根本不执行，getRoot也可能拿不到你以为的值。

mobx-keystone只保留两个语义明确的钩子：

1. onInit—— 模型创建后必然触发（没有懒初始化）；
2. onAttachedToRootStore—— 挂到已注册的根存储时触发，可返回清理函数（disposer），是注册副作用（reaction 等）的安全位置。

差异 7：volatile不再是特殊概念

MST 的.volatile(() => ({...}))在mobx-keystone中就是普通类字段；需要响应式时加上 MobX 的@observable+@action即可。运行期临时数据不进入快照，语义不变但写法更直白。

差异 8：环境注入getEnv→createContext

MST 通过getEnv(self)从树根读取依赖（api、router 等）。mobx-keystone的等价物是Context（见packages/lib/src/context/）：

const envCtx = createContext<Env>() // 模型内部取用： const env = envCtx.get(this)!

好处是依赖注入与模型解耦，单测更容易。

差异 9：异步 Flow 的写法变化

• MST：load: flow(function* () { const dto = yield api.fetch() })
• mobx-keystone：方法加@modelFlow装饰器，yield promise改为yield* _await(promise)。

功能等价，只是语法糖不同。

差异 10：destroy/isAlive的"死节点"语义被移除

MST 里节点被destroy后进入"死亡"状态，误用会抛错。mobx-keystone没有死节点概念：detach(node)之后实例仍是完全可用的普通对象，不会再报 isAlive 错误。这对减少幽灵崩溃很友好，但也要更新测试用例的断言。

🛠️ MST → mobx-keystone 迁移指南（可直接执行）

官方完整迁移文档位于apps/site/docs/mstMigrationGuide.mdx，功能对比表在apps/site/docs/mstComparison.mdx。以下是浓缩版操作手册。

第一步：迁移前必须先做的 3 个决策

1. 是否要运行时类型校验—— 只靠 TypeScript 就用prop<T>()；需要运行时校验（更接近 MST 的 schema 习惯、利于快照迁移）就用tProp(...)+types.*；
2. 持久化格式—— MST 快照没有$modelType元数据，mobx-keystone模型快照会带上$modelType。老快照需要用带类型的fromSnapshot(Todo, oldSnapshot)加载；若属性用了tProp，其内部快照通常可省略$modelType；
3. 引用策略—— 明确哪些关系是真正的树子节点，哪些应该是Ref跨树引用。

第二步：推荐的 7 步迁移顺序（保持 diff 可审查）

1. 转换模型定义（数据结构 + 基础 actions/views）
2. 转换异步 flow（flow→@modelFlow）
3. 转换环境注入（getEnv→createContext）
4. 转换引用（types.reference/safeReference→Ref+rootRef/customRef）
5. 转换持久化与快照（重点是旧快照数据迁移）
6. 转换 patch / 动作回放 / 中间件集成
7. 跑测试，修复边缘场景（生命周期、集合、快照处理器）

第三步：高频坑位速查 ⚠️

第四步：高频 API 对照表（收藏向）

相关实现可参考源码目录：packages/lib/src/ref/（引用）、packages/lib/src/snapshot/（快照）、packages/lib/src/action/（动作与中间件）、packages/lib/src/context/（上下文注入）。

✅ 迁移完成检查清单

• 模型在严格模式 TypeScript 下编译通过
• 所有self已替换为this，cast(...)基本移除
• 动作 / flow 的变更边界仍被正确保护
• 引用解析与清理行为符合预期（含 safe-reference 策略）
• 快照存取往返测试通过（含$modelType元数据）
• types.map/types.array的默认值已显式提供
• volatile 状态已迁移为类字段且响应式正确
• patch / 动作回放链路验证通过（onPatches/applyPatches）
• registerRootStore已为根存储注册（生命周期钩子需要）
• 既有测试全部通过，并为迁移的边缘场景新增测试

📌 小结

mobx-keystone保留了 MST 你最熟悉的一切——数据树、快照、patch、动作回放、undo/redo——同时用类模型 + 可选运行时校验 + 简化的生命周期解决了 MST 长期被诟病的类型痛点。如果你的项目已经用上了 TypeScript 严格模式，迁移的成本比想象中低：按上面的 7 步顺序推进，重点盯住引用快照格式和生命周期行为这两处语义变化即可。

【免费下载链接】mobx-keystoneA MobX powered state management solution based on data trees with first class support for Typescript, support for snapshots, patches and much more项目地址: https://gitcode.com/gh_mirrors/mo/mobx-keystone