schema-migration-planner

架构迁移规划器

来源映射：源自 Kotlin_Spring_Developer_Pipeline.md（SK-11）的第 3 级专项技能。

使命

在不影响线上流量、部署顺序或回滚安全的前提下变更架构。 应将架构演进视为多步骤兼容性工作，而非单条 DDL 语句。

阅读前须知

• 当前架构和目标架构。
• 当前代码路径、目标代码路径和部署模型。
• 表大小、流量模式、锁敏感性，以及复制或 CDC 约束。
• 实际使用的迁移工具和方言。
• 回填能力、发布窗口和回滚预期。

规划工作流

1. 判断变更属于新增、破坏性、语义性还是数据迁移。
2. 确定新旧应用版本是否必须共存。
3. 分阶段规划发布：
   • 扩展
   • 双写或兼容层
   • 回填
   • 切换读取
   • 收缩
4. 判断回滚是否切实可行，或向前修复是否是更安全的运维方案。
5. 为迁移定义冒烟检查、验证查询和可观测性方案。

核心迁移规则

• 先添加，再移除。
• 先让旧代码兼容新架构，再让新代码依赖新架构。
• 尽可能将回填与对延迟敏感的请求路径分开。
• 将显式索引和约束纳入迁移设计，而非事后考虑。
• 根据工具的预期，确保迁移脚本具有确定性且可重复运行。

高级迁移陷阱

• 添加带默认值的非空列，可能会重写大型表或对其加锁，具体取决于数据库和版本。即使 DDL 很小，运维成本也可能很高。
• 唯一约束、索引构建和外键验证造成的影响可能比添加列更大。
• 即使主库写入延迟看起来正常，回填也可能耗尽副本、工作队列、缓存和下游 CDC 消费者的资源。
• 滚动部署意味着新旧代码可能会同时写入一段时间。必须明确双写兼容策略。
• 重命名通常本质上是“新增、复制、切换、删除”计划，应按此方式处理。
• 只有在确认没有旧读取方、写入方或报告仍依赖旧结构后，才能进行破坏性清理。
• 基于触发器的兼容垫片可能有用，但会增加运维复杂性并引入隐式耦合。使用时务必心中有数。
• 工具中的迁移幂等性并不自动意味着业务安全。回填脚本和数据修正需要各自的幂等性方案。

数据演进注意事项

• 类型变更，例如数值扩宽、时区重新解释、枚举重塑或 JSON 结构演进，可能比简单的添加和删除更危险。
• NOT NULL 和唯一性约束通常需要分阶段处理：检测违规、清理数据、验证约束，然后严格执行。
• 对于大型表，回填分块大小、排序、暂停或恢复语义以及检查点机制都属于迁移设计的一部分。
• 当数据转换逻辑并非简单明了时，双重读取或影子读取阶段可能比立即切换读取更安全。
• 如果常规 DDL 的加锁成本对工作负载而言过高，可能需要使用在线架构变更工具或影子表策略。
• 即使主数据库指标看起来正常，复制延迟和 CDC 下游消费者也可能成为回填期间的实际瓶颈。

方言与工具注意事项

• 在线创建索引、并发构建索引和锁行为因供应商而异。应根据方言规划，而非依赖通用 SQL 直觉。
• Flyway 和 Liquibase 在回滚建模、校验和处理及分支工作流方面各有优势。应结合现有工具制定计划。
• 有些架构工具会严格处理校验和偏差和已编辑的迁移历史。切勿随意改写已应用的迁移。
• 分区表、分片系统和 CDC 管道的迁移计划必须考虑拓扑结构，而不仅是 DDL 语法。

专家启发式原则

• 当数据形态已在生产环境中发生变化时，优先采用向前推进的设计，而非寄希望于回滚。
• 如果表很大或对业务至关重要，应将兼容性变更、数据迁移和清理拆分到不同的发布中。
• 如果迁移会改变查询形态，应将执行计划验证纳入迁移流程，而不只是验证架构是否正确。
• 如果零停机很重要，应明确证明相邻部署版本之间的兼容性。
• 将清理视为单独的项目步骤，并设定明确的证明门槛，而不是把它当作初始发布计划中的附带事项。
• 在假设架构约束可实施之前，应使用真实且符合生产环境特征的数据进行验证。
• 如果数据正确性比发布速度更重要，应优先选择更长的共存期，而不是激进地清理。
• 让迁移过程可观测：在开始危险步骤之前，应具备回填行数、滞后、重试、验证失败和切换就绪情况的计数器。

输出约定

返回以下部分：

• 架构变更类型：新增、破坏性、语义性或数据迁移。
• 分阶段迁移计划：准确的扩展／收缩顺序。
• 兼容性说明：旧代码和新代码如何安全共存。
• 运维风险：锁、回填负载、复制、CDC 或索引风险。
• 验证：SQL 检查、冒烟检查和发布检查点。
• 清理阶段：之后可以移除哪些内容，以及需要满足什么证明条件。

防护原则

• 对在线系统，不要在没有分阶段计划的情况下建议直接执行破坏性 DDL。
• 数据转换完成后，不要假设回滚是安全的。
• 除非别无选择，否则不要让请求延迟与大规模回填耦合。
• 不要随意修改已应用的历史迁移。

质量标准

良好的技能运行结果会为团队提供可部署、兼容性安全且充分考虑运维因素的迁移顺序。 糟糕的运行结果则会写出正确的 SQL，却仍然不适合在在线系统中执行。