API 设计 / 系统课时
使用 HTTP 缓存与 CDN
使用 HTTP 缓存与 CDN
HTTP 缓存能把部分 GraphQL 查询从应用服务器前移到浏览器或 CDN,但前提是请求可用 GET 表达,并且缓存键完整覆盖操作、变量与访问范围。本课给出一套可验证的响应头策略,并说明认证请求何时必须绕过共享缓存。
学习目标
- 能判断哪些 GraphQL 查询适合使用 GET 与共享 CDN 缓存
- 能正确设置
Cache-Control,区分浏览器缓存与共享缓存 - 能检查变量、认证与 CDN 缓存键,避免错误命中
先把可缓存请求变成安全的 GET
GraphQL 查询可以通过 HTTP GET 发送,而 mutation 不应通过 GET 执行。对 CDN 来说,GET 的完整 URL 天然适合作为缓存键的一部分,因此操作身份与变量必须稳定、完整地出现在 URL 中;如果查询文本过长,优先使用持久化操作或文档哈希减少 URL 体积。
变量放入查询字符串也意味着它们可能进入浏览器历史、代理日志和 CDN 日志,所以 秘密、令牌和敏感个人数据不应作为 GET 变量。这类请求应继续使用 POST,并按私有响应处理。

正确区分浏览器与共享缓存时间
Cache-Control 中的 max-age 面向所有遵循 HTTP 缓存语义的缓存;s-maxage 只用于共享缓存,通常可让 CDN 保存得比浏览器更久。匿名商品详情这类可公开复用的响应,可以采用短浏览器缓存、较长 CDN 缓存,并用 stale-while-revalidate 降低回源抖动。
Cache-Control: public, max-age=60, s-maxage=300, stale-while-revalidate=30这是响应头配置片段。它表示浏览器最多使用 60 秒的新鲜响应,共享缓存最多使用 300 秒;过期后的 30 秒窗口内,支持该指令的缓存可以先返回旧响应并异步重新验证。
对于个性化结果,最安全的默认值是阻止共享缓存:
Cache-Control: private, no-store这是响应头配置片段。private 表示响应不能存入共享缓存,no-store 进一步要求缓存不要存储该响应;如果业务确实需要浏览器私有缓存,可以去掉 no-store,改为明确的短 max-age。
用一次请求验证缓存语义
假设本地 GraphQL 服务已经支持一个匿名查询 Product,并对 GET 响应设置公共缓存头。下面的命令把操作与变量编码到查询字符串中,同时打印响应头。
curl -i --get 'http://localhost:<PORT>/graphql' \
--data-urlencode 'query=query Product($id: ID!) { product(id: $id) { id name } }' \
--data-urlencode 'operationName=Product' \
--data-urlencode 'variables={"id":"p-42"}'预期结果:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: public, max-age=60, s-maxage=300, stale-while-revalidate=30
{"data":{"product":{"id":"p-42","name":"Example"}}}<PORT> 与实际商品数据会因环境而不同。若同一 URL 连续请求时 CDN 已启用,还应通过 CDN 自带的命中标记或边缘日志确认第二次请求没有回到源站;不要假设某个供应商一定返回固定名称的 X-Cache 头。
把变量与身份纳入 CDN 缓存键
大多数 CDN 默认会以主机、路径和查询字符串构造缓存键,但平台可能配置成忽略某些参数或重新排序参数。GraphQL 场景必须确认 operationName、持久化操作 ID 和 variables 没有被错误丢弃,否则不同查询会映射到同一对象。
认证请求更危险。不要简单通过 Vary: Authorization 就宣布“可以安全共享缓存”:它会造成高基数碎片,而且不同 CDN 对带认证头请求的默认策略并不一致。更稳妥的做法是让带 Cookie 或 Authorization 的请求绕过共享缓存;只有在边缘层能够生成受信任、低基数的派生访问作用域,并且源站也按同一作用域授权时,才考虑共享。
选择失效方式而不是无限加长 TTL
CDN 擅长吸收高频只读流量,但 TTL 越长,数据更新后的陈旧窗口越大。适合的顺序通常是先给可接受的短 TTL,再根据业务需要增加缓存标签、surrogate key 或 URL 版本号做主动 purge;不要把“提高命中率”理解成无限增加 s-maxage。
最终验收应同时看两件事:相同匿名 GET 是否稳定命中边缘缓存,以及改变变量或身份后是否必然得到不同缓存对象。只有“该共享的能共享、不能共享的绝不串数据”,HTTP 缓存与 CDN 才真正改善吞吐和延迟。