接口测试文档手册 · 基础篇
接口认知 + 理论基础 · 用老师讲课的方式,把概念、理论、实操入口和练习串起来
这篇怎么学
建议按 概念 → 理论 → 实操 → 练习 的顺序往下读。先建立接口测试的底层认知,再理解幂等性、状态机、兼容性这些核心理论,最后再去做工具调用和用例编写,学习效率会高很多。
第1章:接口测试到底在测什么
1.1 什么是接口
接口(API)本质上是系统之间交换数据和能力的约定。前端点一个按钮,App 发一个请求,服务端返回一个结果,这中间那条"通信通道"就是接口。
📖 一句话理解
接口 = 一份约定。约定了请求怎么传、响应怎么回、什么情况下成功、什么情况下失败。
示例
电商下单场景: 用户点击"提交订单"→ 前端调用 POST /api/orders→ 后端校验库存/价格/地址→ 返回订单号和支付状态 如果这里库存校验错了、价格字段丢了、状态码不对,前端页面可能只会提示"提交失败",但真正的问题其实发生在接口层。
1.2 为什么很多问题要在接口层发现
接口层离业务核心更近,噪音更少,更容易精准定位问题。很多线上事故,本质都不是 UI 问题,而是接口契约、数据处理或状态流转问题。
| 层级 | 能发现什么 | 优点 | 局限 |
|---|---|---|---|
| UI 测试 | 按钮、页面跳转、展示文案 | 贴近用户 | 定位慢,容易受前端影响 |
| 接口测试 | 请求参数、业务规则、返回结果、状态流转 | 定位准、执行快、覆盖深 | 看不到真实页面体验 |
| 单元测试 | 单个函数/模块逻辑 | 粒度最细 | 跨系统流程覆盖不足 |
测试价值
做接口测试,不只是为了验证"接口能通",更是为了验证业务规则是否真的被正确执行。
1.3 接口测试不是"调通就行"
很多初学者会把接口测试理解成:"拿 Postman 发一下,看到 200 就算通过。" 这是最典型的误区。200 OK 只代表服务器接受并处理了请求,不代表业务一定正确。
示例
订单创建接口返回 200,但其实仍然可能有问题:
- 返回的订单金额和商品价格不一致
- 优惠券明明过期了却还能抵扣
- 库存不足却创建成功
- 重复点击产生了两张订单
- 返回体字段缺失,前端解析失败
1.4 常见接口类型速览
| 类型 | 常见形式 | 特点 | 测试关注 |
|---|---|---|---|
| REST API | HTTP + JSON | 最常见,资源风格明显 | 方法、路径、状态码、字段契约 |
| RPC API | gRPC、Dubbo、Thrift | 服务间调用多,性能好 | 协议兼容、序列化、超时、重试 |
| Webhook / 回调 | 第三方主动推送 | 异步触发 | 签名校验、重复推送、顺序问题 |
| 文件接口 | 上传/下载 | 常涉及大文件和格式解析 | 大小限制、类型校验、断点续传 |
| 流式接口 | SSE、WebSocket | 服务端持续推送数据 | 连接稳定性、顺序、结束信号 |
1.5 接口测试在测试体系中的位置
从教学角度讲,必须把接口测试放回整个测试体系里理解,否则很容易产生两个误区:一是把它看低,觉得只是"发请求";二是把它看太高,觉得可以替代一切测试。
| 层级 | 回答的问题 | 典型代表 | 适合发现什么 |
|---|---|---|---|
| 单元测试 | 单个函数、单个类对不对 | JUnit、pytest | 计算逻辑、边界处理 |
| 接口测试 | 模块之间交互对不对 | Postman、curl、pytest、JMeter | 契约、业务规则、状态流转、权限 |
| UI 测试 | 用户走页面流程对不对 | Selenium、Playwright、Appium | 页面交互、前端展示、端到端体验 |
| 性能 / 稳定性测试 | 高并发、高负载下还能不能扛住 | JMeter、k6、Locust | 吞吐、延迟、资源瓶颈 |
老师视角总结
接口测试是测试体系里的"中段主力"。它没有单元测试那么细,也没有 UI 测试那么贴近用户,但它在效率、定位速度、业务覆盖深度之间取得了最好的平衡。
课堂练习
**练习:**挑你当前项目里的 5 个接口,尝试判断:
- 它属于哪种接口类型?
- 它最核心的业务规则是什么?
- 如果线上出问题,最可能错在哪一层?
第2章:HTTP 请求与响应基础
2.1 一个请求由哪些部分组成
对于最常见的 HTTP 接口来说,一个请求通常由路径、方法、请求头、参数和请求体组成。
POST /api/v1/orders?source=app HTTP/1.1
Host: shop.example.com
Authorization: Bearer eyJhbGci...
Content-Type: application/json
X-Trace-Id: 8f3d92
{
"user_id": 1001,
"items": [
{ "sku_id": "SKU-001", "count": 2 }
],
"coupon_id": "CPN-2026-01",
"address_id": 8899
}| 组成部分 | 作用 | 典型测试点 |
|---|---|---|
| Method | 说明要做什么操作 | GET/POST/PUT/DELETE 是否符合语义 |
| Path | 标识资源 | 路径参数缺失、非法值、大小写 |
| Query | 筛选、排序、分页等附加条件 | 默认值、边界值、组合条件 |
| Headers | 身份、格式、链路信息 | 鉴权、签名、Content-Type、幂等键 |
| Body | 承载业务数据 | 必填、类型、长度、嵌套对象、空值 |
2.2 常见 HTTP 方法的业务语义
| 方法 | 常见语义 | 测试提醒 |
|---|---|---|
| GET | 查询数据 | 不应修改数据;注意分页和缓存 |
| POST | 创建 / 提交动作 | 重点关注重复提交和幂等性 |
| PUT | 整体更新 | 缺失字段是否被覆盖为空 |
| PATCH | 部分更新 | 只改一部分时其他字段是否保持 |
| DELETE | 删除资源 | 是否真删、软删、重复删是否报错 |
2.3 请求体常见格式
| 格式 | 应用场景 | 典型问题 |
|---|---|---|
| application/json | 绝大多数业务接口 | 字段类型、空值、嵌套对象结构错误 |
| x-www-form-urlencoded | 传统表单、OAuth | 编码问题、重复字段覆盖 |
| multipart/form-data | 文件上传 | 文件大小、MIME 类型、文件名注入 |
| text/plain | Webhook、签名串 | 换行、转义、编码差异 |
2.4 响应里要看什么
收到响应后,不要只盯着状态码。至少要同时看状态码、返回结构、关键字段值、错误信息。
HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 0,
"message": "success",
"data": {
"order_id": "ORD202604140001",
"amount": 199.00,
"status": "PENDING_PAY"
},
"request_id": "req_8f3d92"
}| 检查项 | 为什么重要 |
|---|---|
| HTTP 状态码 | 判断协议层是否成功,如 200/400/401/404/500 |
| 业务码 code | 区分业务成功还是业务失败 |
| 数据结构 | 字段是否齐全,类型是否正确,是否符合文档约定 |
| 错误提示 | 报错是否准确、可理解、可定位 |
| request_id | 方便排查日志和链路问题 |
2.5 常见状态码怎么理解
| 状态码 | 含义 | 测试视角 |
|---|---|---|
| 200 | 请求成功 | 还要继续验证业务结果是否正确 |
| 201 | 创建成功 | 是否真的创建了资源 |
| 400 | 请求参数错误 | 参数错误是否被识别得足够细 |
| 401 | 未认证 | token 缺失、过期、伪造时是否正确拦截 |
| 403 | 无权限 | 认证通过但权限不足时是否拒绝 |
| 404 | 资源不存在 | 路径错误和业务对象不存在是否区分清楚 |
| 409 | 资源冲突 | 常见于重复创建、并发修改 |
| 429 | 请求过多 | 限流是否生效,是否有重试建议 |
| 500 | 服务端异常 | 不能把用户输入错误都甩成 500 |
2.6 同步接口和异步接口
同步接口:请求发出去,当前连接里直接拿到结果。 例子:登录、查询订单、修改昵称。 **测试重点:**响应内容、耗时、错误码。 异步接口:请求发出去,服务端先回一个任务号,真正结果后面再查或等回调。 例子:导出报表、音视频转码、批量审核。 **测试重点:**任务状态机、重复轮询、回调签名、超时补偿。
2.7 看接口文档时,先把请求和响应"画"出来
很多人看文档时是被动阅读,读完好像也懂了,但一写用例还是不知道从哪下手。更有效的方法,是把接口文档主动翻译成一个"输入模型 + 输出模型"。
示例
以创建订单接口为例:
输入模型:
method = POST
path = /api/orders
headers = Authorization / Content-Type / Idempotency-Key
body = user_id, sku_id, count, coupon_id, address_id
输出模型:
HTTP = 200 / 400 / 401 / 409 / 500
code = 0 / STOCK_NOT_ENOUGH / COUPON_EXPIRED / UNAUTHORIZED
data = order_id, amount, status, created_at
side effects = 落订单表、预占库存、发送消息一旦你能把接口文档先"画"成这个样子,测试点自然就出来了。
第3章:常见接口设计概念
3.1 鉴权与身份
同一个接口,对不同身份返回的结果可能完全不同。所以接口测试不能只准备一个万能账号,而要准备一组角色矩阵。
| 鉴权方式 | 常见场景 | 测试点 |
|---|---|---|
| Session / Cookie | 传统 Web 后台 | 登录态失效、跨账号串用、CSRF |
| Bearer Token / JWT | App、开放平台 | 过期、伪造、刷新、签名校验 |
| API Key / Secret | 服务对服务 | 泄露风险、权限粒度、白名单 |
| 签名验签 | 支付、Webhook | 重放攻击、时间戳漂移、签名字段顺序 |
权限测试的底层模型
权限判断通常可以拆成三个问题: 1. 你是谁? 2. 你能操作什么资源? 3. 你能做什么动作?
3.2 幂等性
幂等性是接口测试里最重要、也最容易被轻视的概念之一。它本质上在回答一个问题:当请求因为用户重复点击、客户端重试、网络抖动而被重复发送时,系统会不会把同一件事执行两次?
📌 定义
同一个请求重复发送多次,最终结果应与发送一次时保持一致。这就叫幂等。
| 业务场景 | 如果不幂等会怎样 | 风险等级 |
|---|---|---|
| 支付 | 重复扣款 | 极高 |
| 下单 | 重复建单 | 高 |
| 发券 | 用户多领一张券 | 高 |
| 回调通知 | 状态被重复推进 | 中 |
| 导入任务 | 重复写入数据 | 中 |
示例
典型场景:
- 用户手抖点了两次"支付"
- 客户端超时后自动重试
- MQ 消息重复投递
- 第三方回调通知重复发送 **测试重点:**会不会重复扣款、重复建单、重复发券、重复发送消息。
3.2.1 常见实现方式
| 方式 | 原理 | 测试点 |
|---|---|---|
| 唯一业务键 | 例如订单号、交易号天然唯一 | 重复提交同一业务键时是否拦截 |
| 幂等键 Idempotency-Key | 客户端生成唯一键,请求头携带 | 同 key 重放是否返回同结果 |
| 状态机校验 | 基于当前状态判断能否重复执行 | 已支付订单再次支付是否被拒绝 |
| 分布式锁 / 去重表 | 服务端在执行前做去重控制 | 高并发下是否仍然只成功一次 |
3.2.2 幂等性怎么测
- 先确认接口是否要求幂等,以及用什么机制实现。
- 构造完全相同的请求,连续发送 2 次到 5 次。
- 验证响应是否一致,尤其是业务码、订单号、流水号是否复用。
- 验证数据库、副作用、第三方调用是否真的只发生一次。
- 在并发条件下再测一次,因为串行幂等不代表并发幂等。
POST /api/payments
Headers:
Authorization: Bearer xxx
Idempotency-Key: PAY-20260414-0001如果第二次请求拿着相同的 Idempotency-Key 再来,系统理想行为应该是:返回第一次的结果,而不是重新执行一次支付。
3.3 一致性、事务与补偿
很多接口不是单库单表操作,而是多个动作串在一起。例如下单可能同时涉及:写订单表、扣库存、记优惠、发消息。此时接口成功,不代表每一个动作都成功;接口失败,也不代表所有动作都回滚了。
这类问题为什么难测
因为它们往往不是"接口报错"这种显性问题,而是"响应成功但账没对上"、"消息没发出去"、"库存扣了但订单没生成"这种隐性问题。
| 概念 | 意思 | 测试视角 |
|---|---|---|
| 本地事务 | 一个数据库事务内要么都成功,要么都失败 | 异常时是否真的回滚 |
| 最终一致性 | 短时间内可能不一致,但最终会补齐 | 延迟多久能一致,失败后如何补偿 |
| 补偿机制 | 前一步成功、后一步失败时,用反向动作恢复 | 失败时是否触发补偿,补偿是否幂等 |
示例
下单接口的一种失败场景:
- 订单表插入成功。
- 库存服务调用超时。
- 接口返回失败。
- 问题来了:订单表里的那条订单要不要删?库存有没有扣?用户会不会看到一张"幽灵订单"? 这就是接口测试里必须关注的一致性问题。
3.4 分页、排序、过滤
查询类接口里最常见的问题,恰恰不是查不到,而是查错了、漏了、顺序错了、翻页重复了。
| 维度 | 常见问题 | 测试样例 |
|---|---|---|
| 分页 | 第一页和第二页有重复 / 漏数据 | page=1,size=20 与 page=2,size=20 对比 |
| 排序 | 升序降序颠倒、相同值顺序不稳定 | 按创建时间、金额、热度分别验证 |
| 过滤 | 多条件组合后结果错误 | 状态 + 时间区间 + 关键字联合查询 |
| 默认值 | 没传参数时返回量过大或顺序异常 | 空查询条件请求 |
3.5 状态流转
很多业务接口不是单点判断,而是一个状态机。例如订单从 待支付 → 已支付 → 已发货 → 已完成。
待支付 → 已支付 → 已发货 → 已完成
测试不只是验证"能不能从 A 到 B",还要验证:
- 能不能跳过中间状态直接跳到后面。
- 非法状态下调用是否被拦截。
- 失败后是否能回滚或补偿。
- 并发操作会不会导致脏状态。
3.6 超时、重试、限流与熔断
这四个词经常一起出现,因为它们都属于接口在"不理想环境"下的保护机制。
| 机制 | 作用 | 典型测试点 |
|---|---|---|
| 超时 | 避免请求无限等待 | 依赖慢 30 秒时,接口多久返回失败 |
| 重试 | 对偶发错误自动再试一次 | 重试是否误把非幂等接口执行多次 |
| 限流 | 控制流量,防止服务被打爆 | 达到阈值后是否返回 429 |
| 熔断 | 依赖持续失败时快速失败,保护系统 | 依赖宕机后是否还在无意义重试 |
老师提醒
重试并不天然安全。只有在接口具备幂等性的前提下,重试才真正可靠。所以实际项目里常常是"幂等性 + 超时 + 重试"一起设计、一起测试。
3.7 版本兼容与向后兼容
接口一旦对外提供,就有兼容性问题。后端今天加了一个字段,老客户端能不能正常用?后端今天删了一个字段,会不会直接把线上 App 打挂?
常见风险
- 删除旧字段,导致旧版本客户端解析失败。
- 字段类型从数字改成字符串,前端排序错乱。
- 枚举值新增了新状态,客户端没有兜底显示。
- 接口默认行为改变,但文档没更新。
课堂练习
本章练习:
- 在你当前项目里,找一个需要幂等的接口,说明它为什么必须幂等。
- 找一个涉及状态流转的接口,画出它的状态图。
- 找一个查询接口,列出它在分页、排序、过滤三个维度的测试点。
第4章:接口测试的核心理论与文档分析
4.1 为什么说"接口文档本身就是第一个被测对象"
一份不清晰的接口文档,会直接制造歧义、返工和线上事故。很多测试问题并不是测出来的,而是在文档评审阶段就应该被挡住。
文档评审要问的四个问题
- 接口到底解决什么业务问题?
- 哪些输入合法,哪些输入非法?
- 成功和失败分别长什么样?
- 调用后会产生哪些副作用?
4.2 一份合格的接口文档至少要包含什么
| 模块 | 必须写清的内容 |
|---|---|
| 接口标识 | 方法、路径、版本、接口名称、负责人 |
| 入参 | 字段名、类型、是否必填、默认值、约束、示例 |
| 出参 | 状态码、业务码、字段定义、成功示例、失败示例 |
| 鉴权 | 需要什么 token、什么角色、什么签名 |
| 业务规则 | 前置条件、状态流转、边界规则、幂等说明 |
| 副作用 | 是否落库、发消息、调第三方、影响缓存 |
4.3 怎么从文档里拆出测试点
读业务规则 → 拆输入模型 → 拆输出模型 → 补副作用和依赖 → 形成用例清单
从教学上讲,测试点的来源通常有四类:
- **字段约束:**必填、长度、格式、枚举、精度。
- **业务规则:**库存、权限、时效、状态。
- **系统机制:**幂等、重试、限流、回调、补偿。
- **上下游影响:**DB、缓存、MQ、第三方服务。
4.4 从"接口能通"到"业务能跑通"
真正有价值的接口测试,不是孤立地测一个 URL,而是把接口放回业务流程里看。一个订单创建接口,即使本身返回正常,如果后续支付、库存、消息通知全部出问题,这条链路仍然是失败的。
| 维度 | 关注点 | 例子 |
|---|---|---|
| 功能正确性 | 业务规则是否正确执行 | 优惠券过期后不能下单抵扣 |
| 数据正确性 | 金额、时间、状态、字段是否准确 | 返回金额保留两位小数 |
| 鲁棒性 | 异常输入、并发、重试、超时是否稳 | 重复请求不会重复建单 |
| 安全性 | 权限、敏感数据、签名、注入 | 普通用户不能查询他人订单 |
4.5 测试视角要覆盖正向、反向和链路
正向测试:给合法输入,验证系统正确处理。 例子:用户名密码正确,登录成功并返回 token。 反向 + 链路测试:给非法输入、缺失输入、越权输入,或把接口放进完整业务流程里验证。 例子:密码错误、token 过期、越权访问、下单后库存是否真的变化。
4.6 接口测试结果怎么记录
接口测试的记录最好不要只写"通过/失败"。至少保留这些关键信息:
| 字段 | 说明 |
|---|---|
| 接口名 / 用例 ID | 方便回归和追踪 |
| 请求内容 | 路径、方法、参数、请求体、header |
| 实际响应 | 状态码、响应体、响应时间 |
| 数据库 / 日志验证 | 是否真的落库、是否真的发消息 |
| 结论 | 通过 / 失败 / 阻塞 |
| 缺陷等级 | P0 / P1 / P2 |
课堂练习
本章练习:
- 拿一份你们项目里的接口文档,检查它是否写清了失败示例和幂等说明。
- 从文档中至少拆出 10 个测试点,并说明每个测试点来自哪一类信息。
- 把其中 3 个测试点分别归到正向、反向、链路三类测试中。
第5章:传统黑盒方法怎么落到接口上
5.1 等价类划分
把一大堆可能输入划成几个代表性类别,每类挑一个典型值来测。
示例
注册接口里的年龄字段 age:
| 类别 | 输入示例 | 预期 |
|---|---|---|
| 有效等价类 | 18 / 25 / 60 | 注册成功 |
| 无效等价类:过小 | -1 / 0 / 17 | 提示年龄不合法 |
| 无效等价类:过大 | 151 / 999 | 提示年龄不合法 |
| 无效等价类:类型错误 | "abc" / null / [] | 参数类型校验失败 |
5.2 边界值分析
接口最容易出问题的地方,往往是边界,而不是中间值。
| 规则 | 关键值 | 推荐测试点 |
|---|---|---|
| 用户名长度 4~20 | 3 / 4 / 20 / 21 | 边界前一位、边界值、边界后一位 |
| 分页大小最大 100 | 0 / 1 / 100 / 101 | 非法最小值、合法最小值、合法最大值、超上限 |
| 优惠券有效期到 23:59:59 | 前 1 秒 / 当下 / 后 1 秒 | 时间边界最容易漏 |
5.3 判定表法
当一个接口受多个条件共同影响时,用判定表最清晰。
示例
退款申请接口:
- C1:订单是否已支付
- C2:是否在 7 天退款期内
- C3:商品是否已发货 | # | C1 | C2 | C3 | 预期 | | --- | --- | --- | --- | --- | | 1 | 否 | 是 | 否 | 不能退款,订单未支付 | | 2 | 是 | 否 | 否 | 不能退款,超过时限 | | 3 | 是 | 是 | 否 | 允许退款 | | 4 | 是 | 是 | 是 | 走售后流程,不是普通退款 |
5.4 状态迁移法
适合订单、工单、审批、任务这类明显有状态流转的接口。 核心问题是:哪些转移合法,哪些转移非法。
草稿 → 待审核 → 已通过 → 已发布
接口测试要检查:
- 草稿能否直接发布
- 已通过是否还能退回草稿
- 已发布重复发布会怎样
- 并发审核时状态是否冲突
5.5 场景法
单接口没问题,不代表整条链路没问题。很多 bug 是多个接口串起来以后才出现的。
示例
一条完整的用户旅程: 注册→ 登录→ 加入购物车→ 提交订单→ 支付 测试时不要只测其中一个接口,要看整个链路里的数据有没有前后对齐。
第6章:接口测试的准备与产出
6.1 做接口测试前要准备什么
| 准备项 | 内容 | 为什么重要 |
|---|---|---|
| 接口文档 | 路径、参数、示例、错误码、业务规则 | 没有文档就无法判断契约是否一致 |
| 测试环境 | 服务地址、账号、依赖服务、数据库 | 环境不稳会把真实问题淹没 |
| 测试数据 | 账号、订单、商品、库存、优惠券 | 没数据很多场景根本跑不起来 |
| 日志与 DB 权限 | 查询日志、查表、查消息 | 否则只能看到表面现象 |
| 工具 | Postman、Apifox、curl、Swagger、抓包工具 | 提高执行效率 |
6.2 用例模板长什么样
| 用例ID | 接口 | 场景 | 前置条件 | 请求数据 | 预期状态码 | 预期业务结果 | 数据库校验 | 优先级 |
|--------|------|------|----------|----------|------------|--------------|------------|--------|
| API-01 | POST /api/login | 正常登录 | 账号已注册 | 正确用户名密码 | 200 | 返回 token | 生成登录态 | P0 |
| API-02 | POST /api/login | 密码错误 | 账号已注册 | 错误密码 | 401 | 提示认证失败 | 不生成登录态 | P0 |6.3 好的接口用例至少覆盖哪些维度
接口测试基础清单
- 正常流程
- 必填 / 非必填
- 类型错误 / 长度越界 / 特殊字符
- 鉴权 / 越权 / 角色差异
- 重复提交 / 并发 / 重试
- 分页 / 排序 / 过滤
- 状态流转
- 错误码 / 错误提示
- 落库 / 缓存 / 消息 / 回调等副作用
6.4 基础篇学完后你应该具备什么能力
- 能看懂一份接口文档,知道该看哪些字段
- 知道普通 HTTP 接口有哪些基础测试点
- 能用等价类、边界值、判定表、状态迁移拆接口用例
- 知道接口测试不只是看状态码,还要看业务和副作用
课堂练习
**综合练习:**拿你当前项目里的一个"创建类接口"(如创建订单、创建工单、创建任务),完成以下动作:
- 画出请求和响应结构
- 列出 10 个基础测试点
- 写出 3 条正常用例、3 条异常用例、2 条边界用例、2 条权限用例
- 标出其中哪些属于 P0 核心用例
补充参考答案要点
- 本篇练习的答案重点应覆盖接口组成、状态码、参数校验、幂等性和副作用检查。
- 对于查询类接口,回答时要想到分页、排序、过滤、空结果和边界值,而不只是“返回 200”。
- 综合练习里最关键的是能把创建类接口拆成参数层、业务层、状态层和异常层来设计用例。