跳到正文
零到全栈 · 卷 5 · 后端与 API

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 的环境隔离做对——否则你后面每一章都会在"这个包装到哪去了"上耗时间。

→ 卷5-03-Python与虚拟环境.md