HTTP 报文解剖
本合集目录
本章目录
单册说明:本文件是卷 5 的第 2 章,可独立阅读。前置:5.1(契约与四要素)。本章把一次请求拆成一行行文本,让你在终端和浏览器里看到同一件事的两种呈现。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 5 · 后端与 API(第 2 / 8 章) |
| 前置章节 | 5.1 API 是什么 |
| 本章产出 | 一份逐行标注过的真实请求/响应 + 一张 curl 与 F12 的对照表 |
| 对应代码 | 无(只有命令,见 5.2.7) |
| 配图 | 无(后续统一制图) |
| 读完的判定 | 能看着一段报文说出"方法、路径、类型、长度、谁发的",并能指出哪里不对劲 |
5.2.1 一句话结论:报文就是纯文本,看不懂只因为没人拆给你看
先看一个几乎人人都遇到过的报错:
SyntaxError: Unexpected token '<', "<!DOCTYPE "... is not valid JSON
这句话的信息量很大,只是没人翻译:res.json() 拿到的不是 JSON,而是一段以 <!DOCTYPE 开头的 HTML。 也就是说,请求根本没打到接口上——它被前端的开发服务器接住了,返回了首页。
这章要给你的能力就是:在猜之前,先把报文摊开看。 HTTP 报文没有二进制魔法,它就是"一行请求行 + 若干行头 + 一个空行 + 一段体",谁都能读。
5.2.2 原理与方法
请求行:三个词说清"干什么"
POST /api/notes HTTP/1.1
| 段 | 这一格写什么 | 写错的后果 |
|---|---|---|
| 方法 | GET POST PATCH DELETE OPTIONS HEAD |
方法不对,服务器直接 405 Method Not Allowed |
| 目标 | 路径 + 查询串:/api/notes?tag=js |
少一个前缀就是 404;查询串写错就是"筛出来是空的" |
| 版本 | HTTP/1.1(现在也有 HTTP/2、HTTP/3) |
手写时基本不出错,抓包时要注意:HTTP/2 是二进制帧,看不到这种明文 |
注意"目标"里不包含域名。域名在 Host 头里——这样一台服务器(一个 IP)才能按域名分派出几十个网站。
八个关键头,各管一件事
| 头 | 谁发 | 管什么 | 缺了/写错会怎样 |
|---|---|---|---|
Host |
请求 | 我要访问哪个域名 | 同一 IP 多站点时会打错站;HTTP/1.1 里它是必填 |
Content-Type |
双方 | 体是什么格式 | 发 JSON 却没声明,后端按表单解析 → 422 |
Content-Length |
双方 | 体有多少字节 | 少了,对方不知道读到哪算完,可能一直等 |
Accept |
请求 | 我能接受什么格式 | 只是偏好,服务器可以不理(5.1 已验证) |
Authorization |
请求 | 我是谁(令牌) | 缺了 → 401;写错前缀 → 同样 401 |
User-Agent |
请求 | 我是什么客户端 | 缺了会被某些防护当机器人;排查时它是"谁发来的"唯一线索 |
Cache-Control |
双方 | 这份东西能不能存、存多久 | 写错会让用户看到旧数据,或每次都在重新下载 |
Set-Cookie |
响应 | 让浏览器存一个凭据 | 卷 6 的登录全靠它,HttpOnly/SameSite 都在这里 |
Host 与 Content-Length 有一个共同点:它们是" framing "头——决定"这段话在哪结束"。所以中间层(代理、网关)改这两个头,比改别的危险得多。
响应行:状态码 + 原因短语
HTTP/1.1 404 Not Found
原因短语是给人看的,可以自定义,程序只认数字。这也是为什么同一件事你能看到两种写法:422 Unprocessable Entity(旧叫法)和 422 Unprocessable Content(新叫法,本书实测的服务器就用这个)。别在代码里匹配短语。
Content-Type:一个分号救活一堆中文
Content-Type: application/json
Content-Type: text/html; charset=utf-8
Content-Type: application/x-www-form-urlencoded
Content-Type: multipart/form-data; boundary=----abc123
| 类型 | 用在哪 | 要不要 charset |
|---|---|---|
application/json |
API 的请求体和响应体 | 不要写。JSON 规范规定必须是 UTF-8,写了也不会改变什么 |
text/html |
网页 | 要写,否则浏览器可能按本地编码猜,中文变乱码 |
text/plain |
纯文本、调试输出 | 建议写 |
application/x-www-form-urlencoded |
传统表单 a=1&b=2 |
一般不用 |
multipart/form-data |
带文件的表单 | 靠 boundary 分段,一定有 boundary= |
这里有个新手必踩的坑,实测给你看:
curl -X POST http://127.0.0.1:8000/api/notes -d 'title=x&content=y'
curl 的 -d 会自动加上 Content-Type: application/x-www-form-urlencoded。于是后端收到的是表单,不是 JSON,返回:
{"error":{"code":"validation_error","message":"请求数据未通过校验",
"fields":[{"field":"","message":"Input should be a valid dictionary or object to extract fields from"}]}}
field 是空字符串,因为校验器连"哪个字段"都定位不到——它拿到的根本不是对象。看到 422 且 field 为空,先查 Content-Type。
长度:Content-Length 数的是字节
「读到」的列表里只有一条中文摘录时,实测响应头是:
Content-Type: application/json; charset=utf-8
Content-Length: 181
而这段 JSON 的字符数远不到 181。差在哪?一个汉字在 UTF-8 里占 3 个字节。
| 概念 | 单位 | 谁在用 |
|---|---|---|
| 字符数 | 个 | 你在编辑器里看到的、数据库的 VARCHAR(120) |
| 字节数 | byte | Content-Length、网络传输、磁盘占用 |
这条区别会直接咬人:按"字符"去校验长度、按"字节"去限制请求体大小,两边永远对不上。限制请求体大小时留出 3 倍余量。
还有一种情况是没有 Content-Length:
Transfer-Encoding: chunked
意思是"我不知道总共多长,边算边发,每段前面标长度"。动态生成的页面、流式响应都用它。看到 chunked 不要慌,它和 Content-Length 是二选一的关系。
GET 不该有体,POST 才有
规范没禁止 GET 带体,但实际工程里它几乎一定会丢:
| 环节 | 对 GET 的体做了什么 |
|---|---|
浏览器 fetch |
直接报错:Request with GET/HEAD method cannot have body |
| 缓存 | 只按 URL 做键,体不参与,于是"不同请求命中同一份缓存" |
| 代理/网关 | 很多实现直接丢弃 |
| 日志 | 一般只记 URL,体不留痕,出事无法复现 |
所以规则很简单:要传数据,用 POST/PATCH;要筛选,用查询串。 你在 curl -X GET -d '...' 里能成功,是因为 curl 真的把体发出去了、后端也真的没读——它是"发出去了但没人理",不是"支持"。
同名头:有的能合并,有的不能
一个响应里可以出现多个同名的头,但处理规则不同:
| 头 | 能不能合并成一行 | 合并的后果 |
|---|---|---|
Set-Cookie |
不能,必须一行一个 | 只保住最后一个 cookie,其他全丢 |
Cache-Control |
能,逗号分隔 | 取并集,一般安全 |
Accept |
能,逗号分隔 | 正常 |
Content-Length |
不能,且不该重复 | 两个不同值时,代理和后端可能各认一个(请求走私的经典入口) |
Set-Cookie 那条是实战高发区:卷 6 会同时下发"会话 cookie"和"偏好 cookie",如果你用某个中间件把它们拼成一行,浏览器只会存下一个,表现为"登录了但一刷新就退出"。
HEAD:只要头,不要体
curl -I https://example.com 用的是 HEAD 方法。它和 GET 完全一样,只是服务器不返回体。
| 用途 | 为什么用 HEAD 而不是 GET |
|---|---|
| 检查链接是否还有效 | 省掉下载几百 KB 的流量 |
| 看文件大小、修改时间 | 这些信息在头里(Content-Length、Last-Modified) |
| 探活 | 监控每分钟打一次,不想拉全量内容 |
反过来也要注意:不是所有服务器都正确实现 HEAD。有些框架会真的执行一遍业务逻辑再把体丢掉,于是"探活请求"也查了一次数据库。自己写接口时如果用了 @app.get,FastAPI 会自动响应 HEAD,行为是"执行完再丢弃",量大了要考虑成本。
curl -v 的符号表
* 连接层信息(DNS、TCP、TLS)
> 你发出去的
< 你收到的
{ } 传输统计
看到 > 和 < 就够用了:一个是你写的,一个是对方回的。中间没有 > 也没有 < 的行是 curl 自己的碎碎念,比如 Windows 上的 schannel: ...(TLS 后端),可以忽略。
curl 与 F12 是同一件事的两种皮肤
| 报文里的 | 浏览器 F12 里 | 注意 |
|---|---|---|
| 请求行的方法 | Network → 列表的 Method 列 | 预检请求也会出现,方法写 OPTIONS |
| 请求行的路径 | General → Request URL | F12 显示完整 URL(带域名),报文里只有路径 |
| 请求头 | Request Headers | 浏览器会自动加 Origin、Referer、Sec-*,curl 不会 |
| 请求体 | Payload / Request Payload | 表单和 JSON 在这里长得不一样 |
| 状态行 | General → Status Code | 悬停可看原因短语 |
| 响应头 | Response Headers | 有时要看 "Raw",才能看到重复的头 |
| 响应体 | Response / Preview | Preview 是格式化后的,排错请看 Response 原文 |
最后一行是本节的实操建议:Preview 会骗你。它会把 HTML 渲染出来、把 JSON 折叠起来,于是"返回了错误页"看起来像"页面正常"。看原文。
5.2.3 动手:抓一次完整报文并逐行标注
curl -v https://example.com -o /dev/null
-o /dev/null 是把体丢掉,只留过程。形如(Windows 上的输出,* 行有删减):
* Host example.com:443 was resolved.
* IPv4: 104.20.23.154
* Trying 104.20.23.154:443...
* ALPN: curl offers http/1.1
* ALPN: server accepted http/1.1
* using HTTP/1.x
> GET / HTTP/1.1
> Host: example.com
> User-Agent: curl/8.21.0
> Accept: */*
>
* Request completely sent off
< HTTP/1.1 200 OK
< Content-Type: text/html; charset=utf-8
< Transfer-Encoding: chunked
< Connection: keep-alive
< Accept-Ranges: bytes
<
{ [584 bytes data] }
* Connection #0 to host example.com:443 left intact
逐行对照:
| 行 | 属于 | 读法 |
|---|---|---|
ALPN: server accepted http/1.1 |
TLS 协商 | 双方谈好了用哪个版本的 HTTP;谈不拢就是协议错误 |
> GET / HTTP/1.1 |
请求行 | 要根路径,用 GET |
> Host: example.com |
请求头 | 这一行决定"访问哪个站",缺了会 400 |
> User-Agent: curl/8.21.0 |
请求头 | 服务端日志里"谁来过"就靠它 |
> Accept: */* |
请求头 | 什么格式都行,所以服务器给了 HTML |
>(单个) |
空行 | 请求头结束,后面本该是体;GET 没有体,所以紧接着就发完了 |
< HTTP/1.1 200 OK |
状态行 | 成功 |
< Transfer-Encoding: chunked |
响应头 | 没有长度,边发边算 |
<(单个) |
空行 | 响应头结束,后面是体 |
{ [584 bytes data] } |
统计 | curl 告诉你收了多少字节 |
现在把同样的报文和 F12 对一遍,你会发现自己以前"看 Network"其实只看了一个状态码。头里的信息量是状态码的十倍。
5.2.4 三个坑
坑一:-d 没配 -H,JSON 变成表单
症状:用 curl 测新增接口,明明写的是 JSON 字符串,却收到 422,而且 fields 里的 field 是空字符串。
成因:curl -d 默认发送 Content-Type: application/x-www-form-urlencoded。后端按表单解析,拿到的不是对象,校验器无法定位字段。
修法:显式声明类型,两个参数一个都不能少:
curl -X POST http://127.0.0.1:8000/api/notes \
-H "Content-Type: application/json" \
-d '{"title":"闭包","content":"函数记住它的词法环境"}'
这个坑之所以高频,是因为它不报"类型错误",只报"数据不对"——你的注意力会被引到字段内容上,而问题在头里。
坑二:charset 不一致,中文变问号
症状:接口返回的中文在浏览器里是 æ£æ–‡ 或 ???;同一个接口在 curl 里正常。
成因:响应头写的是 charset=iso-8859-1(或根本没写),浏览器按猜的编码解码 UTF-8 字节。字节没错,解码错了。
修法:JSON 一律 application/json(规范即 UTF-8,不要加 charset);HTML 一律 text/html; charset=utf-8;文件读写显式 encoding="utf-8",不要依赖系统默认(Windows 默认不是 UTF-8)。判断口诀:乱码永远是"编码/解码"不匹配,不是"数据坏了"。
坑三:F12 里只有 Provisional headers are shown
症状:Network 里那条请求点开,请求头显示 Provisional headers are shown,没有响应,也没有状态码。
成因:这条请求根本没有真正发出去。常见于:被浏览器扩展拦了、命中了内存缓存、被 CORS 预检挡住、页面在请求发出前就跳走了。它的意思是"这些头是从代码里读出来的,不是我抓到的"。
修法:先别改后端。① 勾上 "Disable cache" 重试;② 开无痕窗口(排除扩展);③ 看 Console 有没有 CORS 或混合内容报错;④ 用同样的 URL 跑一次 curl——curl 能通、浏览器不通,问题就在浏览器这一侧(CORS、凭据、扩展)。这条分流能省掉大量"后端明明没问题"的争论。
本章验收
- 能默写请求行三段、响应行三段,并说出
Host为什么必填 - 能用
curl -v抓一次请求,并指出>与<分别是哪一侧 - 知道
Content-Length数的是字节,并能解释中文为什么"字符少、字节多" - 能说出
application/json不需要 charset 的原因 - 遇到
Provisional headers are shown时,知道先排除浏览器侧而不是改后端
自测
Q1:接口返回 200,但前端 res.json() 抛 Unexpected token '<'。最可能的三个原因是什么?
看答案
① 路径没打到后端,被前端服务器(开发服务器或 Nginx 的 try_files)接住并返回了首页 HTML;② 后端某个错误页/登录页拦截了请求并返回 HTML;③ 请求被代理转发到了一个静态站点。三者共同点是"状态码 200 + 内容是 HTML",所以第一动作不是改代码,而是看 Response 原文和 `Content-Type`。只要 `Content-Type` 是 `text/html`,就说明你拿到的根本不是接口响应。Q2:为什么给 application/json 加 charset=utf-8 没有意义?
看答案
因为 JSON 的规范已经规定文本必须是 UTF-8,解析器不需要、也不应该靠 `charset` 参数来决定编码。加了不会出错,但会产生一种危险的错觉——以为改了它就能解决乱码。真正的乱码来源通常是:数据库连接编码、文件读写没指定 `encoding`、或者中间层把响应重新编码了。要查的是这三处,不是响应头。Q3:一个 POST 请求的 Content-Length: 181,但前端说"我只发了 60 个字符"。谁错了?
看答案
都没错。`Content-Length` 计的是 UTF-8 编码后的字节数,一个汉字占 3 字节,60 个汉字加 JSON 的引号、冒号、括号正好能到 181 左右。这个差异在限制请求体大小时必须考虑:如果按"字符"设定 1MB 上限,实际可能要放行 3MB 的字节。反过来,如果你在中间层(Nginx、网关)设了 body 大小限制,用户传一篇长中文摘录会比预期更早被拒。下一步
报文会读了,接下来要有东西可发请求。在装任何框架之前,先把 Python 的环境隔离做对——否则你后面每一章都会在"这个包装到哪去了"上耗时间。