Caching · XB 现场笔记

缓存头是和浏览器的一份双向契约

Wed, 15 Jul 2026 00:00:00 +0000

源站定义存储和新鲜度策略，缓存判断已保存的响应是否能满足下一次请求。无法直接复用时，验证器可以降低检查成本。这是几个相互独立的决定：在一次成功响应中找到 Cache-Control 和 ETag，并不能证明下一次请求会按预期执行。验收必须沿着重复请求继续观察，才能区分直接命中、成功验证和完整替换。

验证器检查已存表示是否仍然匹配。304 更新元数据，而缓存保留已有正文。

允许谁复用、可复用多久

private 把存储范围限制到单用户缓存，public 在其他条件允许时明确授予缓存许可。max-age 提供新鲜度寿命，s-maxage 则为共享缓存覆盖这个值。no-cache 允许保存，但要求每次复用前成功验证；no-store 禁止 HTTP 缓存存储，并不管住所有应用日志或用户保存的文件。这些指令都不能替代授权检查和传输安全，不能因为缓存头正确就省略访问控制。

对于带内容指纹的资源，如果字节变化一定带来新网址，public, max-age=31536000, immutable 可以是合理策略。这里的时长是一年，不是一个月。稳定网址下会变化的文档，应按更新要求选择策略：短寿命搭配验证器，允许有界的直接复用；no-cache 则要求后续每次 HTTP 缓存复用都先验证。两者的网络请求成本和可见更新延迟并不一样。

验证器回答另一个问题

客户端可以在 If-None-Match 中带回 ETag。条件 GET 的标签匹配时得到不含正文的 304；标签不匹配时，通常得到包含当前表示的 200。If-None-Match 使用弱比较，因此弱标签同样可以用于缓存验证。Last-Modified 支持 If-Modified-Since，但秒级时间戳可能遗漏快速连续变化。请求中只要存在 If-None-Match，就忽略 If-Modified-Since，而不是等标签匹配失败后再用日期兜底。

收到适用的 304 后，缓存保留原有正文，并依照缓存规则更新元数据。对于对应的 200 本来会发送的 Date、ETag、Cache-Control 等字段，源站在 304 中也有相应发送要求。一个只负责下载响应的程序，不会因此自动具备完整缓存能力；如果把 304 的空内容直接当作新的文档覆盖旧正文，反而会丢掉真正要使用的内容。

坏掉的样子

正文已经发生有意义的变化，ETag 却永远不变，可能错误确认旧副本。相反，相同正文每次都生成新标签，会导致本可避免的完整传输。两种缺陷都必须通过重复请求才能识别。强标签需要区分不同表示数据，包括不同内容编码的变体；对实际字节计算哈希是一种实现方法，但客户端应把标签当作不透明值，不必把哈希算法当成公共接口。

修改源站策略不能召回已经新鲜、暂时没有理由再联系源站的缓存副本。同样，个人 JSON 上的短有效期也不能隔离用户，缓存键与账户切换必须另外测试。浏览器历史恢复和应用自行管理的缓存是额外机制，因此 HTTP 测试通过，不代表当前显示的页面一定立即刷新。应把验证结论限定到实际观察过的交互路径。

快速验证

准备 Python 3.11 或更新版本及 POSIX shell。安装 Werkzeug 3.1.8 后，用 "$validation_lab/venv/bin/python" 执行 Python 代码。它在自动分配的回环端口启动开发服务器，结束后关闭服务和线程。安装需要网络，七次请求都只访问本机。这是源站协议测试，不是生产部署方案，也不是浏览器缓存模拟器。

validation_lab=$(mktemp -d)
python3 -m venv "$validation_lab/venv"
"$validation_lab/venv/bin/python" -m pip install Werkzeug==3.1.8

import hashlib
from datetime import datetime, timezone
from http.client import HTTPConnection
from threading import Thread

from werkzeug.serving import make_server
from werkzeug.wrappers import Request, Response

state = {"body": b"release A\n", "modified": datetime(2026, 1, 1, tzinfo=timezone.utc)}
directive = "public, max-age=0, must-revalidate"


@Request.application
def application(request):
 if request.path != "/document":
 return Response("not found\n", status=404)
 if request.method != "GET":
 return Response("GET only\n", status=405, headers={"Allow": "GET"})
 body = state["body"]
 response = Response(body, mimetype="text/plain")
 response.headers["Cache-Control"] = directive
 response.set_etag(hashlib.sha256(body).hexdigest())
 response.last_modified = state["modified"]
 return response.make_conditional(request)


server = make_server("127.0.0.1", 0, application)
worker = Thread(target=server.serve_forever)
worker.start()


def get(headers=None):
 connection = HTTPConnection("127.0.0.1", server.server_port, timeout=3)
 try:
 connection.request("GET", "/document", headers=headers or {})
 response = connection.getresponse()
 body = response.read()
 assert response.headers["Cache-Control"] == directive
 assert response.headers["ETag"] and response.headers["Date"]
 print(response.status, "bytes:", len(body))
 return response.status, response.headers, body
 finally:
 connection.close()


try:
 status, first, body = get()
 assert status == 200 and body == b"release A\n"
 status, headers, body = get({"If-None-Match": first["ETag"]})
 assert status == 304 and body == b"" and headers["ETag"] == first["ETag"]
 status, _, body = get({"If-None-Match": '"different"',
 "If-Modified-Since": first["Last-Modified"]})
 assert status == 200 and body == b"release A\n"
 status, _, body = get({"If-None-Match": "W/" + first["ETag"]})
 assert status == 304 and body == b""
 state.update(body=b"release B\n", modified=datetime(2026, 1, 2, tzinfo=timezone.utc))
 status, second, body = get({"If-None-Match": first["ETag"]})
 assert status == 200 and body == b"release B\n"
 assert second["ETag"] != first["ETag"]
 status, _, body = get({"If-None-Match": second["ETag"]})
 assert status == 304 and body == b""
 status, _, body = get({"If-Modified-Since": second["Last-Modified"]})
 assert status == 304 and body == b""
finally:
 server.shutdown()
 server.server_close()
 worker.join()

预期状态依次是 200、304、200、304、200、304、304。每次 200 携带十字节正文，每次 304 都没有正文。冲突验证器请求虽然日期匹配，仍返回 200，符合实体标签在这组条件下的优先规则；本例没有执行相反的条件组合。弱形式的标签仍能验证未变的表示。A 与 B 的正文长度相同，变更测试还排除了只拿长度当验证器的错误实现。

最后两次分别使用 B 的新 ETag 和单独的 Last-Modified 进行验证。程序在全部响应中检查 Cache-Control、Date 和 ETag。max-age 为零并配合 must-revalidate，允许存储但在过期后要求先成功验证；这不会让 Python 的 HTTP 客户端自动缓存。每次请求都是程序明确构造的，条件解析和实际发出响应时的正文抑制则由 Werkzeug 处理。

部署测试应保留正文变更和验证器冲突案例。检查真正的 GET 响应，而不只看 HEAD，还应确认中间层没有破坏所选表示对应的验证器。合格结果既包括未变时避免传输，也包括内容确实改变时完整替换。只统计 304 越多越好，会漏掉错误验证器把旧内容持续确认成有效副本的风险。

来源

RFC 9111：缓存验证，存储正文复用与元数据更新，已核验 2026-09-07。
RFC 9110：条件请求，实体标签比较与前置条件优先级，已核验 2026-09-07。
MDN：Cache-Control，存储指令和按资源设定新鲜度，已核验 2026-09-07。
Werkzeug 条件响应，实际测试的响应接口与正文处理，已核验 2026-09-07。

验证器决定缓存副本是否仍是答案

Tue, 30 Jun 2026 00:00:00 +0000

缓存可以询问已存储的副本是否仍可使用，而不必每次重新下载正文。它发送验证器；匹配的条件 GET 可以收到 304 Not Modified，表示变化时通常需要新的 200 响应。验证是在命中时省下正文，并非每次请求都省下。

标签仅为示意；假定请求原本成功。GET/HEAD 使用弱比较；HEAD 无正文。匹配既不证明字节相同，也不证明新鲜度。其他方法通常返回 412；If-Range 不能使用弱 ETag。

验证器类型与强度是两回事

ETag 是带双引号的不透明值，可以是强标签（"release-a"），也可以明确标记为弱标签（W/"release-a"）。强比较要求两者都为强标签且值相等；弱比较忽略 W/ 标记，只比较不透明值。即使字节不同，弱标签也可以描述语义等价。

Last-Modified 是 HTTP 日期中精确到秒的时间戳。通常它是弱验证器，除非满足 RFC 9110 第 8.8.2.2 节的条件、可认定为强验证器。不能把所有 ETag 都归为强验证器，也不能无条件把所有时间戳归为弱验证器。

先前的站点观察记录了：

etag: "dkx84jwth7nkc9e"
last-modified: Mon, 24 Aug 2026 13:55:23 GMT

这些是历史值；这里未保留原始响应日志，本轮审阅也未重新检查在线结果。Caddy 文件服务器通常会设置这两个字段，但仍取决于文件元数据与配置。

条件 GET 使用弱比较

把收到的 ETag 原样放进 If-None-Match，保留双引号与可能存在的 W/。原笔记针对上述值报告过 HTTP 304，但展示的请求值没有双引号；该请求文本不符合实体标签语法，不应当作可工作的探针照抄。测试在线端点前应取得当前验证器。

下面无需套接字的练习，展示对单个、已解析标签的比较；它不是完整的 HTTP 头部解析器：

def weak_value(tag):
 return tag[2:] if tag.startswith('W/') else tag

def strong_equal(a, b):
 return not a.startswith('W/') and not b.startswith('W/') and a == b

stored = 'W/"release-a"'
current = '"release-a"'
assert weak_value(stored) == weak_value(current)
assert not strong_equal(stored, current)
assert weak_value(stored) != weak_value('"release-b"')
print("weak match: True; strong match: False; changed tag: no match")

对原本会成功的 GET 或 HEAD，If-None-Match 匹配时返回无正文的 304。其他方法上的同一前置条件为假时，通常返回 412 Precondition Failed。若同时存在 If-None-Match 与 If-Modified-Since，ETag 条件优先。通过 If-Range 做字节范围验证时，不能使用弱 ETag。

重新发布时不要保留误导性的验证器

ETag 不一定是内容哈希。Caddy v2.10.2 的默认文件标签由修改时间与大小生成；替换字节时若两者都保持不变，标签也可能不变。检查实际部署版本与覆盖配置，再让发布流程更新验证器依赖的输入，或采用基于内容的版本标识。

在发布清单中保留字节校验和，并测试未变化与已变化两种响应。校验和不会自动成为服务器的 ETag。304 还需要适用的缓存元数据，让缓存更新已存储的响应；它不只是一个空的成功状态。

来源

RFC 9110 — HTTP Semantics，第 8.8 与 13 节的验证器强度及前置条件，已核验 2026-10-15。
RFC 9111 — HTTP Caching，第 4.3 节的验证与已存储响应更新，已核验 2026-10-15。
MDN: HTTP 条件请求，条件请求概览，已核验 2026-10-15。
Caddy v2.10.2 文件服务器源码，calculateEtag 的输入与默认响应字段，已核验 2026-10-15。

缓存头是两套时钟的契约

Thu, 25 Jun 2026 00:00:00 +0000

缓存不是一个单一开关。一个响应既有一个由缓存作出的新鲜度决策，也有与源站之间的校验对话。把这两种想法混在一起，会得到陈旧内容或多余请求。

存储、新鲜度与校验是不同问题。根据 URL 的变更方式选择策略，完整保留验证器，并检查共享缓存的变体。

先选变更模型

对于发布之后可能变化的 HTML 文档，Cache-Control: no-cache 通常比 no-store 更接近正确起点。no-cache 允许存储，但要求缓存复用前先校验；no-store 则要求缓存完全不存储。当你想要条件请求与廉价的 304 Not Modified 时，这个区别很关键。

对类似 app.4f2c.js 这种带指纹的资源，URL 在字节变化时也随之改变，此时一个较长的新鲜度生命周期是合理的：

Cache-Control: public, max-age=31536000, immutable

但对一个内容可能被原地替换的稳定 URL，该策略不安全。如果 URL 稳定，应优先使用较短的生命周期，并搭配实体标签（ETag）或有意义的 Last-Modified 值。

除了新鲜期，还要决定谁可以存储响应。如果共享缓存不能保存面向特定用户的内容，应使用不带参数的 private 指令；浏览器的私有缓存仍可存储。单独使用 no-cache 不提供这项限制。上面的 public 示例适用于可以在用户之间共享的资源，不是个性化响应的默认策略。

同时检查两条路径

发一次普通请求，再发一次条件请求。各服务器的具体标志可能不同，但你想要的证据是稳定的：

curl -sS -D - -o /dev/null https://www.example.test/
curl -sS -D - -o /dev/null \
 -H 'If-None-Match: "copy-a-real-etag-from-the-first-response"' \
 https://www.example.test/

不要在 runbook 里粘贴编造的验证器。从第一次响应里复制该值，或使用测试夹具。对这里的条件 GET，If-None-Match 匹配时可以通过弱比较返回 304：它允许语义等价，并不一定保证字节完全相同。验证器变化时通常返回新的 200 响应。保留 ETag 的双引号与可能存在的 W/ 前缀。

让中间层可见

Age、Vary 与 cache-control 指令说明了为什么两个客户端可能得到不同结果。如果响应随 Accept-Encoding、语言或其他请求字段变化，该维度应进入 Vary；否则共享缓存可能复用错误的表示。

有意义的发布检查不是"扫描器找到了缓存头"，而是"该头与替换策略匹配，且条件请求的行为符合文档说明"。

immutable 只在声明的新鲜期内生效，并非永久禁止重校验。版本化 URL 的内容应保持不变，只要旧 HTML 仍可能引用旧资源，就应让它们继续可访问。今天修改响应头不会追溯缩短既有缓存响应的寿命；缓存策略出错时，可能需要新 URL 或缓存系统明确支持的清除操作。

来源

RFC 9111 — HTTP Caching，第 4–5 节，已核验 2026-10-15。
RFC 9110 — HTTP Semantics，第 8 与 13 节，已核验 2026-10-15。
MDN: Cache-Control，指令语义与默认值，已核验 2026-10-15。
RFC 8246 — 不可变响应，immutable 仅在新鲜期内生效，已核验 2026-10-15。