【接口与API】12 | 看懂接口文档，其实只需要这3个概念（附：接口文档三定位）

郭菁菁

500人浏览 · 2026-04-15 07:00:00

郭菁菁 · 2026-04-15 07:00:00 发布

下午两点，开发发了一个链接

下午两点，开发在群里发了一个链接：“接口文档更新了，你们确认一下。”

你点开链接，看到这样一个页面：

GET /api/v1/orders
Query Parameters:
  - page: int, optional, default=1
  - size: int, optional, default=20, max=100
  - status: string, optional, enum: [pending, paid, shipped, completed, cancelled]
  - userId: string, required

Response:
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 100,
    "list": [
      {
        "orderId": "string",
        "amount": "number",
        "status": "string",
        "createTime": "string"
      }
    ]
  }
}

你盯着这个页面看了五分钟。

你看到了很多词：GET、Query Parameters、required、optional、enum、Response、code……

你大概能猜到一些意思，但你不敢确定。

你不知道什么是“enum”，不知道“code:0”是什么意思，不知道“page”和“size”为什么要这样传。

你其实知道你没看懂。

但你更怕的是——你问了之后，别人发现你不懂。

你想问问和自己关系相熟的开发，但你已经问了他很多次了。

你怕他觉得你烦，更怕这样下去他会觉得你不专业。

于是你硬着头皮回了一句：“看起来没问题。”

然后你关掉页面，祈祷千万别出问题。

接口文档只回答三个问题

接口文档看起来很复杂，但它的结构是固定的。

你不需要看懂每一行。你只需要看懂三种信息：“要什么”“给什么”“怎么知道好不好”。

所有接口文档，本质上只有三行信息，即在回答这三个问题：

调用这个接口，我需要给你什么？（请求）
你处理完了，会给我什么？（响应）
我怎么知道我调用对了还是错了？（状态与错误码）

就这么简单。

那些让你头晕的英文单词，只是这三种信息的“标签”。就像菜单上的“主料”“辅料”“口味”，标签不同，但都是在描述同一件事。

你不需要成为程序员才能看懂接口文档。你只需要学会“定位”这三种信息。

一旦你掌握了这个能力，你再也不会被接口文档吓到。你会像一个看懂菜单的人，知道点什么、怎么点、点了之后会来什么。

点外卖类比：三个核心概念

我们用“点外卖”这个场景，把接口文档的三个核心概念讲清楚。

概念一：请求——你要给什么

你在外卖App上点餐，你需要告诉系统什么？

你要哪家店？（端点）
你要点什么菜？（商品ID）
要几份？（数量）
送到哪？（地址）
用什么支付？（支付方式）

这就是“请求”。

在接口文档里，“请求”部分会告诉你：

端点（Endpoint）：你要访问哪个地址。就像“麦当劳XX店”的地址。
方法（Method）：你要做什么事。GET是“查”，POST是“创建”，PUT是“改”，DELETE是“删”。
参数（Parameters）：你需要提供什么信息。有些是“必填”（required），有些是“选填”（optional）。有些有固定选项（enum），比如“口味”只能选“微辣、中辣、特辣”。

你看懂“请求”，就知道怎么“下单”了。

概念二：响应——你会得到什么

你点完餐，系统会给你什么？

订单号
预计送达时间
订单状态
总金额

这就是“响应”。

在接口文档里，“响应”部分会告诉你：

数据结构：返回的信息长什么样。比如订单号在data.orderId这个位置。
字段类型：每个字段是什么类型的数据。string是文字，number是数字，boolean是是非，array是列表。

你看懂“响应”，就知道“会收到什么”了。

概念三：状态与错误——怎么知道好不好

你点完餐，怎么知道成功了？

系统返回一个订单号，说明成功了
如果系统提示“余额不足”，说明失败了

这就是“状态与错误”。

在接口文档里，这部分通常用两种方式表达：

HTTP状态码：200表示成功，400表示你传的参数有问题，401表示你没登录，403表示你没权限，500表示服务器挂了。
业务状态码：接口返回的code字段。比如code:0表示业务成功，code:1001表示“订单不存在”。

你看懂“状态与错误”，就知道“成没成功、失败了怎么办”。

现在，我们再回头看那段天书：

GET /api/v1/orders
Query Parameters:
  - page: int, optional, default=1
  - size: int, optional, default=20, max=100
  - status: string, optional, enum: [pending, paid, shipped, completed, cancelled]
  - userId: string, required

Response:
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 100,
    "list": [...]
  }
}

翻译成人话就是：

请求：

这是一个“查询订单列表”的接口（GET /api/v1/orders）
你要告诉我：查谁的订单（userId，必填），查第几页（page，不填默认第1页），每页多少条（size，不填默认20条，最多100条），要不要按状态筛选（status，不填就查全部）

响应：

如果code是0，说明成功了
data.total是总共有多少条订单
data.list是这一页的订单列表

你看，是不是一点都不难了？

两个致命错误：只看响应、分不清必填选填

错误一：只看响应，不看错误码

BA最常见的错误，是 “只看响应，不看错误码”。

我见过一个真实案例。

BA在测试环境验证一个接口，发现接口返回了数据，她就说“接口没问题”。

结果上线后，用户投诉：“我查不到订单！”

开发查了日志，发现接口返回的是code:1001（订单不存在），但前端没有处理这个错误码，直接显示“暂无数据”。

用户以为真的没有订单，其实只是查错了条件。

问题出在哪？BA只看了“响应”，没看“错误码”。

如果她测试的时候，故意传一个不存在的订单号，看接口怎么返回，就会发现返回的是code:1001而不是code:0。她就会问：“这个错误码前端会处理吗？”

错误二：分不清“必填”和“选填”

另一个常见错误是：不知道“必填”和“选填”的区别。

BA在写需求时，说“这个字段要传给接口”。开发问：“这个字段是必填还是选填？”

BA说：“应该要传吧。”

开发按照“选填”做了。结果上线后，某个场景下这个字段没传，接口报错了。

BA说：“我不是说‘应该’吗？你怎么不传？”

开发说：“你说‘应该’，不是‘必须’。”

你看，“应该”和“必须”在接口文档里，是生死之别。

接口文档三定位：三个区域，三个问题

我送你一个模型，叫 “接口文档三定位”。

以后你看任何接口文档，只需要定位三个区域：

区域一：请求区

问自己三个问题：

这个接口是干什么的？（端点和方法）
我需要传什么参数？（哪些必填？哪些选填？）
参数的格式是什么？（字符串还是数字？有没有固定选项？）

区域二：响应区

问自己三个问题：

成功时返回什么数据结构？
数据放在哪个字段里？（data里还是直接返回？）
每个字段的含义是什么？

区域三：错误区

问自己三个问题：

怎么判断成功？（HTTP状态码200？业务状态码0？）
失败时会返回什么？（错误码有哪些？每个错误码什么意思？）
前端需要区分处理不同的错误码吗？

你把这三个区域的信息提炼出来，写在你的需求文档或测试用例里，你就再也不会漏掉关键信息。

三个问题，检验你是否真懂接口文档

接口文档不是用来“看懂每一行”的，是用来“找到关键三行”的。

下次你拿到一份接口文档时，用这三个问题自检：

问题1：我能说清楚“调用这个接口需要传什么”吗？

哪些字段是必填的？如果少传了会怎样？
如果你说不清楚，说明你没看懂请求部分。

问题2：我能说清楚“成功时返回什么”吗？

数据在哪个字段里？每个字段什么意思？
如果你说不清楚，说明你没看懂响应部分。

问题3：我能说清楚“失败了会怎样”吗？

怎么判断失败？不同的失败场景返回什么？
如果你说不清楚，说明你没看懂错误处理部分。

回头看：你已经走了多远

第一篇：为什么需要懂技术——因为不懂，连AI的错都看不出来。

第二篇：怎么学技术——类比、问问题、一句话讲清。

第三篇：为什么开发总怼你——把“说明”翻译成“定义”。

第四篇：技术世界在解决什么问题——存、传、算、显。

第五篇：点一下按钮发生了什么——微观请求之旅。

第六篇：怎么看懂系统架构图——宏观三段式（入口-处理-出口）。

第七篇：为什么电脑可以同时做多件事——操作系统的三个职责（CPU、内存、文件）。

第八篇：前端 vs 后端，到底谁在干活？——前后端分工矩阵。

第九篇：为什么系统会“没反应”？——状态四象限（用户感知设计）。

第十篇：什么是API？——API三问（端点、参数、响应）。

第十一篇：为什么系统之间必须“说话”？——系统沟通五要素。

第十二篇：看懂接口文档——接口文档三定位（请求、响应、错误）。

文章	核心问题	你学会了什么
01	为什么需要懂技术？	不懂技术，连AI的错都看不出来
02	怎么学技术？	类比、问问题、一句话讲清
03	为什么开发总怼你？	把“说明”翻译成“定义”
04	技术到底在解决什么？	存-传-算-显（底层框架）
05	点一下按钮发生了什么？	微观请求之旅
06	怎么看懂系统架构图？	宏观三段式
07	为什么电脑可以同时做多件事？	操作系统的三个职责
08	前端和后端谁干什么？	前后端分工矩阵
09	为什么系统会“没反应”？	状态四象限
10	什么是API？	API三问
11	为什么系统之间必须“说话”？	系统沟通五要素
12	看懂接口文档	接口文档三定位