Skip to content

接口测试文档手册 · 基础篇

接口认知 + 理论基础 · 用老师讲课的方式,把概念、理论、实操入口和练习串起来

这篇怎么学

建议按 概念 → 理论 → 实操 → 练习 的顺序往下读。先建立接口测试的底层认知,再理解幂等性、状态机、兼容性这些核心理论,最后再去做工具调用和用例编写,学习效率会高很多。

第1章:接口测试到底在测什么

1.1 什么是接口

接口(API)本质上是系统之间交换数据和能力的约定。前端点一个按钮,App 发一个请求,服务端返回一个结果,这中间那条"通信通道"就是接口。

📖 一句话理解

接口 = 一份约定。约定了请求怎么传响应怎么回什么情况下成功什么情况下失败

示例

电商下单场景: 用户点击"提交订单"→ 前端调用 POST /api/orders→ 后端校验库存/价格/地址→ 返回订单号和支付状态 如果这里库存校验错了、价格字段丢了、状态码不对,前端页面可能只会提示"提交失败",但真正的问题其实发生在接口层。

1.2 为什么很多问题要在接口层发现

接口层离业务核心更近,噪音更少,更容易精准定位问题。很多线上事故,本质都不是 UI 问题,而是接口契约、数据处理或状态流转问题。

层级能发现什么优点局限
UI 测试按钮、页面跳转、展示文案贴近用户定位慢,容易受前端影响
接口测试请求参数、业务规则、返回结果、状态流转定位准、执行快、覆盖深看不到真实页面体验
单元测试单个函数/模块逻辑粒度最细跨系统流程覆盖不足

测试价值

做接口测试,不只是为了验证"接口能通",更是为了验证业务规则是否真的被正确执行

1.3 接口测试不是"调通就行"

很多初学者会把接口测试理解成:"拿 Postman 发一下,看到 200 就算通过。" 这是最典型的误区。200 OK 只代表服务器接受并处理了请求,不代表业务一定正确。

示例

订单创建接口返回 200,但其实仍然可能有问题:

  • 返回的订单金额和商品价格不一致
  • 优惠券明明过期了却还能抵扣
  • 库存不足却创建成功
  • 重复点击产生了两张订单
  • 返回体字段缺失,前端解析失败

1.4 常见接口类型速览

类型常见形式特点测试关注
REST APIHTTP + JSON最常见,资源风格明显方法、路径、状态码、字段契约
RPC APIgRPC、Dubbo、Thrift服务间调用多,性能好协议兼容、序列化、超时、重试
Webhook / 回调第三方主动推送异步触发签名校验、重复推送、顺序问题
文件接口上传/下载常涉及大文件和格式解析大小限制、类型校验、断点续传
流式接口SSE、WebSocket服务端持续推送数据连接稳定性、顺序、结束信号

1.5 接口测试在测试体系中的位置

从教学角度讲,必须把接口测试放回整个测试体系里理解,否则很容易产生两个误区:一是把它看低,觉得只是"发请求";二是把它看太高,觉得可以替代一切测试。

层级回答的问题典型代表适合发现什么
单元测试单个函数、单个类对不对JUnit、pytest计算逻辑、边界处理
接口测试模块之间交互对不对Postman、curl、pytest、JMeter契约、业务规则、状态流转、权限
UI 测试用户走页面流程对不对Selenium、Playwright、Appium页面交互、前端展示、端到端体验
性能 / 稳定性测试高并发、高负载下还能不能扛住JMeter、k6、Locust吞吐、延迟、资源瓶颈

老师视角总结

接口测试是测试体系里的"中段主力"。它没有单元测试那么细,也没有 UI 测试那么贴近用户,但它在效率、定位速度、业务覆盖深度之间取得了最好的平衡。

课堂练习

**练习:**挑你当前项目里的 5 个接口,尝试判断:

  1. 它属于哪种接口类型?
  2. 它最核心的业务规则是什么?
  3. 如果线上出问题,最可能错在哪一层?

第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/plainWebhook、签名串换行、转义、编码差异

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 / JWTApp、开放平台过期、伪造、刷新、签名校验
API Key / Secret服务对服务泄露风险、权限粒度、白名单
签名验签支付、Webhook重放攻击、时间戳漂移、签名字段顺序

权限测试的底层模型

权限判断通常可以拆成三个问题: 1. 你是谁? 2. 你能操作什么资源? 3. 你能做什么动作?

3.2 幂等性

幂等性是接口测试里最重要、也最容易被轻视的概念之一。它本质上在回答一个问题:当请求因为用户重复点击、客户端重试、网络抖动而被重复发送时,系统会不会把同一件事执行两次

📌 定义

同一个请求重复发送多次,最终结果应与发送一次时保持一致。这就叫幂等。

业务场景如果不幂等会怎样风险等级
支付重复扣款极高
下单重复建单
发券用户多领一张券
回调通知状态被重复推进
导入任务重复写入数据
示例

典型场景:

  • 用户手抖点了两次"支付"
  • 客户端超时后自动重试
  • MQ 消息重复投递
  • 第三方回调通知重复发送 **测试重点:**会不会重复扣款、重复建单、重复发券、重复发送消息。

3.2.1 常见实现方式

方式原理测试点
唯一业务键例如订单号、交易号天然唯一重复提交同一业务键时是否拦截
幂等键 Idempotency-Key客户端生成唯一键,请求头携带同 key 重放是否返回同结果
状态机校验基于当前状态判断能否重复执行已支付订单再次支付是否被拒绝
分布式锁 / 去重表服务端在执行前做去重控制高并发下是否仍然只成功一次

3.2.2 幂等性怎么测

  1. 先确认接口是否要求幂等,以及用什么机制实现。
  2. 构造完全相同的请求,连续发送 2 次到 5 次。
  3. 验证响应是否一致,尤其是业务码、订单号、流水号是否复用。
  4. 验证数据库、副作用、第三方调用是否真的只发生一次。
  5. 在并发条件下再测一次,因为串行幂等不代表并发幂等。
POST /api/payments
Headers:
  Authorization: Bearer xxx
  Idempotency-Key: PAY-20260414-0001

如果第二次请求拿着相同的 Idempotency-Key 再来,系统理想行为应该是:返回第一次的结果,而不是重新执行一次支付

3.3 一致性、事务与补偿

很多接口不是单库单表操作,而是多个动作串在一起。例如下单可能同时涉及:写订单表、扣库存、记优惠、发消息。此时接口成功,不代表每一个动作都成功;接口失败,也不代表所有动作都回滚了。

这类问题为什么难测

因为它们往往不是"接口报错"这种显性问题,而是"响应成功但账没对上"、"消息没发出去"、"库存扣了但订单没生成"这种隐性问题。

概念意思测试视角
本地事务一个数据库事务内要么都成功,要么都失败异常时是否真的回滚
最终一致性短时间内可能不一致,但最终会补齐延迟多久能一致,失败后如何补偿
补偿机制前一步成功、后一步失败时,用反向动作恢复失败时是否触发补偿,补偿是否幂等
示例

下单接口的一种失败场景:

  1. 订单表插入成功。
  2. 库存服务调用超时。
  3. 接口返回失败。
  4. 问题来了:订单表里的那条订单要不要删?库存有没有扣?用户会不会看到一张"幽灵订单"? 这就是接口测试里必须关注的一致性问题。

3.4 分页、排序、过滤

查询类接口里最常见的问题,恰恰不是查不到,而是查错了、漏了、顺序错了、翻页重复了

维度常见问题测试样例
分页第一页和第二页有重复 / 漏数据page=1,size=20 与 page=2,size=20 对比
排序升序降序颠倒、相同值顺序不稳定按创建时间、金额、热度分别验证
过滤多条件组合后结果错误状态 + 时间区间 + 关键字联合查询
默认值没传参数时返回量过大或顺序异常空查询条件请求

3.5 状态流转

很多业务接口不是单点判断,而是一个状态机。例如订单从 待支付已支付已发货已完成

待支付 → 已支付 → 已发货 → 已完成

测试不只是验证"能不能从 A 到 B",还要验证:

  • 能不能跳过中间状态直接跳到后面。
  • 非法状态下调用是否被拦截。
  • 失败后是否能回滚或补偿。
  • 并发操作会不会导致脏状态。

3.6 超时、重试、限流与熔断

这四个词经常一起出现,因为它们都属于接口在"不理想环境"下的保护机制。

机制作用典型测试点
超时避免请求无限等待依赖慢 30 秒时,接口多久返回失败
重试对偶发错误自动再试一次重试是否误把非幂等接口执行多次
限流控制流量,防止服务被打爆达到阈值后是否返回 429
熔断依赖持续失败时快速失败,保护系统依赖宕机后是否还在无意义重试

老师提醒

重试并不天然安全。只有在接口具备幂等性的前提下,重试才真正可靠。所以实际项目里常常是"幂等性 + 超时 + 重试"一起设计、一起测试。

3.7 版本兼容与向后兼容

接口一旦对外提供,就有兼容性问题。后端今天加了一个字段,老客户端能不能正常用?后端今天删了一个字段,会不会直接把线上 App 打挂?

常见风险

  • 删除旧字段,导致旧版本客户端解析失败。
  • 字段类型从数字改成字符串,前端排序错乱。
  • 枚举值新增了新状态,客户端没有兜底显示。
  • 接口默认行为改变,但文档没更新。

课堂练习

本章练习:

  1. 在你当前项目里,找一个需要幂等的接口,说明它为什么必须幂等。
  2. 找一个涉及状态流转的接口,画出它的状态图。
  3. 找一个查询接口,列出它在分页、排序、过滤三个维度的测试点。

第4章:接口测试的核心理论与文档分析

4.1 为什么说"接口文档本身就是第一个被测对象"

一份不清晰的接口文档,会直接制造歧义、返工和线上事故。很多测试问题并不是测出来的,而是在文档评审阶段就应该被挡住。

文档评审要问的四个问题

  1. 接口到底解决什么业务问题?
  2. 哪些输入合法,哪些输入非法?
  3. 成功和失败分别长什么样?
  4. 调用后会产生哪些副作用?

4.2 一份合格的接口文档至少要包含什么

模块必须写清的内容
接口标识方法、路径、版本、接口名称、负责人
入参字段名、类型、是否必填、默认值、约束、示例
出参状态码、业务码、字段定义、成功示例、失败示例
鉴权需要什么 token、什么角色、什么签名
业务规则前置条件、状态流转、边界规则、幂等说明
副作用是否落库、发消息、调第三方、影响缓存

4.3 怎么从文档里拆出测试点

读业务规则 → 拆输入模型 → 拆输出模型 → 补副作用和依赖 → 形成用例清单

从教学上讲,测试点的来源通常有四类:

  • **字段约束:**必填、长度、格式、枚举、精度。
  • **业务规则:**库存、权限、时效、状态。
  • **系统机制:**幂等、重试、限流、回调、补偿。
  • **上下游影响:**DB、缓存、MQ、第三方服务。

4.4 从"接口能通"到"业务能跑通"

真正有价值的接口测试,不是孤立地测一个 URL,而是把接口放回业务流程里看。一个订单创建接口,即使本身返回正常,如果后续支付、库存、消息通知全部出问题,这条链路仍然是失败的。

维度关注点例子
功能正确性业务规则是否正确执行优惠券过期后不能下单抵扣
数据正确性金额、时间、状态、字段是否准确返回金额保留两位小数
鲁棒性异常输入、并发、重试、超时是否稳重复请求不会重复建单
安全性权限、敏感数据、签名、注入普通用户不能查询他人订单

4.5 测试视角要覆盖正向、反向和链路

正向测试:给合法输入,验证系统正确处理。 例子:用户名密码正确,登录成功并返回 token。 反向 + 链路测试:给非法输入、缺失输入、越权输入,或把接口放进完整业务流程里验证。 例子:密码错误、token 过期、越权访问、下单后库存是否真的变化。

4.6 接口测试结果怎么记录

接口测试的记录最好不要只写"通过/失败"。至少保留这些关键信息:

字段说明
接口名 / 用例 ID方便回归和追踪
请求内容路径、方法、参数、请求体、header
实际响应状态码、响应体、响应时间
数据库 / 日志验证是否真的落库、是否真的发消息
结论通过 / 失败 / 阻塞
缺陷等级P0 / P1 / P2

课堂练习

本章练习:

  1. 拿一份你们项目里的接口文档,检查它是否写清了失败示例和幂等说明。
  2. 从文档中至少拆出 10 个测试点,并说明每个测试点来自哪一类信息。
  3. 把其中 3 个测试点分别归到正向、反向、链路三类测试中。

第5章:传统黑盒方法怎么落到接口上

5.1 等价类划分

把一大堆可能输入划成几个代表性类别,每类挑一个典型值来测。

示例

注册接口里的年龄字段 age

类别输入示例预期
有效等价类18 / 25 / 60注册成功
无效等价类:过小-1 / 0 / 17提示年龄不合法
无效等价类:过大151 / 999提示年龄不合法
无效等价类:类型错误"abc" / null / []参数类型校验失败

5.2 边界值分析

接口最容易出问题的地方,往往是边界,而不是中间值。

规则关键值推荐测试点
用户名长度 4~203 / 4 / 20 / 21边界前一位、边界值、边界后一位
分页大小最大 1000 / 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 基础篇学完后你应该具备什么能力

  1. 能看懂一份接口文档,知道该看哪些字段
  2. 知道普通 HTTP 接口有哪些基础测试点
  3. 能用等价类、边界值、判定表、状态迁移拆接口用例
  4. 知道接口测试不只是看状态码,还要看业务和副作用

课堂练习

**综合练习:**拿你当前项目里的一个"创建类接口"(如创建订单、创建工单、创建任务),完成以下动作:

  1. 画出请求和响应结构
  2. 列出 10 个基础测试点
  3. 写出 3 条正常用例、3 条异常用例、2 条边界用例、2 条权限用例
  4. 标出其中哪些属于 P0 核心用例

补充参考答案要点

  • 本篇练习的答案重点应覆盖接口组成、状态码、参数校验、幂等性和副作用检查。
  • 对于查询类接口,回答时要想到分页、排序、过滤、空结果和边界值,而不只是“返回 200”。
  • 综合练习里最关键的是能把创建类接口拆成参数层、业务层、状态层和异常层来设计用例。