请求与响应格式入门教程

编辑部发布 2026-06-27 10 分钟阅读 2,000 字

请求与响应格式（Request/Response Format）设定了客户端与服务器之间数据交换的结构规范，它决定了消息如何被正确解析和处理。该格式由请求行/状态行、头部字段和消息体三个核心组件构成——在API开发中，任何一部分的格式错误都有可能导致通信失败。本教程将带你从零搭建一个完整的请求-响应交互示例，并重点剖析新手最常踩中的三类陷阱：头部信息缺失、编码方式不匹配和消息体结构错误。

前置条件

开始前，请确认以下条件已满足：

能够正常访问目标API服务（请检查网络连通性和服务运行状态）
准备好支持发送HTTP请求的工具，例如curl、Postman，或浏览器开发者工具的网络面板
获取API文档或接口规范，至少需知道请求方法、URL、关键头部字段和消息体结构

适用边界提醒：本教程针对基于HTTP/HTTPS的RESTful API场景。如果处理的是WebSocket、gRPC或GraphQL，其请求与响应格式规则完全不同，不能直接套用以下步骤。

实施步骤

步骤一：确定请求的基本组成

每个HTTP请求必须包含以下三个要素：

请求行：请求方法（GET/POST/PUT/DELETE等）、目标URI、HTTP版本
头部字段：至少需要Content-Type（当存在请求体时）和Accept
消息体（可选）：对于POST/PUT/PATCH请求，通常包含需要发送的数据

常见误区：新手经常遗漏Accept头部字段，导致服务器默认返回HTML而非预期的JSON格式。即使API文档未明确说明，也建议显式地设置Accept: application/json。

步骤二：构建正确的请求消息体

JSON是当前最通用的请求体格式，但结构层面的错误十分常见。请参考以下示例：

{
  "product_id": "P10086",
  "quantity": 2,
  "shipping_address": {
    "city": "北京",
    "district": "海淀",
    "detail": "中关村大街1号"
  }
}

检查清单：

键名是否与API文档完全一致（大小写敏感）
数值类型是否匹配（字符串 vs 数字、布尔值 vs 字符串"true"）
嵌套结构是否符合预期的层级关系

边界案例：当一个字段允许为空值时，应该传递null、空字符串""，还是不传递该字段？这种细微差异在订单创建等场景下，可能会触发完全不同的业务逻辑。务必查阅API文档中规定的处理策略。

步骤三：发送请求并观察响应结构

一个完整的HTTP响应包含以下几个部分：

组成部分	示例	新手常见问题
状态行	`HTTP/1.1 200 OK`	只关注200状态码，忽略1xx/3xx/4xx/5xx的语义差异
响应头部	`Content-Type: application/json`	不检查Content-Type就直接解析消息体
消息体	`{"status": "success", "data": {...}}`	假设数据结构固定不变

完整工作示例（使用curl工具）：

curl -X POST https://api.example.com/v1/orders \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"product_id": "P10086", "quantity": 2}'

服务器返回内容如下：

HTTP/1.1 201 Created
Content-Type: application/json

{
  "status": "success",
  "order_id": "ORD20260627001",
  "created_at": "2026-06-27T14:30:00Z"
}

这里的关键观测点是：状态码是201 Created而非200 OK；响应体中的order_id值为字符串格式，尽管它看起来像是数字。

步骤四：处理响应数据

接收到响应后，按照以下顺序进行检查：

状态码含义：2xx表示成功，4xx表示客户端错误，5xx表示服务端错误
Content-Type：确认实际返回格式是否与Accept头部字段一致
数据结构：参照API文档，验证字段名、类型和嵌套层级是否准确
分页/列表结构：如果返回的是列表数据，检查page、total、items等元数据字段

遇到响应码422 Unprocessable Entity但消息体为空的情况：这是常见陷阱，问题通常出在请求头部的Content-Type与实际消息体格式不一致。例如，头部写的是application/json，但消息体却是URL编码格式，或者JSON存在语法错误（如末尾多了一个逗号）。

验证检查

发送前必须验证的三件事

当前环境下的API版本是否与你所参考的文档版本一致（检查URL路径中的版本号，如/v1/、/v2/）
所有必需的头部字段是否已正确设置，尤其是认证头部（如Authorization: Bearer <token>）
请求体JSON能否被标准JSON解析器正确解析（可以使用jsonlint或在线验证工具）

收到响应后的验证步骤

对比实际返回的Content-Type与预期值
检查响应头部中的X-RateLimit-Remaining（如果存在），确认是否被限流
使用API文档中的示例响应，逐字段进行对比

常见问题排查

问题一：请求被拒，返回`400 Bad Request`

排查步骤：

确认请求行格式正确（特别检查URI中是否包含中文字符）
检查Content-Type与实际消息体格式是否匹配
使用验证工具检查JSON语法（常见问题包括：末尾多余逗号、字符串未加双引号、使用单引号代替双引号）

问题二：收到`401 Unauthorized`或`403 Forbidden`

检查清单：

认证token是否已过期（大多数token都有固定的有效期）
token是否正确放置在Authorization头部字段中
当前用户或应用是否具有访问请求资源的权限

问题三：响应格式与文档不符

优先处理建议：

确认URL路径中的API版本号是否正确
检查请求头部中的Accept是否指定了正确的格式
查阅该API的官方更新日志或变更通告——格式变更通常会提前在版本更新中告知

何时停止继续操作：如果连续三次返回同一种非预期格式，并且排除请求本身错误后，应主动查阅官方文档或联系技术支持，而不是反复调整客户端代码。

常见问题解答