技术文章

外部链接将在新标签页打开。

HTTP 缓存与 CDN 加速实践:API 响应由谁缓存、缓存多久、怎么失效

一句话回答

面向 API 的 HTTP 缓存与 CDN 实践:区分浏览器私有缓存与 CDN 共享缓存,用 Cache-Control 逐条声明可缓存性与有效期,用 ETag/Last-Modified 把重复回源变成 304 校验,并说明缓存键与 Vary 的常见误配、变更发布时的顺序,以及哪些响应不应进入共享缓存。协议语义是公开标准,具体 CDN 的缓存键规则、刷新接口与命中率收益需按各自文档和自身流量核实。

核心要点 TL;DR
  • API 缓存的第一步不是调 TTL,而是逐条声明:默认不共享缓存,只对确定可共享的响应开放。
  • Cache-Control 决定能不能存、存多久,ETag 决定重复请求能否用 304 代替完整响应。
  • 缓存键与 Vary 决定命中率也决定串号风险;按用户区分的响应应走 private 而不是共享缓存。
  • 本文不含任何实测数据:命中率与延迟收益必须用自己的流量测量。

给 API 加缓存,实际要回答三个问题:这份响应能不能被存、能存多久、内容变了怎么让它失效。HTTP 缓存负责把这三件事写成标准头字段,CDN 负责把可缓存的副本放到离调用方更近的节点上。对 API 来说,难点通常不在协议,而在默认值:多数接口返回的是按用户区分的、随时会变的数据,所以更稳妥的起点是“默认不共享缓存,逐条显式开放”,而不是先给所有 GET 接口加一个 max-age。

下文只讨论协议层面的通用语义(HTTP 缓存语义由 RFC 9111 定义)与工程上常见的配置方式。具体 CDN 的缓存键规则、刷新接口、命中率统计口径属于各服务商能力,这里不代为断言,需按其文档与自身流量核实。

一、先分清是谁在缓存#

同一个响应头,对不同缓存角色含义不同。至少要把三类分开看:浏览器里的私有缓存、CDN 边缘节点上的共享缓存、以及源站或应用层的缓存。

  • private:只允许浏览器这类私有缓存存储,共享缓存必须跳过。按用户返回的数据应该用它。
  • public:显式允许共享缓存存储。只有确认“同一 URL 对所有调用方返回同样内容”时才该加。
  • no-store:任何缓存都不得存储,适合含令牌、个人数据的响应。
  • no-cache:可以存,但每次使用前必须校验。它不等于“不缓存”,这是最常见的误解之一。

二、用 Cache-Control 表达有效期#

指令主要作用对象典型用途
max-age=N私有缓存与共享缓存声明响应在 N 秒内可直接复用
s-maxage=N共享缓存给 CDN 单独设 TTL,浏览器侧沿用 max-age
no-cache所有缓存必须校验后才可用,配合 ETag
no-store所有缓存敏感响应,不留副本
must-revalidate所有缓存过期后不得返回陈旧副本
stale-while-revalidate=N支持该扩展的缓存后台刷新期间先返回陈旧内容;是否支持以缓存实现为准,待核实

实践上常把“公开数据”和“用户数据”分成两套默认头:前者给较短的 s-maxage 加 stale-while-revalidate,后者固定 private 或 no-store。这样新增接口时不必逐个回忆规则。

三、条件请求:把重复回源变成 304#

有效期解决的是“这段时间内不用问源站”,校验解决的是“过期了但内容没变,能不能只回一个空响应”。源站在响应里给出 ETag 或 Last-Modified,缓存或客户端下次带上 If-None-Match 或 If-Modified-Since,源站内容未变则返回 304 Not Modified,不带响应体。

两个容易踩的点:一是 ETag 里混入了实例 ID、时间戳或随机数,导致每次校验都不相等,304 永远不会发生;二是弱校验(W/ 前缀)只保证语义等价而非字节一致,用在校验场景是合适的,但不要拿它做断点续传一类需要字节级一致的事情。304 响应本身也应带上 Cache-Control 与 ETag,否则缓存无法更新自己的有效期。

四、缓存键与 Vary:决定命中率,也决定会不会串号#

CDN 判断“这是不是同一个资源”,靠的是缓存键;而缓存键通常由请求方法、主机、路径、查询串等组合而成,具体包含哪些部分、查询参数是否排序,各服务商规则不同,需核实。这意味着 ?a=1&b=2 与 ?b=2&a=1 在某些实现下是两份缓存,会显著拉低命中率。

Vary 则声明“同一 URL 还需按哪些请求头分版本”。需要注意:

  • Vary: * 等价于告诉缓存无法区分版本,实际效果接近不可缓存。
  • 对内容协商场景,按 Accept、Accept-Encoding 区分是合理的。
  • 不要把按用户返回的数据交给共享缓存去按 Authorization 分版本:一旦键设计出错,代价是跨用户返回他人数据,属于安全边界问题,而不是命中率问题。这类响应应直接标 private。

五、变更发布时的顺序#

  1. 静态资源用内容哈希命名,先发布新文件,再更新引用它的页面或配置。
  2. 接口响应结构变化优先用版本路径(如 /v1/ → /v2/)承载,而不是依赖发布瞬间全量刷新边缘缓存。
  3. 确实需要主动失效时,把刷新当作“兜底手段”而非唯一手段,并为其传播时延留出窗口。刷新接口的能力与生效范围以服务商文档为准,待核实。

六、哪些响应不该进入共享缓存#

  • 带 Set-Cookie 的响应;即使共享缓存通常会跳过,也应显式写 no-store。
  • 包含访问令牌、个人身份信息的响应。
  • 错误响应:500、429 若无显式短 TTL,被缓存后会把一次故障放大成一段时间内的持续故障。
  • 按用户区分、但误标为 public 的响应。

七、检查步骤(示例未执行)#

# 占位示例域名,未实际执行;仅说明应观察哪些响应头
curl -sI "https://example.com/api/v1/items?page=1"

重点看四项:Cache-Control 里 private 与 public 谁在生效,最大值是多少;ETag 是否稳定;Age 是否在增长(说明命中了共享缓存);Vary 是否列出了预期之外的头。诊断缓存是否命中的自定义头(常见如 X-Cache)命名各家不同,需查对应文档。上述命令为未执行的示例,预期输出不作为实际结果。

结论#

API 缓存的可靠性来自显式声明:共享缓存默认关闭,只对确定可共享的响应开放;有效期与校验器分开配置,让过期后的请求走 304 而不是完整回源;缓存键与 Vary 按内容协商需要收敛,涉及用户身份的响应一律不进共享缓存。至于命中率能提升多少、边缘节点能把延迟降到什么水平,取决于你的流量结构与节点分布,必须用自己的测量得出——本文不提供这类数字。

常见问题(FAQ)

no-cache 和 no-store 有什么区别?
no-store 要求缓存完全不存储该响应;no-cache 允许存储,但每次使用前必须向源站或上游校验。想禁止留存敏感数据用 no-store,想保证内容最新但允许省流量用 no-cache 加校验器。
加了 max-age,CDN 为什么还可能回源?
常见原因有三类:响应带 private 或 Set-Cookie 被共享缓存排除;缓存键因查询串顺序、Vary 头不同而未命中;缓存实现不支持某些扩展指令。具体判定需查看该 CDN 的缓存键规则与响应头诊断字段,命名各家不同,待核实。

作者:沐小悠

本文约 7 分钟读完 · 关键词:HTTP 缓存、CDN 加速、Cache-Control、ETag、条件请求

更多文章 GET 示例接口

「」标签下的其他文章