> 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-san-pian-cheng-xu-fen-xi-yu-dai-ma-tu-pu/visualization-as-evidence.md).

# 可视化表达：从图到证据

代码可视化不能只追求“看起来清楚”，还要能支持判断。好的视图应该回答具体工程问题，并且能够追溯到证据来源。

前几章讨论了如何提取和组织代码事实。本章讨论表达层：如何把这些事实呈现给人，如何避免图形误导，以及如何让可视化成为 Review、验证和治理中的证据。

## 先定义问题，再选择视图

可视化设计最常见的错误，是先决定画什么图，再思考它能解决什么问题。工程场景中应该反过来：先定义问题，再选择视图。

例如：

* 想知道谁调用了目标方法，用调用图或调用列表。
* 想判断模块边界，用依赖图或依赖矩阵。
* 想定位性能热点，用火焰图或 Trace Waterfall。
* 想解释用户输入流向危险操作，用数据流路径图。
* 想判断变更风险，用影响面图和测试覆盖报告。
* 想理解系统演进，用变更时间线和热点图。

同一份代码图谱可以生成不同视图。视图不是事实本身，而是面向问题的投影。

## 常见视图及适用场景

调用图适合理解函数或方法之间的关系。它适合回答“谁调用谁”，但大规模调用图很容易变得不可读，因此通常需要限制深度、聚合模块或从某个入口开始展示。

依赖图适合理解模块、包、服务之间的边界。它适合架构治理、循环依赖发现和模块拆分。

继承图适合理解类型层次、接口实现和扩展点。它对面向对象系统特别有用。

控制流图适合解释单个函数内部复杂分支，不适合展示整个系统。

数据流图适合安全分析、隐私审查和数据血缘解释，尤其适合展示 Source 到 Sink 的路径。

热力图适合突出风险：复杂度、变更频率、缺陷密度、性能热点、低覆盖区域都可以映射成热度。

时间线适合表达演进：版本变化、PR、事故、重构和质量趋势。

火焰图适合定位性能热点，但它表达的是采样聚合，不是完整调用关系。

## 图太大时怎么办

真实代码库的图很容易过大。一个中型项目可能有数千个文件、数万个方法、更多调用边。直接展示全量图通常没有意义。

常见处理方式包括：

* 按模块聚合。
* 限制调用深度。
* 只展示与当前任务相关的子图。
* 根据运行时频率过滤低价值边。
* 根据风险等级突出重点节点。
* 提供搜索和下钻，而不是一次性展开所有节点。

好的可视化应该支持从概览到细节的路径：先看到系统结构，再进入模块，再进入文件和方法，最后跳回源码和证据。

## 交互能力

工程可视化需要交互。静态图片适合文档说明，但日常开发需要查询和探索。

关键交互包括：

* 搜索：快速定位文件、类、方法、服务。
* 过滤：按关系类型、模块、风险等级、时间范围筛选。
* 聚合：把方法聚合成类，把类聚合成模块。
* 下钻：从系统图进入局部路径。
* 路径高亮：展示从变更点到入口或测试的路径。
* 对比：展示改动前后、版本之间、分支之间的结构变化。
* 跳转：从图节点跳到源码、PR、测试、Trace、日志。

没有跳转能力的可视化很难成为工程工具。开发者最终需要回到证据现场，而不是停留在图上。

## 从结果到证据链

影响面报告不能只说“模块 A 受影响”，它应该展示证据链：

```
变更方法
  -> 被服务方法调用
  -> 被 Controller 入口调用
  -> 被测试用例覆盖
  -> 过去 7 天生产 Trace 中出现过
```

这样的路径才是可验证的。Reviewer 可以沿路径检查代码，测试平台可以运行相关测试，Agent 可以把路径作为上下文。

证据链应该包含来源：

* 这条调用边来自静态解析还是运行时 Trace。
* 覆盖关系来自哪次测试报告。
* 变更频率统计的时间窗口是什么。
* Owner 信息来自哪个配置。

可视化越参与决策，就越需要解释来源。

## 可视化的误导风险

图会放大某些关系，也会隐藏某些关系。常见误导包括：

* 把候选调用当成确定调用。
* 把静态可达路径当成运行时真实路径。
* 把 Coverage 当成行为正确。
* 把图中没有边误解为没有关系。
* 把节点大小或颜色当成绝对风险。
* 忽略采样、版本和时间窗口。

因此，代码可视化系统应该明确标注不确定性。例如边的来源、置信度、更新时间、分析范围，都应该尽量可见。

## 面向 AI Review 的表达

AI 时代，可视化表达不只是给人看，还要转化为 Review 证据。

AI 修改代码后，系统可以生成：

* 改动范围图。
* 影响路径图。
* 相关测试列表。
* 未覆盖风险路径。
* 架构约束检查结果。
* 安全数据流路径。
* 运行时热点提示。

这些结果可以进入 PR 描述或 Review 页面。人类 Reviewer 不需要完全相信 AI 的自然语言总结，而是可以查看代码图谱提供的证据。

## 面向 Agent 的表达

Agent 不一定需要图形界面。它更需要结构化查询结果。

同一个可视化系统可以为 Agent 输出：

* JSON 形式的调用路径。
* Markdown 形式的影响面报告。
* 相关文件列表。
* 风险节点列表。
* 测试推荐。

因此，“可视化表达”不只是图形 UI，也包括机器可读的证据表达。人看图，Agent 查图，CI 消费报告，它们应该共享同一套事实。

## 小结

代码可视化的重点不是图形本身，而是把代码事实组织成可判断、可追溯、可验证的证据。视图要围绕问题设计，交互要支持从概览到源码，结论要能追溯来源。

到这里，前三篇完成了从源码结构化、程序分析到代码图谱和证据表达的基础。下一篇会进入三个核心工程场景：代码库理解、变更影响分析、架构理解与遗留系统改造。