做 schema/数据/API/协议/配置/依赖迁移时…

适用于任何需要可回滚、兼容安全并需证明数据保留的 schema、数据、API、协议、配置或依赖迁移。

适用场景

解决思路

1. 编辑前先梳理现状：当前有哪些 reader、writer，数据结构长什么样，兼容窗口有多长，以及各部分的归属方（ownership）。
2. 同时定义前进路径（forward path）和回滚路径（rollback path）。
3. 保留既有数据；把破坏性步骤显式列出，并单独授权后才能执行。
4. 在发布可能重叠的场景下，保证混合版本（mixed-version）并行运行是安全的。
5. 在适用时按 expand → migrate → verify → contract 的顺序推进。
6. 让重试具备幂等性，并让部分失败（partial failure）可观测。
7. 在迁移所需的各个阶段，同时验证旧路径和新路径。
8. 当请求的阶段通过后就停止；不要隐式地执行后续的破坏性收缩（contraction）步骤。

适用边界 · 注意事项

• 没有回滚需求、可接受一次性停机且无需保留历史数据的一次性改动。
• 无法承担新旧路径并存（双读/双写、混合版本）成本且兼容窗口为零的场景。