**这是本文档旧的修订版!**
请求头(HTTP Request Headers)
一个 HTTP 请求(Request)由四部分组成:请求行、请求头、一个空行、请求体。请求头是夹在请求行和请求体之间的若干行 键: 值,用来描述「这次请求的元信息」——找哪台服务器、我是谁、我从哪个应用来、我带的body是什么格式。
下面用一个「创建订单」类接口做示例。出于安全,域名、令牌、应用标识一律用占位符代替(<访问令牌>、<子应用标识> 这类值属于敏感信息,不该出现在任何文档里):
POST /api/orders/create HTTP/1.1 ← 请求行:方法 + 路径 + 协议版本
Host: api.example.com ← 请求头开始
Authorization: Bearer <访问令牌>
X-App-Id: <子应用标识>
Content-Type: application/json ← 描述请求体的格式
{ "skuId": 1001, "qty": 2 } ← 空行之后是请求体
| 组成 | 作用 | 备注 |
|---|---|---|
| 请求行 | 方法 + 路径 + 协议版本 | 不是请求头,第一行 |
| 请求头 | 键: 值,逐行排列 | 大小写不敏感,顺序不保证 |
| 空行 | 分隔「头」与「体」 | 必须有,少了会被当成坏请求 |
| 请求体 | 真正要发送的数据 | GET 一般没有;POST / PUT 常有 |
一、先拆请求行
示例的第一行不是头,而是请求行,三部分用空格隔开:
POST—— 方法。语义是「提交/创建」,通常会改变服务端状态,因此不该被缓存、不该被随意重放。/api/orders/create—— 路径(含查询串)。只写资源路径,不写协议和域名;域名由下面Host头负责。HTTP/1.1—— 协议版本。它决定了这条报文长什么样,也决定了Host是不是必填。(HTTP/2 里这一行不再明文出现,见第四节。)
二、逐个头拆解
Host: <主站域名>
HTTP/1.1 起唯一被强制要求的请求头。
- 作用:一个 IP 上可能跑着很多站点(虚拟主机),服务端靠
Host决定把这次请求交给哪个网站/哪个后端。 - 写法:只写主机名,可选端口;不写
http:、不写路径。 <code> Host: api.example.com Host: api.example.com:8443 非默认端口才写端口 </code> * 顺带记住:浏览器的同源判定、Cookie 的作用域都和它相关;反向代理、CDN 回源也常常按Host路由(见 回源)。 * 排错价值:明明接口是对的却 404,第一件事就是看Host有没有被上游代理改写。 ==== Authorization: Bearer <访问令牌> ==== 这是认证凭证的标准位置,语法固定为<方案名> <凭证>。 *Bearer是方案名,后面是一枚不透明令牌(JWT、OAuth2 access token 等)——“不透明”的意思是服务端不靠语法解析它,而是直接拿去验签/查库,且谁拿到都能用,等同于密码。 * 必须走 HTTPS;Basic只是 base64 编码而非加密,明文传输等于把密码广播出去。 * 绝不要放进 URL 的 query(会进浏览器历史、Referer、服务器日志,等于到处留副本),只能走请求头。 * 一个请求只用一种方案;确需多种凭证时用自定义头(如X-Api-Key)分开承载。 * 详解见 Authorization 与 Bearer。 ==== X-App-Id: <子应用标识> ==== 这是自定义头(非标准头),用来告诉服务端「这次请求来自哪个子应用/租户」。 ^ 头 ^ 回答的问题 ^ 谁提供 ^ |Authorization| 你是哪个用户,凭证有效吗 | 登录后由服务端签发 | |X-App-Id| 你从哪个应用/入口进来 | 由调用方固定带上 | *X-前缀是老约定,表示「厂商自定义扩展」。现在规范上已不推荐新头再用X-,但存量系统里到处都是。 * 与Authorization是分工关系:一个回答“哪个用户”,一个回答“哪个应用”。两者组合,服务端才能判断「这个用户在这个子应用下能做什么」。 * 重要:客户端可以随意伪造X-App-Id,所以服务端不能只凭它做权限判定,必须与令牌里的应用标识(app/aud/iss等字段)交叉校验,否则就是越权漏洞。 * 常见的同类头:X-Request-Id(链路追踪)、X-Forwarded-For(客户端 IP)、X-Trace-Id、X-Idempotency-Key(幂等)。 * 头名大小写不敏感(x-app-id等价),但约定俗成写成X-App-Id。 ==== Content-Type: application/json ==== 它描述的是请求体的媒体类型——“我发给你的数据是什么格式”,与请求头本身无关。 * 值的形式是type/subtype,可带参数(charset、boundary等)。 * 服务端常据此选择解析器:值写错、或与实际 body 不一致,就会得到 400(解析失败)或 415(不支持的媒体类型)。 * 别和Accept混:Accept是“我希望响应是什么格式”,Content-Type是“我发给你的是什么格式”。 ^ Content-Type ^ 典型场景 ^ |application/json| 前后端 JSON 接口,最常见 | |application/x-www-form-urlencoded| 传统表单提交 | |multipart/form-data| 含文件上传的表单 | |text/plain| 纯文本 | |application/xml| 老式 XML 接口 | ===== 三、还有哪些常见头 ===== ^ 头 ^ 作用 ^ |Accept| 能接受的响应格式,如application/json| |User-Agent| 客户端标识(浏览器、SDK 版本) | |Content-Length| 请求体字节数;与Transfer-Encoding互斥 | |Cookie| 浏览器自动携带的会话凭证(见 Cookie) | |Origin/Referer| 请求来源,跨域与 CSRF 校验看它(见 CSRF) | |Accept-Encoding| 允许的压缩算法,如gzip, br| ===== 四、HTTP/2、HTTP/3 里的差异 ===== 抓包或看日志时,看到的是\:method这种带冒号的头,不要慌,这是同一套东西:HTTP/2 把请求行拆成了伪头(pseudo-header)。 *POST→:method;/api/orders/create→:path;http/https→:scheme;Host→:authority。 * HTTP/2 中头名必须小写(content-type);HTTP/1.1 则大小写不敏感。 * 头会经过 HPACK 压缩,因此同一连接上的重复头在流量里看起来“不见了”是正常的。 * 伪头必须出现在所有普通头之前,且不能自己手写发送。 ===== 五、代理链路中被“加”上的头 ===== 经过 Nginx、网关、CDN 之后,请求头往往已经不是你发出去的那一份了: ^ 头 ^ 含义 ^ 注意 ^ |X-Forwarded-For| 原始客户端 IP(逐级追加) | 可伪造,只信最外层代理重置的值 | |X-Forwarded-Proto| 原始协议(http/https) | 用于生成回调地址、强制跳转 | |X-Real-IP| 单个客户端 IP(Nginx 约定) | 与上面含义重叠,取值口径要统一 | |X-Request-Id| 全链路追踪 ID | 建议入口生成、透传到底 | |Via| 经过的代理列表 | 排链路问题时有用 | 通用原则:所有X-Forwarded-(见 安全头) | | 重复下单 | 是否漏了类头默认都不可信,只有「你信任的那层代理」写入的才作数;服务端要覆盖而不是追加不可信来源的值。 ===== 六、联调排错清单 ===== ^ 现象 ^ 先看哪个头 ^ | 401 未认证 |Authorization是否带了、scheme 拼写对不对、令牌是否过期 | | 403 无权限 | 凭证有效但权限不足;核对X-App-Id与令牌里的应用标识是否一致 | | 400 / 415 |Content-Type与实际 body 是否匹配 | | 404 / 走错站点 |Host是否被代理改写,路径是否带上了 base path | | 跨域失败 |Origin,以及服务端的Access-Control-Allow-X-Idempotency-Key一类的幂等头 | ===== 七、写请求头的通用规则 ===== * 头名大小写不敏感,取值可能大小写敏感(如Bearer与bearer等价,但令牌本身一个字符都不能错)。 * 不要依赖头的顺序;同名头重复出现时,多数头应等价于逗号合并,少数头(如Set-Cookie)例外。 * 不要自造会与标准冲突的头名;自定义头优先用X-前缀或自有的命名空间。 * 敏感头必须脱敏:Authorization、Cookie、X-Api-Key默认不得全量落日志。 * 头过长会被拒:服务端可能回 431 Request Header Fields Too Large。 * 凭证类头只在 HTTPS 上传,这是所有规则里最不能省的一条。 ===== 八、一句话总结 ===== > 请求头就是这次请求的说明书:请求行说“要做什么”,Host说“找哪台服务器”,Authorization说“我是谁”,X-App-Id说“我从哪个应用来”,Content-Type说“我带了什么格式的数据”。 参考: * RFC 9110 —— HTTP Semantics(字段与语义总纲) * RFC 9113 —— HTTP/2 中的伪头与头压缩 * MDN —— HTTP 头字段列表 相关:Authorization · Bearer · JWT · 安全头 · GET_PUT_POST · 回源 · Cookie —- 返回:首页