用 AI 做接口验收：从 Swagger 到批量报告，10 步标准化流程
导读：开发提测后，接口验收往往卡在「拼参数、写用例、跑请求、写报告」四件事上。本文介绍一套基于 Cursor Agent 的 API 层验收方案——自动拉取 Swagger 元数据、多维生成用例、批量执行断言、输出 HTML 报告并邮件通知，在保留人工审核闸门的前提下，将单接口验收从数小时压缩到约 30 分钟。
01｜它解决什么问题
传统接口测试有三个典型痛点：
- 启动成本高：查文档、拼 curl、记 Token，重复劳动多
- 用例覆盖浅：正向路径测完就交差，边界与异常场景常被跳过
- 变更难同步：代码改了，测试用例往往滞后，容易漏测
AI 接口验收测试的定位，是在提测阶段提供一条 API 层快速验收通道：输入项目名与接口路径，Agent 按标准十步流程自动完成元数据拉取、用例生成、批量执行与报告输出，每一步均需人工确认后再继续，避免「全自动抢跑」带来的质量风险。
触发方式：Skill 附带项目名与接口路径即可。
02｜整体架构：三输入、十步引擎、四类产出
┌─────────────────────────────────────────────────────────┐
│ 输 入 │
│ ① 变更扫描（git diff 识别受影响接口） │
│ ② 指定接口（项目 + 路径） │
│ ③ 需求用例库 / 接口知识库 / 公共参数配置 │
└────────────────────────┬────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ 十步引擎 │
│ 选模式 → 拉元数据 → 依赖配置 → 参数设计 → 知识库规则 │
│ → 冒烟验证 → 生成用例 → 用例落盘 → 批量执行+报告 │
│ → 缺陷联动 → 状态回写 │
└────────────────────────┬────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ 产 出 │
│ Markdown 用例文件 │ HTML 测试报告 │ 邮件/企微通知 │ Bug │
└─────────────────────────────────────────────────────────┘
核心模块职责：
| 模块 | 职责 |
|---|---|
rules.md |
十步流程规则的唯一来源 |
SKILL.md |
命令索引与脚本入口 |
scripts/ |
扫描、Swagger 拉取、执行、批量、报告、缺陷创建 |
cases/{project}/ |
可复用的 Markdown 用例，支持版本化管理 |
refs/requirement-cases/ |
需求/文本用例关联 |
refs/api-knowledge/ |
接口通用校验规则（响应结构、鉴权、幂等等） |
tools/ |
邮件与企业微信推送 |
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｜两种入口模式
模式一：变更扫描
适用场景：版本合并后、迭代回归、不确定哪些接口受影响。
工作原理：
- 执行
git fetch，对比两个分支的 diff - 解析
.java/.xml变更，提取 Controller 层 HTTP mapping - 产出接口清单 JSON，供用户选择待测接口
- 进入统一的 Step 1–10 流程
模式二：指定接口
适用场景：单接口验收、联调验证、缺陷复测。
工作原理：
- 输入「项目名 + 接口路径」
- 自动拉取 Swagger 元数据，解析请求/响应结构
- 生成冒烟请求模板，进入 Step 1 审核
| 模式 | 适用场景 | 典型用法 |
|---|---|---|
| 变更扫描 | 合并后批量识别受影响接口 | --mode 1 --project user-service |
| 指定接口 | 单接口快速验收 | --mode 2 --project order-service --path /order/query/status |
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 接口验收 |
|---|---|---|---|
| 触发成本 | 高：查文档、拼请求、记参数 | 中：平台录入，维护成本高 | 低：@ 技能 + 项目/路径 |
| 用例来源 | 测试人员经验 + 需求文档 | 平台手工录入/导入 | 需求用例 + Swagger + 知识库 三源合并 |
| 变更感知 | 依赖人工读 MR/代码 | 需人工同步用例 | git diff 自动扫描 |
| 执行方式 | 逐条手工请求 | 平台调度/CI | 批量执行 + 规则引擎 自动断言 |
| 断言深度 | 看 code/message，易漏 data | 需预先配置脚本 | 可 per 接口配置 data 断言 |
| 异常/边界 | 常因时间不足被跳过 | 取决于用例库完整度 | 强制生成 缺参、边界模板 |
| 报告 | Excel/截图分散 | 平台内置报告 | HTML + 邮件 + JSON 结果 |
| 缺陷闭环 | 手工建 Bug，描述不一 | 平台可关联用例 | 模板化创建 + 请求响应自动带入 |
| 复用/回归 | 低，人员流动易丢失 | 中，平台有历史 | 高：Markdown 用例版本化 |
| 典型耗时（单接口） | 2–4 小时 | 0.5–1 小时（已有用例） | 约 15–30 分钟 |
效率与覆盖的定性对比：
高覆盖 ▲
│ ★ AI 接口验收
│ ○ 平台接口测试
│ △ 手工测试
低覆盖 └──────────────────────► 高效率
量化参考（单接口验收）：
| 指标 | 手工（估） | AI 接口验收 |
|---|---|---|
| 用例条数 | 2–3 条常见 | 6 条（含需求场景 + 边界） |
| 执行 + 报告 | 1–2 小时 | 约 5 分钟（含邮件） |
| 需求追溯 | 弱 | 每条标注来源编号 |
| 变更场景覆盖 | 易遗漏 | 需求用例专项覆盖 |
09｜推荐落地路径
Phase 1 Phase 2 Phase 3 Phase 4
单接口验收 → 需求用例库接入 → 变更扫描 + CI 集成 → 知识库 + 缺陷全自动
（模式二） （refs 目录） （模式一） （闭环自动化）
| 阶段 | 动作 | 预期效果 |
|---|---|---|
| Phase 1 | 提测接口使用模式二验收 | 当天出报告 + 邮件 |
| Phase 2 | 需求用例写入 refs/requirement-cases/
|
业务场景不遗漏 |
| Phase 3 | MR 合并触发模式一扫描 | 变更接口零遗漏 |
| Phase 4 | 知识库 + 缺陷 MCP 默认开启 | 闭环自动化 |
10｜结语
AI 接口验收测试 在保留「人工 Step 审核」质量闸门的前提下，将 Swagger 元数据、需求用例、参数规则与批量断言串联为 十步标准流程。
相比手工测试，效率提升一个数量级；相比测试平台，变更同步与用例生成成本更低。它不能替代复杂链路联调或 UI 层测试，但在 提测验收、变更回归、单接口快速冒烟 这三个场景，已经具备可落地的工程价值。
* 本文基于 Api 验收测试 技能实践整理，适用于 Cursor /Hermes+ Agent 环境下的 API 层验收测试。
有兴趣一起建设 Ai 下的测试；