> 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/change-impact-verification.md).

# 变更影响分析与验证

变更影响分析回答的问题是：这次修改会影响谁，应该如何验证。它是代码可视化最有工程价值的场景之一，也是 AI 生成代码后必须补强的能力。

一次代码修改真正的风险，通常不在 Diff 本身，而在 Diff 连接出去的关系网络里。改动了哪个方法只是起点；这个方法被哪些入口调用、影响哪些测试、涉及哪些资源、是否处于高频运行路径，才决定验证策略。

```mermaid
flowchart LR
  Diff["Git Diff"] --> Entity["变更实体<br/>方法/类/配置/资源"]
  Entity --> Callers["反向调用链"]
  Entity --> Resources["资源依赖"]
  Callers --> Entrypoints["业务入口"]
  Resources --> Entrypoints
  Entity --> Tests["相关测试"]
  Entrypoints --> Risk["风险分级"]
  Tests --> Report["影响面报告"]
  Risk --> Report
```

> 后续 AI 配图备注：可生成一张“PR 页面中的影响面分析报告”界面 mockup，突出变更实体、影响路径、建议测试和风险标签。

## 为什么 Diff 不够

Diff 只能告诉我们“改了什么”，不能完整告诉我们“影响了什么”。

例如一次修改只改了一个工具方法，看起来很小。但如果这个方法被多个核心业务入口调用，且缺少完整测试覆盖，它的风险可能很高。相反，一次修改涉及多个文件，但都在低风险后台路径上，且相关测试覆盖充分，风险可能可控。

影响面分析的任务，是把行级 Diff 转换成工程意义上的影响路径。

## 从 Diff 到变更实体

第一步是把 Diff 映射到代码实体。

行级变化可以进一步映射为：

* 变更方法。
* 变更类或接口。
* 变更字段。
* 变更配置项。
* 变更路由或 API。
* 变更数据库访问。
* 变更测试。

这一步依赖 AST 和符号表。只有知道行号属于哪个方法、方法属于哪个类、类属于哪个模块，才能进入图谱追踪。

对于配置、SQL、路由和消息 topic，映射会更复杂。它们可能不是普通代码节点，但仍然应该进入影响面分析，因为很多生产事故来自配置和资源变更。

## 调用链反向追踪

如果某个底层方法被修改，需要沿调用图反向查找调用方，直到业务入口、模块边界或服务边界。

反向追踪可以回答：

* 哪些 Controller 或 API 可能受影响。
* 哪些定时任务或消息消费者会触发变更代码。
* 哪些上层服务依赖目标方法。
* 哪些公共路径会被波及。

追踪不能无限扩散。实际系统中需要设置边界：

* 最大调用深度。
* 业务入口停止。
* 模块边界停止。
* 只保留运行时出现过的路径。
* 只保留核心业务或高频路径。

边界的作用不是掩盖风险，而是让报告可读。完整图谱可以很大，但 Review 报告需要突出最相关路径。

## 依赖传播和资源影响

调用链不是唯一影响路径。一次变更可能通过资源传播：

* 修改数据库字段影响多个查询和报表。
* 修改消息格式影响消费者。
* 修改缓存 key 影响读写双方。
* 修改配置项影响不同环境行为。
* 修改公共 DTO 影响 API client。

因此，影响面分析应该把资源依赖纳入图谱。否则系统会低估跨模块、跨服务、跨语言的影响。

对于微服务系统，运行时 Trace 和服务目录也很重要。代码仓库内的调用图无法完整覆盖服务间依赖，必须结合 API、RPC、消息和 Trace 数据。

## 关联测试与覆盖率

影响面分析的最终目的之一是验证。系统应该尽量把受影响实体映射到相关测试。

测试关联可以来自：

* Coverage：测试执行时覆盖了哪些代码。
* 命名约定：测试类与业务类的对应关系。
* 目录结构：同模块测试。
* 历史共同变更：哪些测试经常随代码一起改。
* 失败历史：哪些测试曾因相关模块变更失败。
* 调用图：测试入口是否调用目标代码。

Coverage 是很强的信号，但不能单独代表质量。覆盖目标代码的测试不一定有有效断言，未覆盖代码也可能通过更高层集成测试间接验证。因此测试推荐应该解释依据，而不是只给出结论。

## 风险分级

不是所有影响都同等重要。影响面报告应该给出风险分级，帮助 Reviewer 和 CI 决定验证强度。

常见风险信号包括：

* 影响核心业务入口。
* 影响高频运行路径。
* 影响低覆盖代码。
* 修改高复杂度或高变更频率文件。
* 跨模块或跨服务传播。
* 涉及权限、支付、数据一致性、安全输入。
* 影响多个团队 owner。

风险分级不需要一开始就非常精确。即使只是把影响分成高、中、低，也能显著提高 Review 效率。

## 影响面报告设计

一份好的影响面报告应该包含：

* 变更实体：改了哪些方法、类、配置或资源。
* 影响路径：从变更点到业务入口的关键路径。
* 受影响模块和服务。
* 相关测试和覆盖情况。
* 运行时证据：是否处于 Trace 高频路径或性能热点。
* 风险等级。
* 不确定性说明：哪些关系是推断，哪些关系已被运行时确认。

报告不应该只是一个大图。更实用的结构通常是“摘要 + 风险列表 + 关键路径 + 测试建议 + 证据链接”。

## 在 PR 流程中的位置

影响面分析最适合出现在 PR 阶段。开发者提交变更后，系统自动生成报告：

* 这次变更影响哪些入口。
* 建议运行哪些测试。
* 哪些路径没有覆盖。
* 是否违反架构约束。
* 是否需要特定 owner Review。

这样，影响面分析就从事后排查工具变成合并前的验证工具。

## AI 时代的影响面验证

AI 生成代码后，影响面分析更重要。Agent 可能能快速生成补丁，但它不一定知道完整影响范围。

AI 修改后的验证报告应该至少回答：

* AI 改了哪些实体。
* 这些实体被谁调用。
* 哪些测试应该运行。
* 是否改到任务范围之外。
* 是否触碰核心路径或架构边界。

这份报告也可以反向约束 AI：在修改前先运行影响面查询，要求 Agent 只在影响面相关文件中操作，并解释为什么需要修改额外文件。

## 小结

变更影响分析把 Diff、调用图、依赖图、测试覆盖、运行时证据和历史变更连接起来。它让团队从“看改了什么”升级为“知道影响谁、怎么验证”。

在 AI 时代，影响面分析会成为 AI Review 的核心证据层。下一章讨论另一个高价值场景：架构理解与遗留系统改造。

## 延伸阅读与参考资料

* [Azure Pipelines Test Impact Analysis](https://learn.microsoft.com/en-us/azure/devops/pipelines/test/test-impact-analysis?view=azure-devops)：变更影响测试选择的官方资料。
* [Launchable Predictive Test Selection](https://help.launchableinc.com/features/predictive-test-selection/)：预测式测试选择产品资料。
* [Codecov Pull Request Comments](https://docs.codecov.com/docs/pull-request-comments)：PR 中展示覆盖率变化的参考。
* [CodeScene Change Coupling](https://codescene.io/docs/guides/technical/change-coupling.html)：变更耦合分析的工程实践参考。