RESTful API 标准请求头完整参考文档
本文档汇总了 HTTP/1.1 及相关标准（RFC 7230-7235, RFC 6265 等）中定义的、在 RESTful API 实践中广泛使用的标准请求头。
这些头部可用于实现内容协商、认证授权、缓存控制、条件请求、跨域资源共享等核心功能。
一、内容协商（Content Negotiation）
内容协商允许客户端和服务端就响应格式达成一致。
| 请求头 | 示例值 | 类型 | 描述 |
|---|---|---|---|
Accept |
application/json, application/xml, text/html;q=0.9 |
媒体类型 | 告知服务端客户端能够理解的响应媒体类型。可使用 q 参数指定优先级（0~1）。 |
Accept-Charset |
utf-8, iso-8859-1 |
字符集 | 客户端期望的字符编码。 |
Accept-Encoding |
gzip, deflate, br |
压缩算法 | 客户端支持的响应内容压缩编码方式。 |
Accept-Language |
zh-CN, en;q=0.9, fr;q=0.8 |
语言标签 | 客户端期望的自然语言。 |
实践建议：
- REST API 通常至少支持 Accept: application/json 和 application/xml。
- 若服务端无法满足请求的 Accept，应返回 406 Not Acceptable。
二、认证与授权（Authentication & Authorization）
| 请求头 | 示例值 | 类型 | 描述 |
|---|---|---|---|
Authorization |
Bearer <token>Basic dXNlcjpwYXNz |
凭证字符串 | 向服务端提供身份凭证。最常见的是 Bearer Token（JWT）和 Basic 认证。 |
实践建议：
- 无状态 REST API 应优先使用 Authorization: Bearer <JWT>，避免使用 Cookie 携带会话 ID。
- 不要在 URL 中传递敏感凭证。
三、缓存控制（Caching & Conditional Requests）
这些头部用于管理客户端/代理缓存，并实现乐观锁。
| 请求头 | 示例值 | 描述 |
|---|---|---|
Cache-Control |
no-cache, max-age=0, only-if-cached |
指示缓存系统如何处理请求。 |
If-Match |
"etag123", "etag123", "etag456" |
条件请求：仅当资源的 ETag 与给定的值匹配时，才执行请求。常用于 PUT 更新时防止并发覆盖。 |
If-None-Match |
"etag123" |
条件请求：仅当资源的 ETag 不匹配时才执行。用于避免重复下载未修改的资源（配合 GET）。 |
If-Modified-Since |
Wed, 21 Oct 2024 07:28:00 GMT |
条件请求：若资源在指定时间之后未修改，则返回 304 Not Modified。 |
If-Unmodified-Since |
同 If-Modified-Since |
条件请求：仅当资源在指定时间之后未被修改才执行（常用于 PUT/DELETE 保证原子性）。 |
If-Range |
"etag123" 或 日期 |
与 Range 头一起使用，如果 ETag/日期匹配，则发送指定的范围；否则发送完整资源。 |
实践建议：
- 服务端应生成 ETag（通常为内容的哈希值）并通过 ETag 响应头返回。
- 更新资源时，要求客户端提供 If-Match 头，可有效防止并发更新冲突。
四、客户端信息与状态
| 请求头 | 示例值 | 描述 |
|---|---|---|
User-Agent |
Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ... |
标识发起请求的客户端应用程序、操作系统、版本等信息。 |
Cookie |
sessionId=abc123; theme=dark |
向服务端发送之前通过 Set-Cookie 响应头存储的键值对数据。 |
Referer |
https://example.com/page |
指示当前请求的来源页面 URL（常用于防盗链或统计分析）。 |
From |
user@example.com |
发起请求的用户邮件地址（较少使用）。 |
注意：
- 符合 REST 风格的无状态 API 应避免依赖 Cookie 进行会话管理，而是使用 Authorization 头。
- Referer 可能包含敏感信息，建议敏感 API 不依赖它做权限控制。
五、内容描述（Content Description）
用于描述请求体（通常在 POST, PUT, PATCH 请求中使用）。
| 请求头 | 示例值 | 描述 |
|---|---|---|
Content-Type |
application/json, multipart/form-data, application/x-www-form-urlencoded |
请求体中数据的媒体类型。 |
Content-Length |
348 |
请求体的大小（字节数）。对于分块传输编码（chunked）可省略。 |
Content-Encoding |
gzip, deflate |
请求体的压缩编码方式。客户端可以对请求体进行压缩并设置此头。 |
Content-Language |
en, zh |
请求体内容的自然语言。 |
Content-MD5 |
Q2hlY2sgSW50ZWdyaXR5IQ== |
请求体的 Base64 编码 MD5 摘要，用于接收端校验完整性。 |
Content-Disposition |
attachment; filename="file.pdf" |
指示如何处理响应体（例如作为附件下载）。在请求中较少见，但可用于上传文件时提供文件名。 |
Content-Range |
bytes 0-1023/2048 |
在部分请求（Partial Request）中使用，指示请求体的范围信息。 |
实践建议：
- REST API 通常约定 Content-Type: application/json 作为 JSON 格式的标识。
- 文件上传使用 multipart/form-data。
六、跨域资源共享（CORS）
浏览器在发起跨域请求时会自动或手动添加这些头部。
| 请求头 | 示例值 | 描述 |
|---|---|---|
Origin |
https://frontend.example.com |
浏览器自动添加，指示请求的来源域。 |
Access-Control-Request-Method |
DELETE |
在预检请求（OPTIONS）中使用，告知实际请求将使用的方法。 |
Access-Control-Request-Headers |
X-Custom-Header, Content-Type |
在预检请求中告知实际请求将携带的自定义头部。 |
实践建议：
- 服务端需正确响应 Access-Control-Allow-Origin 等 CORS 响应头。
- 对于简单请求（GET/HEAD/POST 且无自定义头），浏览器不会发送预检。
七、连接管理与协议升级
| 请求头 | 示例值 | 描述 |
|---|---|---|
Host |
api.example.com:8080 |
必须，指定被请求的服务器主机名和端口号（HTTP/1.1 强制）。 |
Connection |
keep-alive, close |
控制连接行为：keep-alive 复用连接，close 表示请求完成后关闭。 |
Upgrade |
websocket |
请求服务端切换到其他协议，例如从 HTTP 升级到 WebSocket。 |
TE |
trailers, gzip |
声明客户端能够处理的传输编码扩展（如分块尾部）。 |
Expect |
100-continue |
要求服务端在收到完整请求头后先返回 100 Continue 状态，再发送请求体（适用于大请求体）。 |
注意：
- Host 头是 HTTP/1.1 规范必需的，缺失会导致 400 Bad Request。
- 使用 Upgrade 头通常需配合 Connection: Upgrade。
八、安全与隐私相关
| 请求头 | 示例值 | 描述 |
|---|---|---|
X-Forwarded-For |
203.0.113.195, 198.51.100.178 |
标准事实，用于代理/负载均衡传递原始客户端 IP（非标准但普遍支持）。 |
X-Forwarded-Proto |
https |
指示原始请求使用的协议（http/https）。 |
X-Request-ID |
f47ac10b-58cc-4372-a567-0e02b2c3d479 |
非标准但广泛使用，用于关联客户端请求与后端日志，实现端到端追踪。 |
X-Correlation-ID |
同 X-Request-ID |
与 X-Request-ID 类似，用于分布式追踪。 |
实践建议：
- 建议 API 网关或客户端为每个请求生成唯一的 X-Request-ID，并在响应中以相同值返回。
- 使用 X-Forwarded-For 时需注意伪造风险，应仅信任可信代理。
九、分页与范围请求
| 请求头 | 示例值 | 描述 |
|---|---|---|
Range |
bytes=0-1023 |
请求资源的指定字节范围（用于断点续传、分块下载）。 |
Accept-Ranges |
bytes |
响应头，但可通过 Range 请求头触发；指示服务端支持的范围单位。 |
实践：
- 支持断点续传的 API 应正确处理 Range 头，返回 206 Partial Content。
- REST API 推荐使用查询参数 ?offset=10&limit=20 进行分页，而非 Range 头。
十、最佳实践总结
- 内容协商：优先使用
Accept和Content-Type，支持多种媒体格式。 - 无状态认证：使用
Authorization: Bearer <JWT>，避免 Cookie。 - 缓存与并发控制：服务端提供
ETag，客户端更新时携带If-Match。 - 唯一请求追踪：生成
X-Request-ID并记录于日志。 - 跨域支持：正确配置 CORS 响应头，预检请求须正确处理 OPTIONS。
- 连接管理：推荐
Connection: keep-alive提高性能。 - 安全头部（虽非请求头，但建议响应包含）:
Strict-Transport-Security,X-Content-Type-Options,Content-Security-Policy等。
附录：快速参考表
| 分类 | 请求头名称 |
|---|---|
| 内容协商 | Accept, Accept-Charset, Accept-Encoding, Accept-Language |
| 认证 | Authorization |
| 缓存/条件 | Cache-Control, If-Match, If-None-Match, If-Modified-Since, If-Unmodified-Since, If-Range |
| 客户端信息 | User-Agent, Cookie, Referer, From |
| 内容描述 | Content-Type, Content-Length, Content-Encoding, Content-Language, Content-MD5, Content-Disposition, Content-Range |
| CORS | Origin, Access-Control-Request-Method, Access-Control-Request-Headers |
| 连接/协议 | Host, Connection, Upgrade, TE, Expect |
| 追踪/代理 | X-Forwarded-For, X-Forwarded-Proto, X-Request-ID, X-Correlation-ID |
| 范围请求 | Range |
本文档基于 HTTP 规范及行业实践整理，可用于 API 设计、开发及文档沉淀。
最后更新：2025年（参考 RFC 7230-7235, RFC 6265, CORS 规范等）。
相关资源： - RFC 7230: HTTP/1.1 Message Syntax and Routing - RFC 7231: HTTP/1.1 Semantics and Content - RFC 7232: Conditional Requests - RFC 7235: Authentication - Fetch Standard (CORS)