> 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-yi-pian-dai-ma-ke-shi-hua-de-mu-biao-yu-bian-jie/software-understanding-system.md).

# 从图形展示到软件理解系统

代码可视化经常被误解为“生成几张图”。例如生成类图、依赖图、调用图，或者把性能数据画成火焰图。这些图当然有价值，但它们只是最终表达层。真正能支撑工程决策的，不是一张孤立图片，而是一套持续更新的软件理解系统。

软件理解系统的目标是把代码、运行时、变更历史和工程上下文转化为可查询、可解释、可验证的事实。图形展示只是其中一种输出方式，其他输出还包括影响面报告、测试推荐、风险说明、Agent 上下文包和 Review 检查清单。

本章从系统视角拆解代码可视化：一个有用的代码可视化系统应该有哪些层次。

```mermaid
flowchart TB
  Data[数据采集层<br/>源码/构建/运行时/变更/组织] --> Analysis[程序分析层<br/>AST/符号/调用/Trace/Coverage]
  Analysis --> Graph[图谱建模层<br/>节点/边/属性/证据来源]
  Graph --> Query[可视化与查询层<br/>图/路径/报告/API]
  Query --> Workflow[工程集成层<br/>IDE/CI/PR/APM/AI Agent]
  Workflow --> Feedback[反馈更新<br/>测试结果/Review/运行时数据]
  Feedback --> Data
```

> 后续 AI 配图备注：可生成一张“软件理解系统分层架构图”的高清 PNG，用于替代 Mermaid。图中应体现数据采集、程序分析、图谱建模、可视化查询、工程集成五层闭环。

## 数据采集层

第一层是数据采集。没有可靠的数据，后面的分析和可视化都会变成猜测。

代码可视化的数据来源通常分为几类：

* 源码数据：文件、类、函数、变量、注解、配置。
* 构建数据：依赖包、模块关系、生成代码、编译结果。
* 静态分析数据：AST、符号表、类型关系、调用图、控制流、数据流。
* 动态运行数据：日志、Trace、Profile、Coverage、运行时调用。
* 变更数据：Git Diff、Commit、PR、Review、测试历史。
* 工程元数据：Owner、服务目录、架构规则、部署环境。

不同场景需要不同数据。代码库探索更依赖源码结构和符号关系；变更影响分析更依赖 Diff、调用图和测试覆盖；AI Review 更依赖影响面、测试证据、安全数据流和架构约束。

采集层最重要的原则是可追溯。每个分析结论最好能回到原始证据：哪一行代码、哪个提交、哪个 Trace、哪个测试结果。否则可视化结果很难被信任。

## 程序分析层

采集到数据后，需要通过程序分析把原始数据转化为更高层的事实。

程序分析可以分为静态分析和动态分析。静态分析不运行代码，直接从源码、依赖和配置中提取结构与关系。动态分析观察运行时行为，用 Trace、日志、Profile 和 Coverage 补足静态分析无法确认的事实。

静态分析可以回答：

* 哪些类实现了某个接口。
* 哪些方法调用了目标方法。
* 哪些模块存在循环依赖。
* 哪些方法复杂度过高。
* 哪些代码可能读写敏感数据。

动态分析可以回答：

* 真实请求经过哪些服务。
* 哪些路径最耗时。
* 哪些代码被测试覆盖。
* 哪些异常在生产环境频繁出现。
* 某个接口实际依赖哪些下游资源。

程序分析层的核心不是追求绝对完整，而是明确结论的边界。静态调用图可能存在误报和漏报，Trace 可能受采样影响，Coverage 只能说明执行过，不能说明行为正确。一个好的系统应该把这些不确定性暴露出来，而不是把所有结果包装成绝对事实。

## 图谱建模层

程序分析会产生大量事实，但如果这些事实散落在不同工具里，就很难形成系统理解。图谱建模层负责把这些事实组织起来。

一个代码图谱通常包含三类元素：

* 节点：仓库、文件、模块、类、方法、服务、接口、测试、团队。
* 边：包含、依赖、调用、引用、继承、实现、读写、覆盖、变更、拥有。
* 属性：复杂度、覆盖率、变更频率、耗时、错误率、风险等级、owner。

图谱建模的关键是围绕问题选择粒度。粒度太粗，无法定位具体影响；粒度太细，图会膨胀到不可理解。

例如做架构治理时，模块级和服务级节点更重要；做变更影响分析时，方法级和测试级节点更重要；做性能分析时，运行时 Span、服务和方法之间的映射更重要。

图谱层的价值在于连接。它可以把“某次 Diff 改了一个方法”连接到“哪些入口可能受影响”“哪些测试覆盖它”“哪个团队拥有它”“它是否处于高频变更热点”。这些连接让代码可视化从单点图表变成多证据推理。

## 可视化与查询层

图谱建立后，需要面向不同用户提供合适的表达。

人类开发者需要的是可探索的视图：

* 从模块地图进入代码库。
* 沿调用链下钻到具体方法。
* 过滤无关依赖。
* 高亮变更影响路径。
* 从图节点跳回源码、PR、测试和 Trace。

CI 或平台系统需要的是可计算的查询：

* 这次变更影响哪些测试。
* 哪些模块违反架构约束。
* 哪些文件是高风险热点。
* 哪些代码路径缺少覆盖。

AI Agent 需要的是结构化上下文：

* 与当前任务相关的文件有哪些。
* 目标方法的调用方和被调用方是谁。
* 改动可能影响哪些入口。
* 应该优先阅读哪些测试。
* 有哪些架构规则不能违反。

因此，可视化与查询层不应该只服务前端页面。它还应该提供 API、报告和工具接口，让人、CI 和 AI Agent 都能使用同一套事实。

## 工程集成层

代码可视化如果脱离开发流程，很容易变成偶尔打开看的工具。真正有价值的系统应该嵌入工程流程。

常见集成位置包括：

* IDE：代码阅读时展示调用方、影响路径和相关测试。
* PR：在 Review 页面展示影响面、风险节点和测试建议。
* CI：根据变更影响推荐测试集或阻断高风险变更。
* APM：从线上 Trace 跳回代码路径和 owner。
* 架构治理平台：持续检查依赖规则和模块边界。
* AI Agent：在修改前查询上下文，在修改后生成验证报告。

工程集成层决定了可视化结果是否会被使用。一个需要开发者手动打开、手动选择项目、手动分析的工具，很难成为日常流程的一部分。更好的方式是让结果出现在决策发生的位置：写代码时、提 PR 时、跑测试时、排查故障时、让 Agent 改代码时。

## 从一次性图表到持续更新的事实库

传统代码可视化常常是一次性生成：扫描一次代码，画一张图，供人查看。但现代软件系统持续变化，图表如果不能更新，很快就会过期。

软件理解系统应该更像一个事实库：

* 代码提交后更新结构和关系。
* 测试执行后更新覆盖信息。
* 服务运行后更新 Trace 和性能数据。
* PR 产生后更新变更和 Review 记录。
* 架构规则变化后重新评估依赖。

当事实库持续更新时，代码可视化就不只是文档，而是系统当前状态的一部分。它可以支撑长期治理，也可以给 AI Agent 提供最新上下文。

## 小结

代码可视化的最终形态不应该是一组静态图片，而应该是一套软件理解系统。它包含数据采集、程序分析、图谱建模、可视化查询和工程集成五个层次。

后续章节会沿着这条路径展开：先讲源码如何被结构化，再讲静态和动态分析如何提取代码事实，然后讲代码图谱如何建模，最后讨论这些能力如何服务核心工程场景和 AI 时代的新应用。

## 延伸阅读与参考资料

* [OpenTelemetry Observability Primer](https://opentelemetry.io/docs/concepts/observability-primer/)：理解日志、指标、Trace 等运行时观测数据的基础资料。
* [Backstage Software Catalog](https://backstage.io/docs/features/software-catalog/)：软件目录、实体关系和组织上下文建模的参考。
* [GitHub Docs: About code owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)：理解代码 Owner 如何进入工程治理流程。