ScenarIQ: 用 AST 静态分析自动审计 API 测试覆盖率

ScenarIQ 工程团队

我们合作过的每个 QA 团队，最终都会从经理、审计员或焦虑的发布负责人那里听到同一个问题：

"我们哪些 API 端点实际上有测试？"

而我们见过的每个团队回答这个问题的方式都一样：一个人在一个窗口打开后端仓库，在另一个窗口打开自动化仓库，然后开始制作电子表格。两周后电子表格诞生了。两个冲刺周期后，它已经过时了。

我们构建 ScenarIQ 是因为厌倦了手动进行这种审计。这篇文章是它工作原理的详细版本：五阶段管道、解析器设计决策、迫使我们构建引文验证器的 AI 幻觉，以及将我们自身的覆盖率召回率从 87.2% 提升到 100% 的自我审计。

这种痛点是结构性的，不是组织性的。

大多数中型团队将 API 测试与后端代码分离存储。后端仓库包含 Spring Boot 控制器和业务逻辑，而自动化仓库包含 TestNG + REST Assured 测试套件。

这造成了一个根本性的可见性问题：

我们的自动化代码实际覆盖了哪些后端 API？

手动回答这个问题需要多个步骤。首先，需要有人理解后端代码，识别出所有的控制器、路由、HTTP 方法、参数和端点。然后需要检查自动化仓库，确定哪些测试和 HTTP 调用对应于这些端点。

两个仓库之间的映射关系通常无处存在。它存在于电子表格、文档中，或者仅仅是编写测试的工程师的脑海中。

这产生了几个反复出现的问题：

手动跨仓库审计

需要有人检查两个仓库，识别可用的端点，在自动化代码中找到对应的 API 调用，并手动创建覆盖率矩阵。这个过程缓慢、容易出错，且随着代码库的变化难以维护。

过时覆盖率信息

添加了端点、API 发生变化、或删除了自动化测试，但覆盖率文档没有更新。随着时间推移，覆盖率矩阵变得过时，不再能作为系统的准确代表。

部落知识

团队通常依赖个别工程师知道哪些测试覆盖了哪些 API。

"上个季度编写的测试覆盖了订单 API。"

但当工程师换岗或离职时会发生什么？这些知识也随之消失了。

端点覆盖率不等于场景覆盖率

找到一个端点的测试并不一定意味着该端点得到了充分的测试。例如，一个端点可能只有正常路径测试，而完全缺少：

*   验证失败场景
*   认证和授权场景
*   404 未找到场景
*   冲突场景
*   边界条件
*   负向用例
*   业务规则验证

因此，知道一个端点被覆盖了只是第一步。团队还需要了解测试实际验证了什么。

缺失的场景难以识别

即使在将 API 映射到测试之后，团队仍需确定哪些重要场景仍然缺失。这需要同时理解后端实现和现有自动化代码，使得这个过程手动执行更加困难。

回答这些问题所需的信息已经存在于源代码中。

后端仓库告诉我们：

自动化仓库告诉我们：

测试套件实际调用了什么？

挑战在于连接这两个来源，然后更进一层：

什么是被覆盖的，什么是实际被验证的，还有哪些重要场景仍然缺失？

这就是我们想要用 ScenarIQ 解决的问题。

现有解决方案及其局限

在写一行代码之前，我们仔细研究了现有的测试和覆盖率工具现状。

行覆盖率工具衡量的是不同的维度

JaCoCo（Java）和 Istanbul（JavaScript）等工具在测量测试执行了哪些行、分支或指令方面非常有用。

但它们不能直接回答我们试图解决的 API 级别问题。

当 API 测试位于单独的自动化仓库中，并通过 HTTP 与已部署的后端通信时，传统的代码覆盖率不能直接告诉我们：

在这个服务暴露的 N 个端点中，自动化套件实际调用了多少？

例如，后端可能有很高的行覆盖率，而重要的 API 可能完全没有被测试。

反之，自动化仓库可能有出色的代码覆盖率，而团队仍然对哪些后端 API 实际被验证缺乏可见性。

ScenarIQ 专注于这个缺失的层：

跨后端和自动化仓库的 API 和场景覆盖率。

API 平台不一定理解你的自动化代码

API 管理、可观测性和基于规范的工具为 API、流量、契约和 OpenAPI 定义提供了有价值的可见性。

但它们不一定理解自动化仓库中存在什么，或者哪些自动化测试调用了这些 API。

ScenarIQ 回答一个问题——哪些端点被测试覆盖了？——并用证据回答。每个判断都附带一个可点击的文件:行号引用，你可以自己验证。没有置信度分数，没有"可能已覆盖"。已覆盖意味着：这里是测试文件，这里是行号，这里是匹配此端点的解析后的 URL。

从中产生三个输出：

已覆盖的端点——以及覆盖它们的确切测试

未覆盖的端点——可操作的差距列表

孤儿测试——调用后端中已不存在的端点的测试（死代码，仍在消耗 CI 时间和维护成本）

关键的是：零执行。ScenarIQ 从不运行你的测试，不需要构建，不触碰你的 CI。它只读取源代码。

架构概览

ScenarIQ 是一个 Spring Boot 3.4 后端配合 React 19 仪表盘。通过 JGit 克隆仓库；使用 JavaParser 解析 Java 源代码。分析是一个五阶段管道：

AST 端点清单。将后端的控制器解析为完整的端点列表。JavaParser 处理 Spring Boot（@RestController、@RequestMapping 组合、方法级映射、路径变量）；路由解析器处理 Laravel。

数据流调用解析。解析自动化仓库并解析每个 HTTP 调用的方法和路径——通过变量、常量、静态初始化器、System.getProperty 默认值、辅助/包装方法以及类继承。

Service binding. 通过 base-URL 关键字（来自 URL 模板或变量名）将测试调用匹配到正确的后端服务。一个自动化仓库通常测试多个服务；调用必须落到正确的端点清单上。

Service binding. 通过 base-URL 关键字（来自 URL 模板或变量名）将测试调用匹配到正确的后端服务。一个自动化仓库通常测试多个服务；调用必须落到正确的端点清单上。

Strict matching. 端点到调用的确定性匹配。每个判定结果都带有 file:line 的证据。

Strict matching. 端点到调用的确定性匹配。每个判定结果都带有 file:line 的证据。

Optional AI layer. 评判场景质量——是否测试了正确的用例？——但绝不决定覆盖率。

阶段 1–4 完全确定性运行。同一次扫描跑两遍，得到两遍相同的结果。这个特性后来被证明比我们最初预期的更重要——在 AI 部分会有更多讨论。

阶段边界也是可扩展性的接缝。阶段 3 和 4 操作的是标准化清单——一端是端点模板，另一端是解析后的调用——并不关心是哪个解析器产生的。添加一个框架意味着添加一个解析器（阶段 1）或一个解析器配置文件（阶段 2），不需要触碰匹配逻辑。这就是 Laravel 支持如何与 Spring Boot 并肩落地而不需要分叉流水线，也是未来框架支持的形态。

解析器与解析器设计

阶段 1 是简单的那一半。Spring 注解是声明式的；将类级别的 @RequestMapping("/api/v1/orders") 与方法级别的 @PostMapping("/{id}/approve") 合成为 POST /api/v1/orders/{id}/approve 是机械性的 AST 工作。

阶段 2 是工程所在之处，因为真实的自动化代码从来不会把 URL 写为字面量。下面是一个有代表性的（简化后的）真实企业自动化代码示例：

// Simplified — representative of real enterprise automation code
public class ApiTestBase {
    protected static final String BASE_URI;

static {
        BASE_URI = System.getProperty("service.base.uri",
                       "https://staging.internal/order-service");
    }

protected Response executePost(String path, Object body) {
        return RestAssured.given()
                .baseUri(BASE_URI)
                .body(body)
                .post(path);
    }
}

public class ApproveOrderTest extends ApiTestBase {
    @Test
    public void approveOrder_Test() {
        String endpoint = "/orders/" + orderId + "/approve";
        Response response = executePost(endpoint, payload);
        // ...
    }
}

这里实际的 HTTP 调用是 POST {BASE_URI}/orders/{id}/approve——但要看到这一点，解析器必须：

Follow static initializers to find what BASE_URI is

追踪静态初始化器，找到 BASE_URI 是什么

Understand System.getProperty defaults — the second argument is the value that matters for path analysis

理解 System.getProperty 的默认值——第二个参数才是路径分析中重要的值

Recognize wrapper sinks — executePost() isn't a REST Assured call itself; it's a method whose parameter flows into one. We call these wrapper sinks: the method is a "sink" for a path argument

识别包装器 sink——executePost() 本身不是 REST Assured 调用；它是一个方法，其参数流入一个调用。我们称这些为包装器 sink：方法是路径参数的"汇"（sink）

Walk inheritance — executePost() is defined on the superclass, not the test class

遍历继承——executePost() 定义在父类上，而非测试类

Track parameters transitively — the path travels through a local variable (endpoint), into a method parameter (path), into the .post() call

追踪参数的传递链——路径经过一个局部变量（endpoint），传入方法参数（path），最后到达 .post() 调用

Each of those is a distinct resolver capability, and each one we skipped initially cost us real false negatives (see the self-audit section — it cost us exactly 6 endpoints, 12.8% of recall).

每一项都是一个独立的解析器能力，而我们最初跳过的每一项都让我们付出了真实的漏报代价（见自审部分——它让我们损失了恰好 6 个端点，占召回率的 12.8%）。

解析器将这些能力构建为在 AST 上的可组合遍历：用于字符串拼接的常量折叠、用于字段解析的每个类层次结构的符号表，以及 paramRefs 机制——允许一个值在到达 HTTP sink 之前流经任意数量的中间变量和方法参数。

覆盖率对账：严格匹配

一旦我们有了端点清单和解析后的调用清单，匹配听起来就很 trivial 了。事实上并不尽然——后端的 /orders/{id}/approve 必须匹配测试端的 /orders/8842/approve、/orders/{orderId}/approve 和 /orders/" + id + "/approve。

我们在早期做了一个决定从未后悔：匹配是严格且确定性的。只有当 HTTP 方法匹配且路径结构匹配（字面量段相等，参数段对齐）时，调用才匹配端点。没有模糊评分，没有"78% 相似"。

其后果：在我们审计的参考仓库上实现了 100% 的覆盖率精度——当 ScenarIQ 说一个端点被覆盖时，它确实被覆盖了。代价是任何我们无法解析的内容都变成一个显式的未解析调用，在报告中呈现，而不是一个猜测。我们认为这是一个以其整体价值主张——可信度——为中心的工具的正确权衡。一份偶尔乐观地出错的覆盖率报告比没有报告更糟糕。

孤立检测从未解析对账中免费获得：一个完全解析的测试调用匹配不到清单中的任何端点，意味着该测试针对的是一个已不存在的端点。那些测试仍然消耗 CI 时间并误导阅读套件的任何人——而且从自动化仓库内部来看它们完全不可见，因为在那边没有任何东西看起来有问题。

Beyond binary endpoint coverage, the engine derives scenario coverage: for each endpoint, the set of cases that should exist (success, validation errors, auth failures, not-found) versus the cases the matched tests actually exercise. An endpoint with one happy-path test and an endpoint with a full negative-case suite are both "covered" in the binary sense; scenario coverage is what separates them. On our reference repo pair the deterministic scenario number is 65.8% (258/392) — more on the second, AI-expanded scenario number below.

超越二元的端点覆盖率，引擎还推导出场景覆盖率：对于每个端点，应存在的用例集（成功、验证错误、认证失败、未找到）与匹配的测试实际覆盖的用例之间的对比。有一个快乐路径测试的端点和有完整负向用例套件的端点在二元意义上都是"已覆盖"的；场景覆盖率才能区分它们。在我们的参考仓库对上，确定性场景数字是 65.8%（258/392）——更多关于第二个 AI 扩展场景数字的内容见下文。

The AI insight engine

AI 洞察引擎

Strict matching answers whether an endpoint is covered. It can't answer how well. An endpoint with one happy-path test and an endpoint with tests for validation errors, auth failures, and boundary cases both show up as "covered."

严格匹配回答的是一个端点是否被覆盖。它无法回答覆盖得有多好。只有一个快乐路径测试的端点和有验证错误、认证失败及边界用例测试的端点都显示为"已覆盖"。

That quality judgment is genuinely fuzzy, which makes it a good fit for an LLM — with one hard rule that is the core of our positioning:

这种质量判断确实是模糊的，这使其非常适合 LLM——同时有一条硬规则是我们定位的核心：

Deterministic static analysis decides whether an endpoint is covered. AI only judges how well it's covered. Coverage verdicts are never hallucinated because AI never makes them.

确定性静态分析决定一个端点是否被覆盖。AI 只评判其覆盖质量。由于 AI 从不作覆盖率判定，因此覆盖判定永远不会被 hallucinate。

The AI layer (Precision + AI scan mode) receives the deterministic engine's output — matched endpoints with their citing tests — plus minimal grounded code snippets, and reports on scenario quality: missing negative cases, absent status-code coverage, suggested additional tests. It never adds or removes an endpoint from the covered list. The division of labor is architectural, not a prompt instruction.

AI 层（Precision + AI 扫描模式）接收确定性引擎的输出——带有其引用测试的已匹配端点——加上最少的接地代码片段，并报告场景质量：缺失的负向用例、缺少的状态码覆盖、建议的额外测试。它永远不会从已覆盖列表中添加或移除一个端点。分工是架构层面的，而非 prompt 指令。

The AI also expands the scenario universe itself: cases the deterministic engine can't enumerate — edge cases and negative paths implied by what an endpoint actually does. That's why we report two scenario numbers on purpose: the deterministic 65.8%, stable and reproducible, is the one to trend over time; the AI-inclusive 48.8% (333/682), with its nearly doubled denominator, is the honest view of true coverage debt. Showing only the flattering number would be marketing; showing both is measurement.

AI 还扩展了场景宇宙本身：确定性引擎无法枚举的用例——端点实际行为所隐含的边界用例和负向路径。这就是为什么我们有意识地报告两个场景数字：确定性数字 65.8%，稳定且可复现，是用于随时间趋势追踪的那个；AI 包容数字 48.8%（333/682），其分母几乎翻倍，是对真实覆盖债务的诚实视图。只展示好看的数字是营销；两个都展示才是测量。

Two other AI-layer behaviors follow the same trust-first design. Risk scoring is blended: a deterministic rubric (coverage, quality, HTTP method) sets the baseline tier, and the LLM may adjust by at most ±1 tier — the baseline is fully reproducible, and the AI can nudge but never overturn. And prompt grounding is automatic: the AI is shown the repo's own conventions — dominant base-URL variable, sample paths, argument order — extracted from the resolved calls, so generated test suggestions match the team's actual style, including required annotations like @Owner. (Before grounding, generated suggestions missed @Owner on 5 of 5 tests for a repo that requires it on every test method.)

另外两个 AI 层行为遵循同样的信任优先设计。风险评分是混合的：确定性 rubric（覆盖率、质量、HTTP 方法）设定基线层级，LLM 最多只能调整 ±1 级——基线是完全可复现的，AI 可以推动但永远无法推翻。而 prompt 接地是自动的：AI 会看到仓库自身的约定——主导的 base-URL 变量、样本路径、参数顺序——从解析后的调用中提取，这样生成的测试建议就匹配团队的实际风格，包括必需的注解如 @Owner。（在接地之前，生成的测试建议在 5/5 的测试中都漏掉了 @Owner，而这些测试对于要求在每个测试方法上都加 @Owner 的仓库来说本不应如此。）

Citation verification: the hallucination incident

引用验证：hallucination 事件

Early in building the AI layer, a report cited EvaluateOrderValidationTest.java as evidence for a quality finding. The analysis was plausible. The file did not exist. The model had invented a filename that looked exactly like the repo's naming convention — which is precisely what makes LLM hallucination dangerous in developer tooling: the fabrications are plausible.

在构建 AI 层的早期，一份报告引用了 EvaluateOrderValidationTest.java 作为质量发现的证据。分析看起来是合理的。该文件并不存在。模型凭空创造了一个看起来完全符合仓库命名约定的文件名——这正是 LLM hallucination 在开发者工具中危险的原因：这些捏造的内容是 plausible 的。

报告中的一个虚假引用会破坏对所有真实引用的信任。因此我们采用了一个设计原则——无法验证的声明不予展示——并构建了一个四门引用验证器，每个 AI 声明在持久化之前必须通过全部验证：

第一门——逐字源码匹配。AI 引用的任何代码必须逐字存在于分析的源码中。经过释义或"从记忆中重建"的代码片段将被拒绝。

第一门——逐字源码匹配。AI 引用的任何代码必须逐字存在于分析的源码中。经过释义或"从记忆中重建"的代码片段将被拒绝。

第二门——状态/断言匹配。如果 AI 声称测试中断言了特定的状态码或条件，该断言必须与被引用测试中的实际内容相符。

第二门——状态/断言匹配。如果 AI 声称测试中断言了特定的状态码或条件，该断言必须与被引用测试中的实际内容相符。

第三门——文件存在性。每个被引用的文件必须存在于分析包中。仅这一门就能捕获最初的事件。

第三门——文件存在性。每个被引用的文件必须存在于分析包中。仅这一门就能捕获最初的事件。

第四门——自动化侧接地。建议的测试代码必须仅基于自动化仓库中的类。这捕获了一种微妙的失败：AI 建议的测试导入了自动化仓库无法访问的后端专属 DTO。

第四门——自动化侧接地。建议的测试代码必须仅基于自动化仓库中的类。这捕获了一种微妙的失败：AI 建议的测试导入了自动化仓库无法访问的后端专属 DTO。

任何未能通过任何一门的声明在存储前就会被丢弃。现在通过架构设计实现了零虚假文件引用——不是因为提示词说"请不要幻觉"，而是因为无法验证的声明根本到不了数据库。这些门由 14 个专项回归测试保护。

覆盖率分析意味着克隆客户源代码，因此安全态势必须保持平淡且保守：

GitHub 令牌静态加密（AES）

GitHub 令牌静态加密（AES）

支持服务级令牌——不同的仓库可以使用不同的 GitHub 账户进行认证，匹配企业实际划分访问权限的方式

支持服务级令牌——不同的仓库可以使用不同的 GitHub 账户进行认证，匹配企业实际划分访问权限的方式

代码为分析而克隆，结果被存储；源代码从不发送给任何第三方进行确定性扫描

代码为分析而克隆，结果被存储；源代码从不发送给任何第三方进行确定性扫描

AI 扫描仅发送场景分析所需的最小接地代码片段——从不发送整个仓库

AI 扫描仅发送场景分析所需的最小接地代码片段——从不发送整个仓库

JWT 密钥在生产环境中遇到占位符值时会快速失败，因此配置错误的部署会拒绝启动，而不是用已知密钥继续运行

JWT 密钥在生产环境中遇到占位符值时会快速失败，因此配置错误的部署会拒绝启动，而不是用已知密钥继续运行

自我审计：87.2% → 100%

2026 年 7 月，我们用一组可以完全手动验证事实的仓库对运行了 ScenarIQ：一个拥有 80 个端点的生产级企业微服务和一个真正的企业自动化仓库。然后我们审计了每个差异，修复了引擎，并重新运行。

核心 bug：这 6 个假阴性都有一个共同的模式。测试通过一个继承自基类的包装方法（executePost()）调用端点。我们的解析器看到了测试，看到了包装器调用，但丢失了线程。6 个有完美测试的端点被报告为未覆盖。

修复需要三个解析器升级协同工作：

超类链sink查找——当被调用的方法在当前类中未定义时，沿继承链向上查找，直到找到它并检查它是否是包装器sink

超类链sink查找——当被调用的方法在当前类中未定义时，沿继承链向上查找，直到找到它并检查它是否是包装器sink

包装器base-URI字段绑定——读取包装器的内部base-URI字段（包括其静态初始化器和System.getProperty默认值），使解析的路径绑定到正确的服务

包装器base-URI字段绑定——读取包装器的内部base-URI字段（包括其静态初始化器和System.getProperty默认值），使解析的路径绑定到正确的服务

可传递参数跟踪——通过局部变量和方法参数跟踪路径值直到达sink

可传递参数跟踪——通过局部变量和方法参数跟踪路径值直到达sink

召回率：87.2% → 100%。同一次审计消除了 2 个幻影端点（发现侧的解析器伪影——在其中一个案例中，我们发现自己手工构建的事实真相本身就是错误的，这本身就是关于手动审计为何会失败的教训），将未解析调用减少了 58%，并留下了 38 个回归测试来锁定引擎的准确性，这样这些 bug 就不会悄然回归。

审计后仍有 27 个调用未解析，这些是真正动态的——URL 由运行时数据组装，静态分析器无法知晓。我们在报告中明确标记它们。我们不猜测。

[SCREENSHOT: 审计前后对比视图，显示召回率、未解析调用和审计分数差值]