页面已经发布新版本,部分客户端却仍显示旧内容;或者接口每次都返回200,明明发送了 ETag,响应体仍然重复传输。这两类现象需要沿请求链核对:客户端是否发出请求、条件头是否到达源站、验证器是否随内容变化、代理是否改写了表示。

本文面向可缓存的公开配置与静态内容,建立一套可运行的协议实验及上线验收方法。Python仅用来构造本地HTTP实验,不讨论语言函数陷阱,也不把实验服务作为生产服务器。

先明确缓存合同

ETag标识选定表示的版本。它不是缓存有效期;即使源站生成了新ETag,仍处于新鲜期的客户端缓存也可能不发请求。因此,先决定允许多久看见旧内容,再选择策略。

响应策略 允许存储 后续使用条件 适用例子
Cache-Control: no-cache 允许 复用前成功验证 需要及时更新的公开配置
Cache-Control: public, max-age=300 允许 新鲜期可直接复用 允许短暂陈旧的公开资源
Cache-Control: no-store 不允许 不应作为后续响应缓存使用 含敏感数据的响应

这里的no-cache并不是禁止保存正文;它要求复用前验证。no-store也不是清除所有历史缓存的远程按钮。本文采用no-cache,主动观察每次验证。规则依据HTTP缓存规范 RFC 9111。

首次GET返回200、正文和ETag。下次GET携带If-None-Match,匹配时返回304,客户端使用原来保存的正文。304自身没有正文。GET与HEAD的If-None-Match使用弱比较,W/"abc"与"abc"可以匹配;非GET/HEAD的前置条件失败则涉及412,不能复用本文只读处理器。RFC 9110 条件请求定义了这些规则。

在回环地址运行协议实验

保存下面完整代码为etag_lab.py。需要Python 3.10以上及已有的HTTPX依赖;运行python etag_lab.py。服务只监听127.0.0.1,由操作系统分配端口,结束后关闭监听并回收线程。所有请求禁用环境代理,超时3秒,不访问外网。

实验只提供/config的GET和HEAD;固定JSON字节是公开演示数据。ETag从实际发送的字节计算。处理器仅接受本实验生成的64位十六进制标签、标签列表和星号,其他条件头返回400;它不是通用的HTTP实体标签解析库。

import hashlib
import re
from http.server import BaseHTTPRequestHandler, HTTPServer
from threading import Thread

import httpx


def run_lab() -> None:
    """运行隔离的HTTP条件请求验收,不使用真实业务数据。"""
    payload = b'{"version":1}\n'
    tag_pattern = re.compile(r'(?:W/)?"[0-9a-f]{64}"')

    class Handler(BaseHTTPRequestHandler):
        def log_message(self, format: str, *args: object) -> None:
            """实验不输出请求头与默认访问日志。"""

        def do_GET(self) -> None:
            """返回当前表示或条件验证结果。"""
            self.respond(is_head=False)

        def do_HEAD(self) -> None:
            """返回与GET相同的表示元数据,不发送正文。"""
            self.respond(is_head=True)

        def respond(self, is_head: bool) -> None:
            """先选定表示,再比较验证器,保证正文与标签一致。"""
            # HTTP状态行使用标准英文原因短语,中文说明放入UTF-8错误正文。
            if self.path != "/config":
                self.send_error(404, explain="资源不存在")
                return
            body = payload
            etag = '"' + hashlib.sha256(body).hexdigest() + '"'
            condition = self.headers.get("If-None-Match")
            is_match = False
            if condition is not None:
                if len(condition) > 4096:
                    self.send_error(400, explain="条件头过长")
                    return
                if condition.strip() == "*":
                    is_match = True
                else:
                    tags = [item.strip() for item in condition.split(",")]
                    if not all(tag_pattern.fullmatch(tag) for tag in tags):
                        self.send_error(400, explain="条件头格式错误")
                        return
                    is_match = any(tag.removeprefix("W/") == etag for tag in tags)
            self.send_response(304 if is_match else 200)
            self.send_header("ETag", etag)
            self.send_header("Cache-Control", "no-cache")
            if not is_match:
                self.send_header("Content-Type", "application/json")
                self.send_header("Content-Length", str(len(body)))
            self.end_headers()
            if not is_match and not is_head:
                self.wfile.write(body)

    server = HTTPServer(("127.0.0.1", 0), Handler)
    server.timeout = 3
    worker = Thread(target=server.serve_forever, daemon=True)
    worker.start()
    try:
        url = f"http://127.0.0.1:{server.server_port}/config"
        with httpx.Client(timeout=3, trust_env=False) as client:
            first = client.get(url)
            assert first.status_code == 200 and first.content == payload
            etag = first.headers["ETag"]
            other = '"' + "0" * 64 + '"'
            for condition in (etag, "W/" + etag, other + ", " + etag, "*"):
                response = client.get(url, headers={"If-None-Match": condition})
                assert response.status_code == 304 and response.content == b""
                assert response.headers["ETag"] == etag
                assert response.headers["Cache-Control"] == "no-cache"
            miss = client.get(url, headers={"If-None-Match": other})
            assert miss.status_code == 200 and miss.content == payload
            head = client.head(url)
            assert head.status_code == 200 and head.content == b""
            assert head.headers["Content-Length"] == str(len(payload))
            head_match = client.head(url, headers={"If-None-Match": etag})
            assert head_match.status_code == 304 and head_match.content == b""
            invalid = client.get(url, headers={"If-None-Match": "invalid"})
            assert invalid.status_code == 400
            oversized = client.get(url, headers={"If-None-Match": "x" * 4097})
            assert oversized.status_code == 400
            assert client.get(url + "/missing").status_code == 404
            payload = b'{"version":2}\n'
            changed = client.get(url, headers={"If-None-Match": etag})
            assert changed.status_code == 200 and changed.content == payload
            assert changed.headers["ETag"] != etag
            print("协议验收通过:首次获取、条件匹配、失败输入与内容更新")
    finally:
        server.shutdown()
        server.server_close()
        worker.join(timeout=5)
        if worker.is_alive():
            raise RuntimeError("实验服务线程未按期退出")


if __name__ == "__main__":
    run_lab()

代码对HEAD的200响应发送GET正文长度,但不发送正文;对304省略Content-Length,不把“没有正文”误写成所选表示长度为0。每次304都携带ETag和缓存策略,便于缓存更新已有元数据。BaseHTTPRequestHandler自动补充Date。服务为串行实验模型,变量更新发生在前一次请求完成之后;生产应使用框架和不可变表示快照,避免读正文与计算版本之间发生并发变化。

把请求矩阵迁移到真实入口

请求与前提 预期结果 不满足时优先检查
不带条件的首次GET 200、正文、ETag 应用是否生成验证器
原ETag再次GET 304、空正文 条件头是否转发、表示是否稳定
弱标签或列表中包含原标签 304 是否错误使用字符串整体相等
不匹配的标签 200与当前正文 是否无条件返回304
HEAD及匹配条件HEAD 200或304,均无正文 HEAD是否走了不同业务版本
更新正文后携带旧标签GET 200、新正文、新ETag 验证器是否固定、更新是否到达该副本

在测试环境分别通过源站和正式入口执行相同矩阵。路径、查询参数、Accept-Encoding和业务身份保持一致;如果要比较两次请求,必须确保选择的是同一种表示。记录状态码、ETag、Cache-Control、Age、Vary和正文摘要即可,避免记录完整敏感正文或鉴权头。

对真实服务,不应强制要求它使用SHA-256或64位标签;这是实验合同。验收器应原样保存服务返回的ETag,再回传,不能去掉引号,也不能自行把弱标签“升级”为强标签。

浏览器排查时先看请求是否真正发出。没有请求通常要检查新鲜度、Service Worker或应用自己的缓存;已经发送If-None-Match且得到304,则要核对相同请求条件下源站是否真的改变表示。浏览器可能把304与本地缓存合并后向应用提供正文,所以不能只通过前端读取到的最终对象判断网络响应体。

若仅正式入口异常,再检查代理缓存键、条件头转发与响应头改写。Age可帮助识别缓存响应,但没有Age不能证明请求一定直达源站。不要为了强制看到200就把所有资源长期改为no-store;先明确缓存层和允许陈旧的时间预算。

更新、压缩与多副本的边界

同一份内容应有稳定验证器,不要每次请求都用当前时间生成标签。反过来,内容改变必须改变验证器;只依赖秒级修改时间与文件大小,可能漏掉同秒等长替换。本文将正文从version 1改成等长的version 2,专门覆盖这种情况。

强ETag要求表示数据保持字节一致。如果中间层执行压缩或其他转换,应由明确负责表示的层生成或调整标签;需要按Accept-Encoding选择缓存变体时正确设置Vary,并测试压缩与未压缩两条路径。不能给不同编码的字节随意复用同一个强标签。多副本也必须对同一版本提供一致正文,否则标签会随负载均衡跳动。

对带身份的个性化内容,先处理缓存隔离与权限,再讨论304节省传输;不能直接沿用公开资源的public策略。If-None-Match与If-Modified-Since同时出现时,服务端应优先评估前者,本文实验没有实现日期验证器,也没有覆盖写入前置条件、Range与If-Range。

本次验证记录与上线门槛

本次从稿件提取完整代码,实际通过回环TCP发送HTTP请求,覆盖首次获取、四种匹配条件、不匹配、两种HEAD、非法与超长输入、路径不存在及等长内容更新。还将ETag计算故意固定为旧版本摘要,重新运行同一验收;内容更新检查必须失败,证明矩阵能发现“标签不变导致旧正文继续复用”的缺陷。

实验验证的是源站条件请求行为,没有实现浏览器缓存或共享缓存。未执行真实CDN、Nginx、TLS、压缩、多副本与性能测试;不能据此宣称线上缓存命中率或节省比例。上线门槛是部署环境按同一矩阵留存结果,并在修改缓存策略、压缩或发布方式后重新验收。若需要回滚,恢复原版本的正文与对应标签,另行处理已有缓存的新鲜期;撤销源站配置不会立即使客户端历史缓存失效。