3. HTTP 缓存机制：核心头与验证流程

在 OpenAPI 契约的缓存与权限验证场景中，HTTP 缓存机制是减少重复请求、降低后端负载、提升响应速度的关键技术。本节将系统讲解 Cache-Control、Expires、ETag / If-None-Match、Last-Modified / If-Modified-Since 四组核心头部的定义、优先级与协作流程。

3.1 缓存头部概览与优先级

HTTP 缓存头部按控制粒度分为“绝对过期”与“条件验证”两类。下表列出各头部的作用与优先级关系：

3.2 Cache-Control 与 Expires：过期控制

Cache-Control 是 HTTP/1.1 定义的缓存指令头部，支持多种指令组合：

• max-age=<seconds>：资源从生成时刻起可缓存的最大秒数。
• no-cache：每次使用前必须向源服务器验证资源是否过期。
• no-store：禁止任何缓存（包括代理和浏览器）。
• public / private：允许公共缓存或仅私有缓存。
• must-revalidate：过期后必须重新验证，不可直接使用。

Expires 是 HTTP/1.0 的绝对时间戳头部，格式为 Expires: Wed, 21 Oct 2025 07:28:00 GMT。当 Cache-Control 存在时，Expires 被忽略。

3.3 ETag 与 If-None-Match：强验证器

ETag（Entity Tag）是服务器为资源生成的唯一标识，通常为哈希值或版本号。客户端在后续请求中通过 If-None-Match 头部携带该值，服务器比较后返回：

• 304 Not Modified：资源未变更，客户端可继续使用本地缓存。
• 200 OK：资源已变更，返回新资源及新 ETag。

# 首次响应
HTTP/1.1 200 OK
ETag: "abc123def456"
Content-Type: application/json

# 后续请求
GET /openapi/v3/spec HTTP/1.1
If-None-Match: "abc123def456"

# 未变更响应
HTTP/1.1 304 Not Modified
ETag: "abc123def456"

3.4 Last-Modified 与 If-Modified-Since：弱验证器

Last-Modified 记录资源的最后修改时间，精度为秒。客户端通过 If-Modified-Since 携带该时间戳，服务器判断是否返回 304 或 200。

# 首次响应
HTTP/1.1 200 OK
Last-Modified: Tue, 15 Oct 2025 12:00:00 GMT

# 后续请求
GET /openapi/v3/spec HTTP/1.1
If-Modified-Since: Tue, 15 Oct 2025 12:00:00 GMT

# 未修改响应
HTTP/1.1 304 Not Modified

Last-Modified 的局限性：

• 精度仅到秒，毫秒级变更无法区分。
• 无法检测内容是否真正变化（如元数据修改但内容未变）。
• 建议与 ETag 配合使用，ETag 优先。

3.5 缓存验证流程（SVG 图）

下图展示客户端与服务器之间的完整缓存验证流程，涵盖强缓存与条件请求两条路径：

3.6 缓存头部在 OpenAPI 契约中的典型配置

以下是一个针对 OpenAPI 规范文档的缓存响应示例，展示如何组合使用各头部：

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: public, max-age=3600, must-revalidate
ETag: "d5e8c2a1b3f4"
Last-Modified: Mon, 14 Oct 2025 08:30:00 GMT
Expires: Mon, 14 Oct 2025 09:30:00 GMT

{
  "openapi": "3.1.0",
  "info": { "title": "用户服务 API", "version": "2.4.1" },
  "paths": { ... }
}

3.7 权限验证场景下的缓存策略

当 OpenAPI 端点需要权限验证时，缓存策略需谨慎设计：

3.8 小结