> For the complete documentation index, see [llms.txt](https://code-visualization.shawnxie.top/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://code-visualization.shawnxie.top/di-wu-pian-ai-shi-dai-de-xin-ying-yong/ai-assisted-refactoring-and-migration.md).

# AI 辅助重构与系统迁移

AI 可以加速重构，但重构的前提仍然是理解边界和验证行为。没有代码图谱和验证机制，AI 重构会放大风险。

重构和迁移通常涉及多个文件、多个模块、多个测试，甚至多个服务。它们不是简单生成代码，而是需要持续判断：边界是否清晰，行为是否保持，风险是否可控。

## AI 适合做什么

AI 在重构中很适合做明确、机械、可验证的任务：

* 批量替换 API 调用。
* 按规则重命名符号。
* 提取重复代码。
* 拆分过长函数。
* 生成适配层。
* 补充测试样例。
* 迁移配置格式。
* 更新类型声明。

这些任务有明确输入和输出，容易通过编译、测试和结构检查验证。

## AI 不适合直接做什么

AI 不适合在缺少系统地图的情况下直接做大规模重构。例如：

* 一次性重写核心模块。
* 在没有测试覆盖的情况下改业务规则。
* 凭局部代码判断架构边界。
* 未理解数据模型就迁移存储。
* 未识别调用方就修改公共接口。

这类任务的风险不在代码生成，而在系统理解。AI 可以参与，但必须被代码图谱、影响面分析和验证流程约束。

## 重构前恢复系统边界

重构前首先要恢复系统边界：

* 模块之间如何依赖。
* 哪些入口触发目标模块。
* 目标模块读写哪些资源。
* 哪些测试覆盖目标路径。
* 哪些文件历史上经常一起变化。
* 哪些团队拥有相关代码。

这些信息决定重构计划。没有边界，AI 很容易把局部改动扩散成不可控变更。

## 小步改动

AI 辅助重构应该遵循小步原则：

1. 每次只处理一个明确目标。
2. 每次改动都能生成影响面报告。
3. 每次改动都有对应测试或验证方式。
4. 每次改动都能回滚。

小步改动适合 AI，因为它可以快速执行机械任务；也适合人类 Review，因为影响范围可控。

## 行为保持验证

重构的目标通常是不改变外部行为。因此验证重点不是“新代码是否更漂亮”，而是“行为是否保持”。

可以使用：

* 单元测试和集成测试。
* Golden Master 或快照测试。
* API 合约测试。
* Trace 路径对比。
* 数据读写对比。
* 性能指标对比。

如果旧系统缺少测试，AI 直接重构前应先补充 characterization test，用测试记录当前行为，再进行改造。

## 架构约束保护

重构过程中，架构约束应该持续执行：

* 新模块不能反向依赖旧模块。
* 业务层不能直接访问基础设施细节。
* 数据访问必须经过统一接口。
* 公共接口修改必须更新调用方。
* 跨团队模块需要 owner Review。

这些约束可以来自代码图谱和规则引擎。AI 修改代码时，系统应该及时提示或阻断违规依赖。

## 系统迁移中的图谱价值

系统迁移常见场景包括：

* 单体拆分为服务。
* 老框架迁移到新框架。
* 数据库表拆分。
* API 协议升级。
* 语言或运行时升级。

迁移需要知道源系统和目标系统之间的映射。代码图谱可以帮助建立迁移清单：

* 哪些入口需要迁移。
* 哪些调用方依赖旧接口。
* 哪些数据表需要兼容。
* 哪些测试必须通过。
* 哪些模块可以先迁移，哪些必须后迁移。

AI 可以根据清单执行局部迁移，但迁移顺序和验证策略仍应由系统事实和人工决策共同决定。

## 迁移验证报告

每次迁移或重构后，应该输出验证报告：

* 本次迁移范围。
* 结构变化。
* 行为路径对比。
* 影响面。
* 测试结果。
* 未覆盖风险。
* 架构规则检查。
* 回滚建议。

这份报告比普通变更说明更适合决策。它证明迁移不是“代码改完了”，而是“系统行为和边界被验证过”。

## 小结

AI 辅助重构的关键不是让 AI 一次性重写系统，而是让 AI 在清晰边界、明确任务和可验证证据下执行小步改造。代码图谱、影响面分析、测试覆盖和架构规则，是让 AI 重构可控的基础。

下一章会把视角进一步扩大，讨论代码可视化如何演进为软件理解基础设施。