第 3 章:报文与 JSON
上一章看的是信封,这一章拆开信封。请求和响应都由四段组成,前三段是"怎么处理这条消息"的说明,最后一段才是数据本身。
学习目标
- 说清 HTTP 报文的四段结构,知道空行不是装饰
- 认识六个必懂的请求头,知道
Content-Type写错会出什么事 - 掌握 JSON 的六种类型和五条语法规则
- 会用 Python 做序列化和反序列化,不再被中文转义和编码坑到
3.1 报文四段:起始行、头、空行、体
四段的作用:
| 段 | 请求里是什么 | 响应里是什么 |
|---|---|---|
| 起始行 | 方法 + 路径 + 协议版本 | 协议版本 + 状态码 + 原因短语 |
| 头 | 谁发的、要什么格式、凭证 | 内容的格式、长度、缓存策略 |
| 空行 | 必须有,标记"头结束" | 同样必须有 |
| 体 | 提交的数据 | 返回的数据 |
空行不是排版,它是头和体之间的分隔符。少了它,服务器会把体的第一行当成头来解析。
这段结构不用背。第 2.5 节的 curl -i 会把四段原样刷出来,你可以边看边对:状态行在哪一行结束、头有几条、空行之后是什么。
3.2 六个必懂的请求头
| 头 | 作用 | 常见错误 |
|---|---|---|
Host | 说明要访问哪个域名(同一 IP 可能挂多个站) | 手写报文时漏掉 |
Content-Type | 体的格式与编码 | 写成 text/plain 导致对方解析失败 |
Authorization | 凭证 | 格式少写 Bearer 前缀 |
Accept | 我希望返回什么格式 | 不写一般也行,但显式写更稳 |
User-Agent | 标识客户端(有些服务会校验) | 空 UA 被网关拦截 |
Content-Length | 体的字节长度(非字符数) | 中文算成"字符数"导致对不上 |
后两个不用手写:用 requests 这类库时,Host、Content-Length 会自动补。但 Content-Type 和 Authorization 需要你自己给对。
3.3 Content-Type:写错就是"鸡同鸭讲"
最常见的三种值:
| 值 | 意味着 | 谁用 |
|---|---|---|
application/json | 体是 JSON | 绝大多数 API |
application/x-www-form-urlencoded | 体是 a=1&b=2 形式 | 传统表单提交 |
multipart/form-data | 体是分块的表单(含文件) | 上传文件 |
发 JSON 时,必须写 application/json。只写 Content-Type: text/plain,很多框架会拒绝解析体,返回 400 或"缺少字段",排查半天以为是参数问题。
带编码的写法更完整:
Content-Type: application/json; charset=utf-8charset 说明"体里的文字用 UTF-8 编码"。中文项目里漏掉它,偶尔会出现乱码——尤其是老版本的服务端。
3.4 JSON:六种类型,五条规则
JSON 是"JavaScript Object Notation",但它跟语言无关,几乎所有语言都能读写。
一个嵌套的例子:
{
"id": "chatcmpl-123",
"created": 1734567890,
"choices": [
{
"index": 0,
"message": { "role": "assistant", "content": "你好" },
"finish_reason": "stop"
}
],
"usage": { "prompt_tokens": 12, "completion_tokens": 3, "total_tokens": 15 }
}2
3
4
5
6
7
8
9
10
11
12
五条必须记住的语法规则:
- 键必须用双引号,不能用单引号,也不能不加引号;
- 不能写注释。JSON 标准不支持
//或/* */,加了会解析失败; - 最后一个元素后面不能有逗号(尾逗号);
- 字符串里不能直接换行,要写成
\n; - 没有日期类型,时间一律用字符串(推荐 ISO 8601:
2025-11-18T10:30:00Z)。
很多"看起来像 JSON"的配置文件(比如某些工具的配置)其实允许注释和尾逗号,那是 JSON5 或 YAML,不要混为一谈。
3.5 序列化与反序列化
- 序列化:把程序里的对象变成 JSON 字符串(发出去之前);
- 反序列化:把 JSON 字符串变成程序里的对象(收到之后)。
Python 里就是两个函数:
import json
data = {"model": "gpt-4o", "messages": [{"role": "user", "content": "你好"}]}
# 序列化:dict → JSON 字符串
text = json.dumps(data, ensure_ascii=False)
print(text)
# {"model": "gpt-4o", "messages": [{"role": "user", "content": "你好"}]}
# 反序列化:JSON 字符串 → dict
obj = json.loads('{"id": 1, "name": "张三"}')
print(obj["name"]) # 张三2
3
4
5
6
7
8
9
10
11
12
ensure_ascii=False 是关键:默认 True 会把中文转成 \u4f60\u597d,虽然合法也能用,但日志和调试时几乎没法读。
中文为什么变成 \u4f60\u597d
这是 ASCII 转义:为了让纯 ASCII 环境也能传输,JSON 允许用 \uXXXX 表示任意 Unicode 字符。\u4f60 就是"你",\u597d 是"好"。它和乱码不是一回事——乱码是编码错配(UTF-8 被当 GBK 读),转义是"写法变了但内容没变"。
遇到乱码时检查顺序:
- 请求头有没有
charset=utf-8; - 代码读文件/读响应时有没有指定
encoding="utf-8"; - 数据库/终端是不是 UTF-8。
编码问题的一个真实场景
resp = requests.post(url, json=data) # 正确:库自动序列化 + 设 Content-Type
resp = requests.post(url, data=json.dumps(data)) # 错误:Content-Type 变成表单类型2
第二种写法看着"更可控",实际上 requests 会把 data= 当表单发,Content-Type 变成 application/x-www-form-urlencoded,服务端解析不出字段。发 JSON 就用 json= 参数,第 4 章会展开。
3.6 六个最常见的数据结构坑
调 API 时踩得最多的不是语法,是"以为字段是这样,其实不是":
| 坑 | 表现 | 怎么确认 |
|---|---|---|
字段可能是 null | data["name"].upper() 报 NoneType | 先判空或用 .get() |
| 数组可能为空 | data["items"][0] 越界 | 先判长度 |
| 数字可能是字符串 | "price": "49.00" 而不是 49.0 | 打印类型,别直接算 |
| 字段名大小写不同 | user_id vs userId | 照文档原样抄,别凭感觉 |
| 嵌套层级很深 | data["choices"][0]["message"]["content"] | 逐层打印,别一次取到底 |
| 分页字段不统一 | 有时 total,有时 count | 看响应示例,别猜 |
一个稳妥的取值习惯:
content = (
data.get("choices", [{}])[0]
.get("message", {})
.get("content")
)
if content is None:
print("响应里没有 content,原始数据:", data)2
3
4
5
6
7
看起来啰嗦,但比在生产环境里吃 KeyError 强。
本章小结
| 要点 | 说明 |
|---|---|
| 报文四段 | 起始行、头、空行、体 |
| 空行必须有 | 它是头和体的分隔符 |
Content-Type | 发 JSON 就写 application/json |
| JSON 六种类型 | 对象、数组、字符串、数字、布尔、null |
| 五条语法 | 双引号键、无注释、无尾逗号、\n 换行、日期用字符串 |
| 序列化 | json.dumps(..., ensure_ascii=False) |
| 反序列化 | json.loads(...) |
| 取值要防御 | null、空数组、类型不符都会让代码崩 |
下一章
报文和格式都懂了,该动手了。下一章用 Python 真正发出请求:requests 和 httpx 怎么选、超时必须设多少、重试怎么写才不会把对方打挂、连接复用为什么能快一倍。