开头(节选约300字)
最近帮同事排查一个接口报错,他把日志贴过来的时候我愣了一下:
cc switch local proxy failed while handling codex endpoint /responses. provider: deepseek; model: deepseek-v4-flash; upstream_status: http 400; cause: the reasoning_content in the thinking mode must be passed back to the api.
紧接着下面还有一条 502 Bad Gateway: unknown error, url: http://127.0.0.1:1572,以及一条 client.timeout exceeded while awaiting headers。
这串日志放在一起看,其实就是一个典型的 HTTP 协议现场:状态码、报文、代理、超时这几个概念全占齐了。很多人在网上搜“HTTP基础知识”的时候,往往只看得到请求响应的那张图,真到了分析实际问题的时候,却又不太记得怎么把这些知识点和具体报错联系起来。
所以这篇就用“HTTP深度解析”作为主线,把报文结构、状态码语义、连接管理、HTTPS、与 RPC 的区别、隧道与调试工具这几个方面串起来,最后再回到真实的故障排查。文章适合后端开发、全栈工程师,也适合正在做嵌入式联网(比如 STM32、ESP32 这类硬件要跑 HTTP 库)的朋友。我会尽量用实际场景来讲,而不是堆概念。
1. HTTP 的骨架:一次请求报文里到底写了什么
1.1 请求行的三个要素不能搞混
先看一段最常见的 HTTP 请求报文:
code复制POST /api/v1/login HTTP/1.1
Host: example.com
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
Accept: application/json
Content-Type: application/json
Content-Length: 42
{"username":"admin","password":"123456"}
第一行是请求行,拆开看是三个部分:方法、URL 路径、协议版本。
- 方法:GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS 等。语义上,GET 表示获取资源,POST 表示提交并创建资源,PUT 表示整体替换,PATCH 表示局部修改,DELETE 表示删除。
- 路径:是 /api/v1/login,而不是完整的 URL。完整的 URL 只在代理场景下才会出现在请求行里,这个细节后面讲隧道的时候会再提到。
- 协议版本:HTTP/1.1。这个版本号决定了连接默认是否是长连接,HTTP/1.1 默认 keep-alive,而 HTTP/1.0 默认是短连接,每次请求都要重新建立 TCP 连接。
很多新手写爬虫,或者用 curl 调试接口的时候,最容易犯的错是把路径写成了完整 URL,或者漏了 Host 头。在 HTTP/1.1 里,Host 头是强制要求的,因为同一个 IP 和端口下可以托管多个域名(虚拟主机),服务器必须靠 Host 头来区分你到底要访问哪个站点。
1.2 请求头是双方协商的“元信息”
请求头从请求行结束的换行之后开始,每一行都是 Key: Value 的格式,直到遇到一个空行。这里头有几个值得说下的关键字段:
Host:目标主机名和端口。Content-Type:告诉服务器请求体的格式。常见的有application/json、application/x-www-form-urlencoded、multipart/form-data。三者用法差异很大,POST 提交表单时如果格式不匹配,服务器端很容易解析出空数据。Content-Length:请求体的字节长度。如果这个值和实际发送的字节数不一致,服务器会一直等到超时才认为请求结束。Accept:客户端希望接收的格式。服务器可以不完全遵守,但这是一个协商信号。User-Agent:客户端的身份标识。很多后端会用它做简单的爬虫拦截。Cookie:无状态 HTTP 协议用来保持会话状态的机制,通常由服务器通过Set-Cookie下发。
1.3 响应报文的结构和请求是对称的
响应报文长这样:
code复制HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 19
Connection: keep-alive
{"code":0,"data":"ok"}
第一行是状态行,包含协议版本、状态码和原因短语。要注意的是,原因短语(比如 OK、Not Found)只是给人看的,客户端程序要判断结果必须看状态码,不要用原因短语做逻辑判断。
响应头里的 Content-Type 和 Content-Length 同样重要,浏览器就是靠这两个字段决定怎么渲染和判断 body 的边界。Transfer-Encoding: chunked 则是另一种编码方式,表示 body 以一系列分块发送,每个分块前面有十六进制长度,最后以空块结束。这种模式下就没有 Content-Length 了。
在嵌入式场景里(比如 STM32 跑的 HTTP 客户端库),很多实现只处理 `Content-Len
