内容协商 · XB 现场笔记

Accept 系列头让服务器协商应答

Tue, 23 Nov 2027 00:00:00 +0000

内容协商是在服务器能够实际生成的表示之间进行选择。请求偏好只是选择的输入，并不能证明响应已经满足这些偏好，客户端仍需检查收到的表示。Vary 记录影响复用的请求维度，不负责命名最后选中的格式、语言或压缩方式。把选择输入与响应结果混为一谈，会让排查从一开始就看错字段。

分开看待不同维度

请求偏好	所选表示的响应元数据
Accept	Content-Type
Accept-Language	Content-Language
Accept-Encoding	实际施加内容编码时的 Content-Encoding

这些维度相互独立，请求 JSON 不等于请求英文或 gzip。Content-Language 描述内容所面向受众的语言，不保证每个字符都属于某一种语言。如果服务器只有英文 HTML 和中文 JSON，不能把分别算出的“最优格式”和“最优语言”拼成根本不存在的中文 HTML。应先列清实际可用的完整组合，再定义选择规则；偏好不能凭空增加服务端的生成能力。

质量值范围是零到一，省略时为一，最多允许三位小数。零表示不可接受，不是“稍微不喜欢”。对媒体类型，一个候选的质量值由匹配它的最具体范围决定。显式的 text/html;q=0 不会被更宽泛的 */*;q=1 解禁。如果只是找整串字段里最大的数字，或者拿逗号前第一项，就会丢掉“哪个范围约束哪个候选”的关系，得到看似按权重处理、实际上违反排除条件的结果。

坏掉的样子

缺失某个偏好字段通常表示在该维度上没有偏好，并不等同于显式拒绝。RFC 9110 允许服务器在没有可接受表示时返回 406，也允许忽略该字段，因此默认响应可能仍然无法被客户端使用。承诺严格协商的 API 必须自己明确这项策略。客户端可以表达排除条件，却不能仅靠发出这个字段，强迫所有现网服务器都执行严格拒绝逻辑。

各类字段还存在不同的匹配语义。Accept 使用媒体范围，语言协商需要约定语言标签匹配方式，Accept-Encoding 则有 identity、字段缺失和空值的专门规则。通用列表解析器不会自动补齐所有业务策略。特别是不能把缺失字段悄悄变成一个空集合，再推导出“客户端拒绝一切”。应用选择默认值与解析器返回没有匹配项，是两个需要明确区分的事实。

相同权重也没有一条跨所有服务器通用的顺序规则。应用应让并列时的选择可预测，并实际测试。完整的语言偏好还可能帮助识别用户，因此记录全部偏好档案、把所有可能字段都放进 Vary，并非天然合理。Vary 只处理匹配问题，缓存资格、新鲜度和授权边界仍需各自的规则，不能因为增加了这个字段就认定内容可以共享。

快速验证

准备 Python 3.11 或更新版本及 POSIX shell，在临时环境安装本次验证的解析器，再用 "$accept_lab/venv/bin/python" 运行 Python 代码。安装需要外网，实验本身不发请求、不启动服务器。它验证的是 Werkzeug 3.1.8 的候选选择行为，不是假装复现任意浏览器或 CDN 的完整实现。

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

from werkzeug.datastructures import Accept, LanguageAccept, MIMEAccept
from werkzeug.http import parse_accept_header

offers = ["text/html", "application/json"]
cases = [
 (None, "text/html"),
 ("", None),
 ("application/json;q=0.9, text/html;q=0.2", "application/json"),
 ("text/*;q=0.9, text/html;q=0, application/json;q=0.5", "application/json"),
 ("application/json;q=0, text/*;q=0.4, */*;q=1", "text/html"),
 ("application/xml", None),
 ("*/*;q=0", None),
]
for header, expected in cases:
 parsed = parse_accept_header(header, MIMEAccept)
 selected = offers[0] if header is None else parsed.best_match(offers)
 assert selected == expected
 print(repr(header), "->", selected)

denied = parse_accept_header("text/html;q=0, */*;q=1", MIMEAccept)
assert denied.quality("text/html") == 0
assert denied.quality("application/json") == 1
print("specific exclusion:", denied.quality("text/html"), denied.quality("application/json"))

tied = parse_accept_header("application/json, text/html", MIMEAccept)
assert tied.best_match(offers) == "text/html"
assert tied.best_match(list(reversed(offers))) == "application/json"
print("tie: server offer order decides")

languages = parse_accept_header("fr;q=1, zh;q=0.8, en;q=0.5", LanguageAccept)
codings = parse_accept_header("gzip;q=0, br;q=1", Accept)
assert languages.best_match(["en", "zh"]) == "zh"
assert codings.best_match(["gzip", "br"]) == "br"
print("independent axes:", languages.best_match(["en", "zh"]), codings.best_match(["gzip", "br"]))

前七次媒体选择依次得到 HTML、无匹配、JSON、JSON、HTML、无匹配、无匹配。缺失字段时使用 HTML，是调用方明确设定的默认策略；显式为空的 Accept 字段则不采用这个默认值。两个带排除条件的例子说明，更宽泛的范围不会覆盖具体候选的质量值。不提供的 XML 与全体质量值为零都会得到 None；把这个结果转换成 HTTP 406 是端点的职责，不是解析器直接发送了一次错误响应。

并列测试保持请求不变，只反转服务器提供的候选顺序。Werkzeug 在质量值和具体程度都相同时按照这个顺序选择。最后两项分别选出中文和 Brotli，但没有创建它们与某种媒体类型组成的完整表示，也没有执行压缩。语言测试只使用直接标签，不验证地区语言回退；编码测试则刻意不实现 identity 或缺失字段语义。明确这些范围，才能避免从局部输出推导出未被测试的能力。

做真实集成时，应保留这些负向案例，并核对实际发出的请求、返回的元数据和正文。默认情况、受支持的替代项、显式排除项与不可用组合，都应经过真实部署路径测试，再决定哪些请求字段属于 Vary。解析器测试通过，只建立了一个有用的组件契约；它不能代替对整条协商与缓存链路的验收。

来源

RFC 9110：内容协商，字段缺失、质量值、各字段匹配方式与 Vary，已核验 2026-09-07。
Werkzeug Accept 数据结构，具体程度、质量值与并列处理，已核验 2026-09-07。
Werkzeug 头字段解析，解析器与不同字段对应的类型，已核验 2026-09-07。

Accept 与 Vary 让一个 URL 回应多种格式

Tue, 19 Jan 2027 00:00:00 +0000

同一个资源可以同时提供面向读者的 HTML 视图和面向程序的 JSON 表示。共用 URL 的前提是源站与中间层始终保留这种区别。端点需要选择可用格式、正确序列化、说明缓存变化维度，并验证本次选中的表示，而不是拿同一资源的另一种版本来代替它。单一地址不会自动完成这些工作。

先选择，再序列化与验证

对于 GET 响应，请求中的 Accept 表达希望接收哪些媒体类型，请求中的 Content-Type 则描述请求内容本身。把后者写成 JSON，并不等于要求服务器返回 JSON。质量值与通配符匹配应交给框架已有的媒体范围解析器。应用还需要分别规定：没有 Accept 时默认返回什么，以及字段存在却匹配不到任何可用表示时如何处理。

下面的端点只在 Accept 缺失时默认选择 HTML。如果客户端明确表达的偏好没有可接受候选，就返回 406，并列出可用类型。这是一项刻意选择的接口策略，因为 HTTP 也允许忽略偏好。不要把它换成 415，后者针对的是请求内容格式不受支持。分清错误方向，客户端才能知道应该修改希望接收的类型，还是自己发送的正文及其声明。

完成选择后，Content-Type 应由实际使用的序列化方式确定。HTML 中插入数据需要适当转义，JSON 则应通过 JSON 序列化器生成，而不是塞进 HTML 模板。该路由的各类表示，包括默认表示，都需要 Vary: Accept。但 Vary 不授予存储资格，也不保护个人信息；实验中的公开缓存指令只适用于这份对所有调用者完全相同、没有敏感信息的固定状态记录，不能直接复制到账户接口。

坏掉的样子

只测源站，可能看不出缓存正在把之前的 HTML 发给现在的 JSON 请求。需要通过完整交付路径检查响应头和解析后的正文，并交换请求顺序。新响应补上正确的 Vary，不会自动修复此前已经缓存、却缺失选择元数据的条目。应使用受控测试地址或已获批准的失效流程，不要为了验证一个端点而随意清空共享缓存。

更隐蔽的问题是把数据库记录的版本号直接作为两种格式共同的强 ETag。ETag 识别的是所选表示，不同的 HTML 与 JSON 字节不能仅因为描述同一条记录，就共用这个强验证器。如果先处理条件请求、后选择格式，就可能对客户端根本没有的表示错误返回 304。正确顺序是先选择、序列化、计算该表示的标记，再判断条件是否成立。资源内容相同与表示字节相同，不是一个概念。

快速验证

使用 Python 3.11 或更新版本建立以下临时环境，然后用 "$media_lab/venv/bin/python" 运行 Python 代码。程序在自动分配的回环端口启动 Werkzeug 开发服务器，完成后关闭服务器与连接。只有安装依赖需要联网，六次测试请求都留在本机。这是协议实验，不是生产 WSGI 部署，也没有假装验证真实共享缓存的配置。

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

import hashlib
import html
import json
from http.client import HTTPConnection
from threading import Thread

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

record = {"message": "ready"}
variants = {
 "text/html": f"<!doctype html><p>{html.escape(record['message'])}</p>\n".encode(),
 "application/json": json.dumps(record).encode("utf-8"),
}


@Request.application
def application(request):
 if request.path != "/status":
 return Response("not found\n", status=404)
 if request.method != "GET":
 return Response("GET only\n", status=405, headers={"Allow": "GET"})
 media = "text/html" if "Accept" not in request.headers else (
 request.accept_mimetypes.best_match(variants)
 )
 if media is None:
 response = Response("available: text/html, application/json\n", status=406)
 response.headers["Cache-Control"] = "no-store"
 else:
 body = variants[media]
 response = Response(body, mimetype=media)
 response.set_etag(hashlib.sha256(body).hexdigest())
 response.headers["Cache-Control"] = "public, max-age=60"
 response.make_conditional(request)
 response.vary.add("Accept")
 return response


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


def get(accept=None, etag=None):
 headers = {}
 if accept is not None:
 headers["Accept"] = accept
 if etag is not None:
 headers["If-None-Match"] = etag
 connection = HTTPConnection("127.0.0.1", server.server_port, timeout=3)
 try:
 connection.request("GET", "/status", headers=headers)
 response = connection.getresponse()
 body = response.read()
 assert response.headers["Vary"] == "Accept"
 print(accept, "->", response.status, "bytes=", len(body))
 return response.status, response.headers, body
 finally:
 connection.close()


try:
 status, html_headers, body = get()
 assert status == 200 and body == variants["text/html"]
 assert html_headers.get_content_type() == "text/html"
 status, json_headers, body = get("application/json")
 assert status == 200 and json.loads(body) == record
 assert json_headers.get_content_type() == "application/json"
 assert html_headers["ETag"] != json_headers["ETag"]
 status, _, body = get("application/json", json_headers["ETag"])
 assert status == 304 and body == b""
 status, _, body = get("text/html", json_headers["ETag"])
 assert status == 200 and body == variants["text/html"]
 for accept in ["application/xml", "*/*;q=0"]:
 status, headers, _ = get(accept)
 assert status == 406 and headers["Cache-Control"] == "no-store"
finally:
 server.shutdown()
 server.server_close()
 worker.join()

预期状态码依次为 200、200、304、200、406、406。前两次以不同格式返回同一状态信息，程序同时检查正文、媒体类型以及两个强 ETag 确实不同。第三次重新验证 JSON，得到不携带正文的 304。第四次携带 JSON 的标记，却明确请求 HTML，因此必须得到完整 HTML 与 200。这是只验证“两种格式都能正常打开”时最容易遗漏的负向检查。

最后两次分别请求服务器没有提供的 XML，以及明确排除全部媒体类型，都会触发本例选定的拒绝策略。错误响应使用 no-store，避免把这类实验错误交给缓存保存。每个测试响应都断言存在 Vary，包括 304。解析和条件响应处理复用 Werkzeug，而不是自己拆分头字段语法或手写实体标记比较规则；实验成功只证明所覆盖的调用路径，不能推导出未测试客户端都正确处理这些响应。

采用这项设计之前，应确认两种序列化结果属于同一个资源契约，并能一起测试。如果调用者、访问权限或发布时间存在实质差异，独立 URL 可能更容易维护。不要因为地址统一就把不同的授权规则合并。不论最终采用哪种寻址方案，都应把正文验证与跨表示验证器检查保留在集成测试中，防止以后修改序列化方式时重新引入错误复用。

来源

RFC 9110：HTTP 语义，Accept、ETag、If-None-Match 以及 406 与 415 的区别，已核验 2026-09-07。
RFC 9111：Vary 匹配，缓存复用之前的请求匹配，已核验 2026-09-07。
Werkzeug 条件响应，响应验证器与条件正文处理，已核验 2026-09-07。

内容协商 · XB 现场笔记

Accept 系列头让服务器协商应答

分开看待不同维度

坏掉的样子

快速验证

延伸阅读

来源

Accept 与 Vary 让一个 URL 回应多种格式

先选择，再序列化与验证

坏掉的样子

快速验证

延伸阅读

来源