代码迁移

何时使用

• 老项目要升级框架或语言版本;
• 把一段代码从一个技术栈迁到另一个;
• 替换弃用的依赖;
• 用户说"帮我把这个项目从 X 迁到 Y"。

使用步骤

第 1 步:评估现状

动手前先摸清:

1. 代码规模:多少文件、多少行、几个模块;
2. 依赖情况:框架版本、弃用项、风险依赖;
3. 测试覆盖:有没有测试,覆盖率多少;
4. 行为清单:核心功能、边界行为、已知怪癖(怪癖也是要保留的行为)。

输出一份现状清单,标出高风险区域。

第 2 步:选迁移策略

优先增量,不要推倒重写:

第 3 步:分批迁移

把迁移拆成可独立交付的小批:

1. 每批只动一个模块或一个依赖;
2. 每批开始前有测试兜底;
3. 每批结束可以独立上线;
4. 每批有明确的完成标准。

第 4 步:迁移与验证

每批按这个循环走:

备份 → 迁移 → 跑测试 → 对照行为清单 → 上线/回滚

• 用工具辅助:codemod、编译器自动迁移、lint 修复;
• 人工核对行为差异,机器翻译不了的语义变化重点看;
• 对比新旧行为:输入相同,输出和副作用要一致;
• 行为不一致时,先确认是"新实现错了"还是"旧行为是 Bug"(Bug 不用保留)。

第 5 步:输出迁移报告

# 迁移报告:<目标>

## 现状与范围
## 策略与批次划分
## 每批结果(测试、行为对照、上线情况)
## 行为差异清单(改了哪些旧行为)
## 遗留风险

输入与输出

• 输入:项目路径 + 迁移目标;
• 输出:分批迁移结果 + 行为差异清单 + 迁移报告。

示例

需求: 把 Python 2 项目迁到 Python 3。

评估: 300 个文件,核心模块 5 个,有测试但覆盖率只有 40%。

策略: 试点先行,先迁 utils 模块。

批次:

1. 工具链迁移(2to3/futurize 跑语法);
2. 核心模块逐个迁移,每批补测试;
3. 兼容层移除;
4. 全量回归 + 修复编码问题。

结果: 每批独立合入,行为对照清单确认无回归。

参考

四种策略的选型、执行要点和风险控制清单见 references/STRATEGIES.md。

辅助脚本

scripts/migration_checklist.py 生成迁移检查清单:自动统计仓库文件,输出现状评估、策略选项、分批计划模板:

python scripts/migration_checklist.py "Python 2 迁到 Python 3"

清单需要人工补充测试覆盖、风险区域等内容。

注意事项

• 不要推倒重写:重写的成本远超预期,历史行为会丢;
• 先补测试再迁移,没有测试兜底,改了也发现不了问题;
• 一次只动一个变量,同时换框架又重构逻辑,出问题说不清是谁的;
• 老代码的"怪癖"是行为,先记录再决定保不保留;
• 迁移工具自动改的代码,也要人工过一遍关键逻辑。

不适用场景

• 没有明确迁移目标;
• 代码没有版本管理(先初始化 git);
• 迁移涉及的生产系统无法分批上线(需先和团队确认策略)。

验证方式

1. 触发:"帮我把项目迁到 X";
2. 检查:有现状评估、分批计划、行为对照清单;
3. 走查:每批有测试结果,行为差异有记录。