SuperAPI AI 工具集

deprecation-and-migration

编程与开发

查看项目

更新于 11-15 16:08

技能介绍

用途

该技能用于指导软件生命周期中的“移除”环节:判断是否弃用代码、如何通知消费者、如何在不中断服务的情况下迁移消费者,以及在删除前如何证明旧路径确实无人使用。它强调代码是负债,弃用是移除不再创造价值的代码的纪律,迁移是先将消费者安全转移再删除的过程。

主要能力

  • 弃用决策树:通过五个问题决定是否弃用:是否仍有独特价值、是否存在替代方案、有多少消费者、每个消费者的迁移成本、不弃用的2-3年成本。
  • Hyrum定律应用:提醒公告不等于迁移,需枚举行为差异(状态码、错误信息、顺序、默认值等),并区分建议性弃用与强制性弃用。
  • 弃用通知模板:提供包含状态、替代方案、移除时间、支持窗口、原因、变更对照表、迁移步骤和帮助渠道的模板,要求同时发布到CHANGELOG、文档和运行时信号。
  • 扩展/收缩(并行变更)模式:分阶段迁移,包括添加新字段、双写、回填、切换读取、停止写入旧字段、最终删除,适用于重命名、删除和类型变更。
  • 代码修改工作流:使用语法感知工具(jscodeshift、ast-grep、comby等)进行自动化重写,要求幂等、试运行、小批量评审、删除旧路径。
  • 支持窗口策略:结合语义化版本,定义公共API弃用后最早在下一个主版本移除,最小窗口为一个完整次版本或90天(取较长者)。
  • 证据门:删除前必须满足:grep零调用、运行时指标为零、测试更新且通过、文档和CHANGELOG记录移除、弃用通知移除、存在回滚路径。
  • 服务下线清单:涵盖流量(410 Gone响应、保持墓碑端点)、数据(保留决策、备份验证、PII删除)、访问(凭证撤销、DNS移除)、运维(告警移除、成本归零)等方面。

使用方式

该技能以文档形式提供指导,用户可按照其中的决策树、模板、工作流和清单执行弃用与迁移任务。具体使用包括:回答决策树问题、填写通知模板、实施扩展/收缩迁移步骤、运行代码修改工具(如npx jscodeshift -t codemods/rename-call.ts src/ --dry --print)、检查支持窗口和证据门清单。

适用场景

  • 移除公共API、端点、导出符号、CLI标志或配置键。
  • 替换实现并将调用方迁移到新实现。
  • 在生产环境中重命名或删除数据库列而不停机。
  • 下线整个服务、主机名或凭证集。
  • 决定是继续维护遗留系统还是投资迁移。

限制

该技能不适用于保持行为的内部重构(应使用safe-refactor)或简化单个文件内的可读性(应使用code-simplification)。它针对跨边界变更,即版本、包、契约或运行中的生产系统。资料未提供该技能的具体安装命令、平台依赖或收费信息。