可视化表达：从图到证据
代码可视化不能只追求“看起来清楚”，还要能支持判断。好的视图应该回答具体工程问题，并且能够追溯到证据来源。
前几章讨论了如何提取和组织代码事实。本章讨论表达层：如何把这些事实呈现给人，如何避免图形误导，以及如何让可视化成为 Review、验证和治理中的证据。
先定义问题，再选择视图
可视化设计最常见的错误，是先决定画什么图，再思考它能解决什么问题。工程场景中应该反过来：先定义问题，再选择视图。
例如：
想知道谁调用了目标方法，用调用图或调用列表。
想判断模块边界，用依赖图或依赖矩阵。
想定位性能热点，用火焰图或 Trace Waterfall。
想解释用户输入流向危险操作，用数据流路径图。
想判断变更风险，用影响面图和测试覆盖报告。
想理解系统演进，用变更时间线和热点图。
同一份代码图谱可以生成不同视图。视图不是事实本身，而是面向问题的投影。
常见视图及适用场景
调用图适合理解函数或方法之间的关系。它适合回答“谁调用谁”，但大规模调用图很容易变得不可读，因此通常需要限制深度、聚合模块或从某个入口开始展示。
依赖图适合理解模块、包、服务之间的边界。它适合架构治理、循环依赖发现和模块拆分。
继承图适合理解类型层次、接口实现和扩展点。它对面向对象系统特别有用。
控制流图适合解释单个函数内部复杂分支，不适合展示整个系统。
数据流图适合安全分析、隐私审查和数据血缘解释，尤其适合展示 Source 到 Sink 的路径。
热力图适合突出风险：复杂度、变更频率、缺陷密度、性能热点、低覆盖区域都可以映射成热度。
时间线适合表达演进：版本变化、PR、事故、重构和质量趋势。
火焰图适合定位性能热点，但它表达的是采样聚合，不是完整调用关系。
图太大时怎么办
真实代码库的图很容易过大。一个中型项目可能有数千个文件、数万个方法、更多调用边。直接展示全量图通常没有意义。
常见处理方式包括：
按模块聚合。
限制调用深度。
只展示与当前任务相关的子图。
根据运行时频率过滤低价值边。
根据风险等级突出重点节点。
提供搜索和下钻，而不是一次性展开所有节点。
好的可视化应该支持从概览到细节的路径：先看到系统结构，再进入模块，再进入文件和方法，最后跳回源码和证据。
交互能力
工程可视化需要交互。静态图片适合文档说明，但日常开发需要查询和探索。
关键交互包括：
搜索：快速定位文件、类、方法、服务。
过滤：按关系类型、模块、风险等级、时间范围筛选。
聚合：把方法聚合成类，把类聚合成模块。
下钻：从系统图进入局部路径。
路径高亮：展示从变更点到入口或测试的路径。
对比：展示改动前后、版本之间、分支之间的结构变化。
跳转：从图节点跳到源码、PR、测试、Trace、日志。
没有跳转能力的可视化很难成为工程工具。开发者最终需要回到证据现场，而不是停留在图上。
从结果到证据链
影响面报告不能只说“模块 A 受影响”，它应该展示证据链：
这样的路径才是可验证的。Reviewer 可以沿路径检查代码，测试平台可以运行相关测试，Agent 可以把路径作为上下文。
证据链应该包含来源：
这条调用边来自静态解析还是运行时 Trace。
覆盖关系来自哪次测试报告。
变更频率统计的时间窗口是什么。
Owner 信息来自哪个配置。
可视化越参与决策，就越需要解释来源。
可视化的误导风险
图会放大某些关系，也会隐藏某些关系。常见误导包括：
把候选调用当成确定调用。
把静态可达路径当成运行时真实路径。
把 Coverage 当成行为正确。
把图中没有边误解为没有关系。
把节点大小或颜色当成绝对风险。
忽略采样、版本和时间窗口。
因此，代码可视化系统应该明确标注不确定性。例如边的来源、置信度、更新时间、分析范围，都应该尽量可见。
面向 AI Review 的表达
AI 时代，可视化表达不只是给人看，还要转化为 Review 证据。
AI 修改代码后，系统可以生成：
改动范围图。
影响路径图。
相关测试列表。
未覆盖风险路径。
架构约束检查结果。
安全数据流路径。
运行时热点提示。
这些结果可以进入 PR 描述或 Review 页面。人类 Reviewer 不需要完全相信 AI 的自然语言总结，而是可以查看代码图谱提供的证据。
面向 Agent 的表达
Agent 不一定需要图形界面。它更需要结构化查询结果。
同一个可视化系统可以为 Agent 输出：
JSON 形式的调用路径。
Markdown 形式的影响面报告。
相关文件列表。
风险节点列表。
测试推荐。
因此，“可视化表达”不只是图形 UI，也包括机器可读的证据表达。人看图，Agent 查图，CI 消费报告，它们应该共享同一套事实。
小结
代码可视化的重点不是图形本身，而是把代码事实组织成可判断、可追溯、可验证的证据。视图要围绕问题设计，交互要支持从概览到源码，结论要能追溯来源。
到这里，前三篇完成了从源码结构化、程序分析到代码图谱和证据表达的基础。下一篇会进入三个核心工程场景：代码库理解、变更影响分析、架构理解与遗留系统改造。
Last updated