迁移指南总览

本目录用于解决三类迁移问题：

• 语义怎么对齐：旧库概念如何映射到 IO。
• 迁移如何分阶段：如何从低风险开始逐步替换。
• 如何判断完成：用统一验收清单避免“看起来能跑但边界不稳”。

推荐阅读顺序

1. 先读 为什么选择 IO 明确收益与代价。
2. 再读对应来源库页面（Zustand / Valtio / Jotai / Redux / MobX）。
3. Query 升级场景补读：
   • Query v0.1 Breaking Changes
   • Migration: client.query -> defineQuery/observeQuery
4. 最后按本页验收清单做上线前检查。

通用迁移步骤

1) 定义迁移边界

• 先选一个业务切片（例如用户中心、列表页）而不是全局一次性替换。
• 记录该切片的输入、输出、副作用与持久化依赖。

2) 完成模型映射

• 状态：从旧库 store/atom/proxy 映射到 io(...)。
• 读取：从 selector/snapshot/observer 映射到路径 Unit 订阅。
• 写入：从 dispatch/action/set/proxy mutation 映射到 set/commit。

3) 先替换读路径，再替换写路径

• 先替换组件订阅读取，确认渲染边界稳定。
• 再替换写入逻辑，减少迁移过程中行为漂移。

4) 接入能力扩展

• 持久化：persist。
• 调试：devtools / 更新日志。
• 高频更新：batch、schedule、throttle、debounce。

上线前验收清单

• 订阅粒度：组件是否优先订阅路径 Unit，而不是根节点。
• 边界序列化：SSR 边界是否只传 plain object。
• 批量写入：多字段更新是否统一 commit 或 batch。
• 回放能力：关键流程是否可通过更新日志定位问题。
• 清理机制：订阅是否有明确卸载与释放。

迁移中的常见误区

• 只“语法替换”不做订阅粒度重构，导致性能退化。
• 在 SSR 环境保留模块级单例 store，导致跨请求污染。
• 把 IO 当作“旧模型的别名”，没有利用路径级能力。

FAQ（高频问题）

Q1：迁移一定要一次性完成吗？

不建议。优先按业务切片渐进迁移，先跑通一条完整链路（读、写、持久化、调试），再扩展到下一块。

Q2：迁移后性能会自动提升吗？

不会自动提升。关键在于是否把订阅从根节点收敛到路径 Unit，并且是否对高频写入做 batch/schedule。

Q3：旧的 action/reducer/atom 代码要立刻删除吗？

不需要。建议先“并行保留 + 新链路灰度”，等回归稳定后再删除旧实现，降低回滚成本。

Q4：SSR 项目最容易踩的坑是什么？

模块级单例 store。必须按请求创建状态，并在 hydration 边界只传 plain object（通常是 snapshot() 结果）。

Q5：如何判断迁移质量达标？

至少满足三点：关键页面无渲染回归、关键流程可更新日志追踪、边界数据序列化一致且可复现。

下一步

• 查看 从 Zustand 迁移 或对应来源库文档。
• 进入 核心原理 巩固模型。