HTTP 缓存与 CDN 加速实践:API 响应由谁缓存、缓存多久、怎么失效
面向 API 的 HTTP 缓存与 CDN 实践:区分浏览器私有缓存与 CDN 共享缓存,用 Cache-Control 逐条声明可缓存性与有效期,用 ETag/Last-Modified 把重复回源变成 304 校验,并说明缓存键与 Vary 的常见误配、变更发布时的顺序,以及哪些响应不应进入共享缓存。协议语义是公开标准,具体 CDN 的缓存键规则、刷新接口与命中率收益需按各自文档和自身流量核实。
- 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。
五、变更发布时的顺序#
- 静态资源用内容哈希命名,先发布新文件,再更新引用它的页面或配置。
- 接口响应结构变化优先用版本路径(如
/v1/→/v2/)承载,而不是依赖发布瞬间全量刷新边缘缓存。 - 确实需要主动失效时,把刷新当作“兜底手段”而非唯一手段,并为其传播时延留出窗口。刷新接口的能力与生效范围以服务商文档为准,待核实。
六、哪些响应不该进入共享缓存#
- 带
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 按内容协商需要收敛,涉及用户身份的响应一律不进共享缓存。至于命中率能提升多少、边缘节点能把延迟降到什么水平,取决于你的流量结构与节点分布,必须用自己的测量得出——本文不提供这类数字。