用 AI 做接口验收：从 Swagger 到批量报告，10 步标准化流程

导读：开发提测后，接口验收往往卡在「拼参数、写用例、跑请求、写报告」四件事上。本文介绍一套基于 Cursor Agent 的 API 层验收方案——自动拉取 Swagger 元数据、多维生成用例、批量执行断言、输出 HTML 报告并邮件通知，在保留人工审核闸门的前提下，将单接口验收从数小时压缩到约 30 分钟。

01｜它解决什么问题

传统接口测试有三个典型痛点：

1. 启动成本高：查文档、拼 curl、记 Token，重复劳动多
2. 用例覆盖浅：正向路径测完就交差，边界与异常场景常被跳过
3. 变更难同步：代码改了，测试用例往往滞后，容易漏测

AI 接口验收测试的定位，是在提测阶段提供一条 API 层快速验收通道：输入项目名与接口路径，Agent 按标准十步流程自动完成元数据拉取、用例生成、批量执行与报告输出，每一步均需人工确认后再继续，避免「全自动抢跑」带来的质量风险。

触发方式：Skill 附带项目名与接口路径即可。

02｜整体架构：三输入、十步引擎、四类产出

┌─────────────────────────────────────────────────────────┐
│                        输 入                             │
│  ① 变更扫描（git diff 识别受影响接口）                    │
│  ② 指定接口（项目 + 路径）                               │
│  ③ 需求用例库 / 接口知识库 / 公共参数配置                 │
└────────────────────────┬────────────────────────────────┘
                         ▼
┌─────────────────────────────────────────────────────────┐
│              十步引擎                │
│  选模式 → 拉元数据 → 依赖配置 → 参数设计 → 知识库规则    │
│  → 冒烟验证 → 生成用例 → 用例落盘 → 批量执行+报告       │
│  → 缺陷联动 → 状态回写                                   │
└────────────────────────┬────────────────────────────────┘
                         ▼
┌─────────────────────────────────────────────────────────┐
│                        产 出                             │
│  Markdown 用例文件 │ HTML 测试报告 │ 邮件/企微通知 │ Bug  │
└─────────────────────────────────────────────────────────┘

核心模块职责：

03｜十步流程与审核闸门

整个流程分为十个标准步骤，每步结束展示产物，用户确认「StepN 审核通过」后才进入下一步——这是 Agent 强制执行的质量闸门，防止跳步或抢跑。

Step 0  选择模式（变更扫描 / 指定接口）
   ↓
Step 1  确定测试对象（Swagger 元数据 + 冒烟请求）
   ↓
Step 2  配置测试依赖（Token、环境变量等）
   ↓
Step 3  设计请求参数
   ↓
Step 4  纳入知识库规则（响应结构、鉴权、幂等）
   ↓
Step 5  冒烟验证（确认接口可达、响应格式正确）
   ↓
Step 6  生成测试用例（三源合并）
   ↓
Step 7  用例落盘（写入 cases/ 目录）
   ↓
Step 8  批量执行 + HTML 报告 + 邮件通知
   ↓
Step 9  缺陷联动（可选：创建 Bug / 企微通知）
   ↓
Step 10 状态回写（更新用例执行结果）

其中 Step 5（冒烟验证） 与 Step 8（批量执行） 是两条关键质量节点：前者确认接口可用，后者产出可交付的测试报告。

04｜两种入口模式

模式一：变更扫描

适用场景：版本合并后、迭代回归、不确定哪些接口受影响。

工作原理：

1. 执行 git fetch，对比两个分支的 diff
2. 解析 .java / .xml 变更，提取 Controller 层 HTTP mapping
3. 产出接口清单 JSON，供用户选择待测接口
4. 进入统一的 Step 1–10 流程

模式二：指定接口

适用场景：单接口验收、联调验证、缺陷复测。

工作原理：

1. 输入「项目名 + 接口路径」
2. 自动拉取 Swagger 元数据，解析请求/响应结构
3. 生成冒烟请求模板，进入 Step 1 审核

05｜用例生成：三源合并，不遗漏边界

Step 6 的用例并非凭空生成，而是从三个维度合并去重：

维度一：关联需求用例

• 来源：refs/requirement-cases/
• 将业务场景映射为具体请求参数与断言

维度二：API 参数级用例

• 正常参数（冒烟已验证）
• 必填字段缺失
• 边界值（如 ID=0、空字符串、超长输入等）

维度三：知识库规则

• 来源：refs/api-knowledge/
• 统一响应结构校验、鉴权规则、幂等约束等

三源合并后，输出为标准 Markdown 用例文件，每条用例标注来源，便于需求追溯。

06｜批量执行与断言规则

Step 8 触发批量执行，对每条用例自动校验并汇总结果：

用户触发批量执行
    │
    ├─→ 循环执行每条用例（api_execute.py）
    │       ├─ R1：响应 JSON 可解析
    │       ├─ R2：正常流 code ∈ {0, 200} 且 success = true
    │       ├─ R3：data 字段 exists / equals 断言
    │       ├─ R_boundary：边界场景 HTTP 非 5xx
    │       └─ R_expect_fail：异常场景仍返回成功 → 标记潜在缺陷
    │
    ├─→ 生成 HTML 测试报告
    ├─→ 自动发送邮件通知（必执行）
    └─→ Step 10 回写用例执行状态

断言规则通过 validation-rules.json 配置，支持按接口定制 data 字段断言，避免「只看 code，漏验 data」的常见盲区。

07｜典型应用场景

场景一：单接口快速验收

背景：某查询接口逻辑变更，需在提测当天完成回归。

做法：模式二指定接口 → 关联需求用例 5 条 + 边界用例 1 条 → 批量执行。

结果：6 条用例全部通过，覆盖变更涉及的核心业务规则；产出 HTML 报告与邮件通知，用例文件可纳入版本库复用。

场景二：边界缺陷发现

背景：GET 接口带 Query 参数，需验证缺参与非法值处理。

做法：生成正向 / 缺参 / 边界负数三类用例，批量执行。

结果：2 条通过、1 条失败——非法参数返回 HTTP 500，暴露服务端边界未兜底，可直接进入 Step 9 创建缺陷。

场景三：版本合并后变更扫描

背景：开发合并主干后，需识别哪些接口可能受影响。

做法：模式一对目标工程执行 git diff 扫描，解析 Controller 变更。

结果：产出变更接口清单 JSON，测试人员按清单选择待测接口，降低「漏测变更接口」风险。

场景四：一句话触发

Agent 按 rules.md 逐步执行，无需手工拼 curl；每步审核保证关键节点人工确认。

08｜三种测试方式对比

效率与覆盖的定性对比：

高覆盖 ▲
       │          ★ AI 接口验收
       │    ○ 平台接口测试
       │  △ 手工测试
低覆盖 └──────────────────────► 高效率

量化参考（单接口验收）：

09｜推荐落地路径

Phase 1          Phase 2              Phase 3                Phase 4
单接口验收   →   需求用例库接入   →   变更扫描 + CI 集成   →   知识库 + 缺陷全自动
（模式二）        （refs 目录）         （模式一）              （闭环自动化）

10｜结语

AI 接口验收测试 在保留「人工 Step 审核」质量闸门的前提下，将 Swagger 元数据、需求用例、参数规则与批量断言串联为 十步标准流程。

相比手工测试，效率提升一个数量级；相比测试平台，变更同步与用例生成成本更低。它不能替代复杂链路联调或 UI 层测试，但在 提测验收、变更回归、单接口快速冒烟 这三个场景，已经具备可落地的工程价值。

* 本文基于 Api 验收测试 技能实践整理，适用于 Cursor /Hermes+ Agent 环境下的 API 层验收测试。
有兴趣一起建设 Ai 下的测试；

来源公众号：https://mp.weixin.qq.com/s/ZMSSOUoyd9BPJIRzCNlIEQ