> 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-si-pian-san-ge-he-xin-gong-cheng-chang-jing/architecture-and-legacy-modernization.md).

# 架构理解与遗留系统改造

遗留系统最需要的往往不是立即重构，而是先恢复理解。没有系统地图的重构，很容易把隐性依赖、业务规则和团队知识一起破坏。

架构理解与遗留系统改造是代码可视化的第三个核心工程场景。它关注的不是某次小变更，而是如何在长期演进后重新看清系统边界，并找到可验证的改造路径。

## 遗留系统的真正困难

遗留系统难维护，通常不是因为它“旧”，而是因为它缺少可依赖的理解模型。

常见问题包括：

* 模块边界和业务边界不一致。
* 公共工具包承载了大量业务逻辑。
* 数据库表被多个业务共享。
* 配置、脚本和批任务隐藏关键规则。
* 没有人能完整解释调用路径。
* 测试不足，修改后缺少验证依据。
* 历史重构留下半完成状态。

如果在这种状态下直接让人或 AI 大规模重构，风险会非常高。正确顺序应该是先恢复系统地图，再选择小步改造点。

## 模块边界识别

模块边界可以从多个信号推断：

* 目录和包名。
* 构建模块。
* 依赖关系。
* 业务入口。
* 数据库表和资源访问。
* 变更耦合。
* 团队 owner。

这些信号可能相互冲突。例如目录上看是两个模块，但历史上总是一起变更；依赖图上看没有直接关系，但它们读写同一张核心表；团队 owner 已经变更，但代码包名还保留旧业务名称。

边界识别的目标不是得到完美架构图，而是找到可以讨论和验证的拆分单元。一个可用的模块边界应该能回答：它有哪些入口，依赖谁，被谁依赖，拥有哪些数据，谁负责，如何验证。

## 服务和资源依赖

现代系统的依赖不只存在于代码调用里。服务可能依赖数据库、缓存、队列、外部 API、文件存储、配置中心、任务调度和权限系统。

遗留系统改造时，资源依赖经常比代码依赖更关键。比如一个模块看起来可以独立拆分，但它和其他模块共享数据库表；一个服务接口看起来不再被调用，但消息消费者仍然依赖它写入数据。

资源依赖图可以帮助判断：

* 哪些数据库表被多个模块共享。
* 哪些消息 topic 连接多个业务域。
* 哪些外部 API 是核心路径。
* 哪些配置项影响多个服务。
* 哪些资源需要先隔离再迁移。

这类视图能避免只按代码目录做重构。

## 技术债和热点识别

遗留系统中，重构资源通常有限，不可能一次性改完。需要找到优先级最高的区域。

可以组合以下信号识别热点：

* 复杂度高。
* 变更频率高。
* 缺陷历史多。
* 测试覆盖低。
* 多团队交叉修改。
* 运行时高频或高错误率。
* 位于关键业务路径。

单个指标容易误导。比如一个复杂但稳定的老模块不一定需要优先重构；一个不复杂但频繁出问题的模块可能更值得处理。热点识别应该把静态、动态和变更数据结合起来。

## 重构路径设计

重构不是一次性推翻重写，而是连续的小步改造。代码可视化可以帮助设计重构顺序：

1. 先识别边界清晰、测试较好的局部模块。
2. 再处理高频变更、高风险热点。
3. 对共享数据和公共依赖建立隔离层。
4. 对核心路径补充测试和运行时观测。
5. 每一步都输出结构变化和验证结果。

这种方式比“大重写”更可控，也更适合 AI 辅助。AI 可以承担局部机械改造，但系统必须用图谱和测试证明每一步的影响可控。

## 重构前后对比

重构是否成功，不能只看代码风格是否变好。更重要的是行为和边界是否符合预期。

对比项包括：

* 模块依赖是否减少。
* 循环依赖是否消除。
* 调用路径是否保持关键行为。
* 数据读写是否仍然一致。
* 测试覆盖是否提升。
* 运行时指标是否稳定。
* 架构规则是否更清晰。

重构前后对比本质上也是一种可视化：它把结构变化、行为变化和验证结果放在同一张证据表里。

## 架构守护

系统改造后，还需要防止结构再次腐化。架构守护可以通过规则持续执行：

* 禁止跨层调用。
* 禁止新模块依赖旧模块。
* 禁止核心域依赖实验性组件。
* 共享表访问必须经过指定接口。
* 新接口必须声明 owner 和测试。

这些规则可以进入 CI 或 PR Review。代码图谱提供规则执行所需的依赖、调用、资源和 owner 信息。

## AI 辅助改造的边界

AI 在遗留系统改造中很有价值，但更适合做小步、明确、可验证的任务：

* 批量迁移 API 调用。
* 提取重复逻辑。
* 生成补充测试。
* 更新配置或类型声明。
* 重命名符号。
* 按规则移动代码。

不适合直接让 AI 在缺少系统地图的情况下做大规模重构。没有边界和验证，AI 很可能生成局部合理但全局危险的改动。

因此，AI 辅助重构的前置条件是：有代码图谱，有影响面分析，有测试和运行时证据，有架构约束。

## 小结

架构理解与遗留系统改造的核心，是先恢复系统事实，再进行小步验证。代码可视化在这里不是画一张静态架构图，而是建立可以持续更新的系统地图。

第四篇到这里完成了三个核心工程场景：代码库理解、变更影响分析、架构理解。下一篇会进入 AI 时代的新应用，讨论这些能力如何升级为 Agent 上下文、AI Review 证据和软件理解基础设施。