deprecation-and-migration

Deprecation and Migration - 代码弃用与系统迁移指南

技能概述

Deprecation and Migration 是一个专注于安全移除旧代码和系统迁移的工程实践指南，帮助团队决策何时弃用、如何迁移、如何验证，以及如何避免技术债务积累。

适用场景

1. 替换旧系统、API 或库

当现有实现存在安全风险、维护成本过高，或新系统已经就绪时，本技能提供完整的弃用流程和迁移策略，包括 Strangler 模式、适配器模式等渐进式迁移方案。

2. 清理无人维护的僵尸代码

识别和处理那些"没人管但大家都在用"的代码，包括长期未更新但有活跃消费者的模块、存在安全漏洞的依赖、文档过时的系统等。

3. 数据库 Schema 迁移

最风险的数据层迁移实践，采用扩展/收缩（Expand/Contract）模式，确保每个步骤都可独立部署和回滚，避免在发布窗口期出现字段不存在或查询失败的问题。

核心功能

1. 弃用决策框架

通过 5 个关键问题评估是否应该弃用系统：是否还提供独特价值、有多少依赖用户、是否有替代方案、迁移成本如何、不弃用的维护成本是多少。区分强制弃用和建议性弃用，避免过度强制用户迁移。

2. 渐进式迁移模式库

提供多种经过验证的迁移模式：

Strangler 模式: 新旧系统并行运行，逐步将流量从旧系统切换到新系统

适配器模式: 保留旧接口，底层切换到新实现

特性标志迁移: 逐个用户或服务切换，降低风险

扩展/收缩模式: 数据库迁移的安全方法，先添加后删除，避免原地修改

3. 迁移验证清单

弃用完成后的验证清单，包括：替换方案已在生产验证、迁移文档完备、所有活跃消费者已迁移（通过指标/日志验证）、旧代码/测试/文档/配置完全清理、弃用公告移除。对于数据库迁移，额外验证每个阶段都可独立回滚、回填脚本分批执行、破坏性变更单独部署。

常见问题

什么时候应该弃用代码而不是继续维护？

当系统不再提供独特价值、存在活跃的替代方案、维护成本（安全风险、工程师时间、机会成本）超过迁移成本时，应该弃用。如果迁移成本过高，可以先用建议性弃用（警告、文档、提示）让用户自主迁移，等到维护成本不可持续时再转为强制弃用。

数据库迁移为什么要用扩展/收缩模式而不是直接修改？

因为在发布窗口期，新旧代码会同时运行。如果直接重命名或删除字段，一半的代码会查询不存在的字段导致失败。扩展/收缩模式确保每个阶段新旧代码都有效：先添加新字段（nullable），然后双写，再回填数据，接着切换读取，最后删除旧字段。每个步骤都可独立部署和回滚。

如何处理没人维护但大家都在用的僵尸代码？

僵尸代码不能保持无人问津的状态，要么投入资源正式维护，要么制定具体的弃用和迁移计划。识别僵尸代码的标志包括：6 个月以上没有提交但有活跃消费者、没有指派的维护者、测试失败无人修复、依赖有已知漏洞无人更新、文档引用不存在的系统。