接口测试专项
核心原则
接口 Bug 大多不在状态码，而在数据结构不一致、字段类型错配、空值处理与并发副作用。
200 只能证明"通路是通的"，证明不了"数据是对的"。
1. 先定位接口类型（决定重心）
| 接口类型 | 典型代表 | 测试重点 | 协议特点 |
|---|---|---|---|
| RESTful | CRUD API、微服务接口 | 状态码、HTTP方法语义、RESTful规范符合度 | 无状态、资源导向、Cache |
| GraphQL | 聚合查询、数据中台 | 查询复杂度、N+1问题、权限细粒度 | 单一端点、按需查询 |
| gRPC | 内部服务通信、高吞吐场景 | 消息格式、流处理、超时重试 | Protobuf、双向流、高性能 |
| WebSocket | 实时推送、消息通知 | 连接管理、心跳、消息顺序 | 长连接、全双工、有状态 |
| SOAP | 企业级系统、金融/医疗 | WSDL契约验证、XML报文结构、WS-Security | XML、强契约、RPC风格 |
| Webhook | 支付回调、事件通知 | 验签、幂等性、超时重试、回调顺序 | HTTP回调、被动触发、需主动Mock |
2. 深度要求
| 复杂度 | 用例数要求 | 说明 |
|---|---|---|
| 简单接口 | 接口数×5 | 单一功能接口 |
| 中等接口 | 接口数×10 | 多参数接口 |
| 复杂接口 | 接口数×15 | 多依赖/多状态接口 |
必须覆盖的6个维度：
| 维度 | 占比 | 说明 |
|---|---|---|
| 功能测试 | 40% | 正向/反向/边界/参数 |
| 安全测试 | 20% | 认证/授权/注入 |
| 异常测试 | 15% | 超时/重试/降级 |
| 性能测试 | 10% | 响应时间/并发 |
| 契约测试 | 10% | 接口契约验证 |
| 兼容性测试 | 5% | 版本兼容 |
> 偏差声明：技能集通用六维标准为 功能/异常/边界/并发/安全/性能（见 docs/standards.md，装整套技能集时可得）。本技能针对 API 测试专项调整：将「边界」归入功能测试维（边界值验证是参数测试的子项）、将「并发」归入性能测试维（并发能力是 API 性能指标），新增「契约测试」与「兼容性测试」两维——这两者是接口测试的核心风险面（契约破裂与版本迁移），在通用功能测试中无独立维度。若与通用六维口径冲突，以本技能的六维为准，并在测试报告中说明。
>
> 小规模降级：上表占比适用于接口数 ≥ 5 的项目。接口数 < 5 时配额在数学上无法成立（20% 安全测试不足 1 条），此时改为「每维至少 1 条 + 覆盖率标注实际口径」，不要为凑比例编造用例。占比取整规则（先保 P0 所属维 → 向下取整 → 偏差 ≤1 条）见 references/core-flows.md。
3. 加载时机
需要时才读，不要一上来全读：
| 什么时候读 | 读哪个 |
|---|---|
| 展开某一维的测试范围，或交付前逐项自检（32 项） | references/core-flows.md（六维详图 + Mock 策略 + 检查清单） |
| 生成具体测试用例；被测接口是 GraphQL/gRPC/WebSocket/SOAP/Webhook | references/test-cases.md（39 条用例 + OWASP API Top 10 对照 + 协议专项） |
| 选工具，或要展开某工具能力边界 | references/tooling.md（默认选型 + 能力矩阵 + 性能工具） |
| 用户描述的情况命中特定风险场景 | references/scenarios.md（5 个场景，校正测试重心） |
| 写用例表 | assets/case-template.md（9 列模板 + 填写要求） |
4. 工具默认选型
没别的约束就用这套：
| 场景 | 默认工具 | 理由 |
|---|---|---|
| 日常调试与文档 | Postman / Apifox | 上手最快，协作与文档一体 |
| 自动化执行 | pytest + requests（Python）/ REST Assured（Java） | 生态成熟、易接 CI |
| 契约测试 | Pact（消费者驱动）/ Schemathesis（OpenAPI 校验） | 前者管协作方破坏性变更，后者管实现偏离契约 |
| 第三方与异常 Mock | WireMock | 延迟/超时/脏数据开箱即用 |
| 性能 | k6（CI 友好）；需 GUI 分布式再选 JMeter | 压测按需引入，非默认动作 |
> 明确"单工具全栈"诉求用 Karate。gRPC 用 grpcurl 调试（WireMock 不覆盖流式语义）。
> 完整能力矩阵与选型避坑见 references/tooling.md。
5. 输出格式
9 列标准表格：
| 用例编号 | 测试类型 | 功能模块 | 测试标题 | 用例级别 | 预置条件 | 测试步骤 | 预期结果 | 风险等级 |
|---|---|---|---|---|---|---|---|---|
| TC_API_LOGIN_001 | 功能测试 | 登录接口 | 正确凭证登录成功 | P0 | 接口文档已提供，账号已就绪 | 发送POST /api/login，参数{user,pass} | 返回200，响应含token且有效 | 高 |
| TC_API_LOGIN_002 | 安全测试 | 登录接口 | Token伪造被拒绝 | P0 | 合法Token已知 | 修改Token签名后请求受保护接口 | 返回401，拒绝访问 | 高 |
| TC_API_LOGIN_003 | 异常测试 | 登录接口 | 超时重试幂等性 | P1 | 模拟网关超时 | 请求超时后自动重试2次 | 重试成功且无重复副作用 | 中 |
> 上面 3 行只用于展示每列的写法，不是完整用例集。P0≤20% 等占比约束作用于最终交付的整份用例集，
> 不要照抄这 3 行的级别分布。完整模板见 assets/case-template.md。
方案产出顺序：接口类型定位 → 六维用例矩阵 → Mock 策略 → 自动化脚本设计 → 安全清单 → 风险提示。
6. 交付前自检
- [ ] 9 列齐全，无列错位、无单元格含
|（会破坏表格与 CSV） - [ ] 用例编号唯一且符合
TC_{模块}_{功能}_{序号} - [ ] P0-P3 占比符合；接口数 <5 时已注明实际分布口径
- [ ] 覆盖率已标注口径，无"全覆盖/100%"绝对化表述
- [ ] 未覆盖接口已写明"未覆盖 + 原因"
- [ ] 六维检查清单已逐项过（见
references/core-flows.md第 8 节）
机器校验：
python scripts/validate_testcase_table.py <用例文件>
覆盖列数、编号唯一性、级别/风险取值、占比、覆盖率措辞。报错先修再交付。
