JSCodeshift 代码重构

问题：手工重构在大型代码库中不可持续

当代码库规模增长到数千个文件后，手工执行 API 重写、批量迁移或大规模重构会遇到两个问题：一是遗漏，二是不可重复。手工修改一次只能覆盖当前工作区，无法保证下次拉取新分支后同样完成；代码评审时也难以给出统一、可审查的差异。这类工作需要一种机制，能把「修改规则」固化下来，随时在任意 checkout 上重新执行。

核心能力：把迁移规则写成 AST 转换

该技能基于 jscodeshift，将 JavaScript 和 TypeScript 的批量迁移表达为 基于 AST 的 codemods。核心思路不是做字符串替换，而是解析源码为语法树，按节点结构匹配目标模式，再按规则生成替换节点。这样转换具备几个特点：

• 可重复：同样的规则可以在不同分支、不同时间重复执行，结果一致。
• 可审查：每次运行产生的差异聚焦在 AST 层，便于 review。
• 可组合：不同迁移规则可以独立编写、单独运行或组合使用。

关键步骤通常包括：用 runner 解析目标文件，遍历匹配节点，按规则构造替换，最后输出统一的差异结果。运行环境需要 Node.js、npm 或 pnpm，以及 Git 工作流配合。

适用边界与注意事项

这种方案适合语法层面明确的迁移，例如 API 签名调整、导入路径改写、重复模式统一。但它不能替代语义理解：如果转换依赖运行时行为或跨文件上下文，纯 AST 匹配可能不够。此外，codemod 本身需要测试覆盖，大规模执行前建议先在小范围分支验证差异。