API · 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。

Protobuf 兼容性会在 JSON 边界发生变化

Fri, 19 Nov 2027 00:00:00 +0000

一次 schema 变更可能适用于二进制消息，却不适用于同一服务的 JSON 网关。Protobuf 二进制格式按编号识别字段，ProtoJSON 通常暴露字段名称。因此应把生产方、消费方和中间转换组成兼容矩阵，而不是只给变更贴一个“向后兼容”的标签。编译成功，或两个端点互相读懂，并不能证明所有转发环节都保留了它们交换的信息。

新增字段是否安全，取决于表示形式

使用全新编号增加字段，通常属于二进制线上安全变更。旧解析器可以保留未知字段，同时继续读取熟悉的内容；新版解析器读取旧数据时，则得到相应默认值或缺失状态。缺失是否符合业务要求仍是另一项决定，不能在旧写方还无法提供新值时，就让新读方强制依赖它。格式接受能力与功能实施能力必须分开验收。

ProtoJSON 的规则不同。解析器默认拒绝未知字段，所以旧 JSON 消费方可能拒绝带有新增属性的消息。配置忽略未知字段，可以让解析继续，却不会为后续消费方保留被丢弃的信息。这是明确允许信息损失的策略，不是二进制未知字段转发的等价实现。应先确认新字段是否只是补充说明，还是会影响业务动作的必要输入。

保持编号而修改字段名，能很好地展示这个差别。二进制读方仍然可以按编号取得数值，但生成代码的访问器和默认 JSON 属性会变化，旧属性对新 JSON 解析器可能变成未知字段。json_name 选项同样参与这个契约。发布前应列出实际输出与接受的名称，而不是只比较编号表，便宣布改名完全没有代价。

跟踪中间转换，不只比较两个端点

旧消息对象能够在内部保留未知二进制数据，即便公开字段接口无法描述它们。把这个对象序列化成 JSON 时，只输出已知字段，未知信息就会丢失。遍历已知字段并填入一个新消息，也会产生类似损失。需要保留未知数据时，应优先使用面向整个消息的复制接口，并用测试明确验证保留结果，而不是依赖表面上相同的字段值。

这也不同于序列化字节稳定。等价消息在不同版本或实现间，不一定产生完全相同的二进制输出。比较时应检查所需值与存在状态，不应要求相同字段顺序，除非协议另外定义了规范表示。对重新序列化结果签名或计算身份摘要，需要单独、明确的规则；某一次小样本字节相等，并不能替所有版本建立这种规则。

字段编号退役后应永久保留，并把删除的名称加入 reserved，阻止 schema 中意外复用。但名称保留声明不会让运行时 JSON 解析器继续接受旧属性。deprecated 标记也不会自动删除字段，它更不会清除旧写方、已保存记录或下游依赖。真正删除之前，需要知道哪些对象还在使用它，以及怎样完成迁移。

坏掉的样子

网关可能接受一条新的二进制请求，经过旧 schema 的 JSON 对象再输出，从而悄悄抹掉新增指令。末端消费方仍可解析成功，却因缺失而进入默认分支。另一条路径则是严格旧 JSON 解析器直接拒绝整条消息。需要同时检查拒绝与静默省略，两者的运行症状不同，却可能来自同一个表示转换边界。

也要区分 schema 兼容与生成代码、运行时版本兼容。即便线上格式没有变化，新生成代码也可能要求受支持的特定运行时组合。应遵循供应方支持规则，并测试仍有意义的最老读方、延迟消息和回滚路径。几行把类型名称放进字典的自制检查器，不能证明真实解析器、代码生成或运行时的这些性质，更不能替代跨版本测试。

快速验证

准备 Python 和 Google 的 protobuf 7.36.2 包，然后运行完整程序。本次在 Python 3.12.14 上通过。独立描述符池为三套 schema 创建真实消息类，二进制与 JSON 都调用库本身的解析实现，不是手写序列化模型。实验不调用编译器，不启动服务，也不会发送网络请求，作用范围限定为本地运行时转换。

from google.protobuf import descriptor_pb2 as schema, descriptor_pool, message_factory, json_format


def message(fields):
 file = schema.FileDescriptorProto(name='probe.proto', package='probe', syntax='proto3')
 record = file.message_type.add(name='Record')
 for name, number, kind in fields:
 record.field.add(name=name, number=number, type=kind, label=1)
 pool = descriptor_pool.DescriptorPool()
 pool.Add(file)
 return message_factory.GetMessageClass(pool.FindMessageTypeByName('probe.Record'))


INT32 = schema.FieldDescriptorProto.TYPE_INT32
STRING = schema.FieldDescriptorProto.TYPE_STRING
Old = message([('id', 1, INT32)])
New = message([('id', 1, INT32), ('note', 2, STRING)])
Renamed = message([('event_id', 1, INT32)])
producer = New(id=7, note='retain me')
old_relay = Old.FromString(producer.SerializeToString())
assert New.FromString(old_relay.SerializeToString()).note == 'retain me'

# Known-field JSON serialization omits unknown binary fields.
relay_json = json_format.MessageToJson(old_relay)
through_json = json_format.Parse(relay_json, Old())
assert New.FromString(through_json.SerializeToString()).note == ''
print('binary relay keeps note; old-schema JSON relay drops it')

new_json = json_format.MessageToJson(producer)
try:
 json_format.Parse(new_json, Old())
except json_format.ParseError:
 pass
else:
 raise AssertionError('unknown JSON field was accepted by the strict old parser')
ignored = json_format.Parse(new_json, Old(), ignore_unknown_fields=True)
assert ignored.id == 7
assert New.FromString(ignored.SerializeToString()).note == ''
print('strict old JSON parser rejects new field; permissive parsing discards it')

assert Renamed.FromString(Old(id=7).SerializeToString()).event_id == 7
try:
 json_format.Parse(json_format.MessageToJson(Old(id=7)), Renamed())
except json_format.ParseError:
 pass
else:
 raise AssertionError('renamed JSON field unexpectedly accepted')
print('same-number rename reads binary but rejects the previous JSON name')

二进制转发保留 note，而同一个旧消息对象经过 JSON 后会丢掉它。用严格旧 schema 解析新版 JSON，会得到 ParseError；打开忽略未知字段后，已知编号能留下，但新说明仍然消失。最后，保持编号的改名能够继续读取二进制，却拒绝此前的 JSON 属性名称。这些结果分别验证保留、拒绝和省略，不能只把“程序没有报错”当成成功条件。

这些断言覆盖一个运行时中的特定 schema 版本，没有认证任意变更、gRPC 传输或所有语言的生成客户端。真正的发布门禁应换成实际 schema，并把必要语义值、依赖存在性的默认行为，以及生产环境每一种中间表示都加入同一张跨版本测试矩阵。只有转换路径也被验证，端点兼容才足以支撑发布判断。

来源

Protobuf：proto3 语言指南，二进制安全新增与未知字段保留，已核验 2026-10-15。
Protobuf：ProtoJSON，未知字段、属性名称与兼容性，已核验 2026-10-15。
Protobuf：序列化不是规范形式，确定性输出的限制，已核验 2026-10-15。
Protobuf：运行时版本保证，生成代码与运行时的受支持组合，已核验 2026-10-15。

幂等键是客户端的承诺

Wed, 20 Jan 2027 00:00:00 +0000

幂等键命名的是一次预期行动，不是一次网络投递尝试。服务支持这项契约时，客户端在结果不明确后重试同一个行动，应该继续发送同一个键。每次重试都生成新键，实际是在告诉服务器“这是另一次行动”，因此完全可能合理地产生第二份业务效果。客户端必须先把行动身份与尝试次数分开。

创建一次，在后续尝试中保留

在第一次发送之前生成键，并把它与操作参数、目标一起保存。如果后台任务可能在客户端重启后恢复，任务记录也需要保留这个身份。仅把键放在临时网络连接或一次调用栈中，无法可靠地把后续尝试关联回原来的意图，恢复程序也不应临时猜一个替代值。

真正的新行动应该使用新键，即使参数与之前的购买完全一样。仅用正文哈希无法区分“再买一次同样的东西”和“重试第一次购买”。键与请求指纹承担不同职责：键标记行动，指纹检查是否发生了不兼容的复用。把二者合并，既可能漏去重，也可能错误阻止合理的新操作。

键的格式和作用域应遵循服务提供方的契约。Stripe 建议使用 UUIDv4 等随机标识，并提醒不要把敏感数据放进键中。键不是认证凭据，拥有某个键也不能代替访问已存结果所需的授权。不要把 bearer 凭据、邮箱或个人信息塞进用于关联请求的标识。

接收方必须真正实现这份承诺

只加一个 Idempotency-Key 请求头，不会自动实现去重。服务端必须在明确契约下识别它，说明比较哪些参数、保留哪些结果、执行尚未完成时如何处理重复请求，以及记录会保存多久。这些都是服务行为，不能从客户端看见一个字段名就推断已经具备。

Stripe API v1 记录的是首次进入执行阶段的请求状态码与正文，包括 500 响应。如果参数验证失败，或与正在执行的请求发生冲突，而端点执行尚未开始，则不会保存对应幂等结果。因此，“重复请求必须等待第一份结果”并不是所有 API 都必须采用的通用规则，调用方要处理实际的在途冲突语义。

Stripe API v2 则可能继续尝试失败或部分失败的工作，并返回更新后的结果；不能把 v1 的原响应保存规则直接套到 v2。不同提供方也不保证逐字重放响应。EC2 文档说明，成功重试不会再次执行行动，但返回结果可以包含更新后的创建状态等信息。RFC 9110 定义的是预期效果；具体服务是否复用原始响应字节，是叠加在其上的另一层契约，不能把两者当成同一要求。

让键的含义保持稳定

同一个键被配上不兼容的参数时，应按照服务明确的错误规则处理，而不是静默创建另一项操作，或覆盖原先保存的结果。JSON 字段顺序、默认值、数字表示和省略字段，都可能影响比较。一个小例子能规范化某种输入，不代表已经解决任意正文的语义等价问题。

下面的实验只接受一个商品字符串和一个正整数量。将这两个字段排序，定义了它自己的比较规则，并不是通用 JSON 等价算法。示例用 409 表示参数冲突，也是测试接口的政策，不是每一家幂等 API 都保证返回的状态码。

坏掉的样子

超时不能证明操作没有执行。使用新键重试，可能把一次已经成功但丢了响应的购买变成两次。为了绕过已保存的错误而换键，也可能在原行动结果仍不明时额外启动工作。应该按照服务文档给出的恢复路径核对原行动，而不是用新身份掩盖不确定性。

保留期同样限制承诺范围。Stripe API v1 允许在键至少保存二十四小时后清理，并将清理后的同键请求视为新请求；这既不是永久保存身份，也不是适用于所有服务的精确过期定时器。客户端的恢复窗口必须与实际保留契约一致，不能只考虑立即发生的重试。

快速验证

保存为 intent_check.py，用 Python 3.10 以上版本执行 python3 intent_check.py。实验已在 Python 3.14.4 上运行，只使用标准库。代码在临时目录中写入一份行动记录，再读回，退出时清理目录。API 与响应丢失都是明确的顺序模拟，不会发送网络请求，也不会连接真实支付服务。

import json
from pathlib import Path
from tempfile import TemporaryDirectory
from uuid import uuid4


def new_intent(parameters):
 return {"key": str(uuid4()), "parameters": dict(parameters)}


class FixtureAPI:
 # One already authenticated scope, sequential execution, no network service.
 def __init__(self):
 self.saved = {}
 self.orders = []
 self.attempts = []

 def execute(self, intent):
 key, parameters = intent["key"], intent["parameters"]
 self.attempts.append(key)
 if (set(parameters) != {"product", "quantity"}
 or not isinstance(parameters["product"], str) or not parameters["product"]
 or type(parameters["quantity"]) is not int or parameters["quantity"] < 1):
 return 400, '{"error":"invalid parameters"}'
 fingerprint = json.dumps(parameters, sort_keys=True, separators=(",", ":"))
 if key in self.saved:
 original, response = self.saved[key]
 return response if original == fingerprint else (409, '{"error":"key reused with other parameters"}')
 self.orders.append(dict(parameters))
 response = (201, json.dumps({"order_id": len(self.orders)}, separators=(",", ":")))
 self.saved[key] = (fingerprint, response)
 return response


def deliver(api, intent, lose_response=False):
 response = api.execute(intent)
 if lose_response:
 raise TimeoutError("simulated response loss after the fixture saved its result")
 return response


api = FixtureAPI()
parameters = {"product": "notebook", "quantity": 2}
intent = new_intent(parameters)

with TemporaryDirectory(prefix="idempotency-intent-") as directory:
 record = Path(directory) / "intent.json"
 with record.open("x", encoding="utf-8") as stream:
 json.dump(intent, stream)
 try:
 deliver(api, intent, lose_response=True)
 except TimeoutError:
 pass
 else:
 raise AssertionError("expected simulated response loss")
 assert len(api.orders) == 1
 with record.open(encoding="utf-8") as stream:
 recovered = json.load(stream)
 assert recovered == intent
 first_known_result = deliver(api, recovered)
 assert first_known_result == (201, '{"order_id":1}')
 assert deliver(api, recovered) == first_known_result
 assert len(api.orders) == 1 and api.attempts[:3] == [intent["key"]] * 3
 print("one persisted intent survives serialization and three attempts produce one order")

 reordered = {"key": intent["key"], "parameters": {"quantity": 2, "product": "notebook"}}
 assert deliver(api, reordered) == first_known_result
 changed = {"key": intent["key"], "parameters": {**parameters, "quantity": 3}}
 assert deliver(api, changed)[0] == 409 and len(api.orders) == 1
 assert deliver(api, recovered) == first_known_result
 print("equivalent field ordering replays; changed parameters conflict without replacing the saved result")

 mistaken_retry = new_intent(parameters)
 assert mistaken_retry["key"] != intent["key"]
 assert deliver(api, mistaken_retry) == (201, '{"order_id":2}')
 assert len(api.orders) == 2
 print("generating a new key for an uncertain retry creates a second order")

 invalid = new_intent({"product": "notebook", "quantity": 0})
 assert deliver(api, invalid)[0] == 400
 assert invalid["key"] not in api.saved and len(api.orders) == 2
 corrected = {**invalid, "parameters": {"product": "notebook", "quantity": 1}}
 assert deliver(api, corrected) == (201, '{"order_id":3}')
 assert len(api.orders) == 3
 print("this fixture does not save pre-execution validation failures; the corrected request can execute")

测试先保存第一次操作结果，再模拟超时。读回保存的行动并继续使用原键，三次尝试只生成一笔订单。字段顺序变化仍重放同一结果，数量改变则发生冲突，而且原结果没有被替换。如果把不确定的重试换成新键，就会创建第二笔订单，直接展示错误客户端行为的后果。

这个测试接口不会保存执行前的参数验证失败，因此修正非法数量后，仍可用尚未执行过的那个键发起操作。这只展示已经声明的政策，不能理解为对已经执行的请求也可以随意修改参数。应先区分是否进入执行阶段，再应用具体服务的规则。

文件往返验证的是序列化后身份仍然保留，并没有启动新的客户端进程，也不证明客户端存储能抵抗崩溃。持久化服务端记录、并发执行、真实传输丢失与提供方 API 都没有在本例中验收。把应用部署称为可安全重试之前，仍需验证这些真实边界。

来源

Stripe：幂等请求，稳定键、API v1 的结果保留与执行前失败，以及 API v2 差异，已核验 2026-10-15。
EC2 API 幂等性，客户端令牌语义与可反映更新状态的结果，已核验 2026-09-08。
RFC 9110，9.2.2 节定义预期效果与非幂等方法重试条件，已核验 2026-09-08。

HTTP 方法在描述意图

Sat, 24 Oct 2026 00:00:00 +0000

URL 指认目标资源，请求方法描述客户端希望源站执行的操作。服务器、缓存、代理、爬虫和重试客户端都会读取这个动词，因此方法不是路径上的装饰，而是关于预期效果的一份承诺。只有当承诺诚实时，外围设施才能做出安全的缓存、预取、重试和监控决定。同一个 URL 配上不同方法，对下游来说就是不同请求。

安全与幂等不是一回事

安全方法的定义是“本质上只读”：GET 和 HEAD 都不应要求源站改变目标资源状态。服务器仍可能写访问日志、计费或更新观测计数，但这些附带动作不改变方法的安全语义。幂等则表示，把完全相同的请求发送多次，服务器的预期效果与发送一次相同。PUT 和 DELETE 在协议上具有幂等意图，可是第一次请求可能已经到达而响应在途中丢失，客户端仍需结合版本、条件头和业务结果判断是否重试。

POST 通常表示创建从属资源或执行一次动作；它不会因为当前处理器恰好没有重复副作用，就自动变成幂等。PATCH 表示部分修改，也不天然保证重放安全。OPTIONS 用来询问通信选项，TRACE 有专门的诊断用途。具体资源允许哪些方法由源站决定；已知但不支持的方法应返回 405，并用 Allow 说明可用集合。未知方法则可能得到 501，不能把两个状态码混成一个“失败”。

让动词帮助基础设施判断

GET 与 HEAD 是否可缓存，要结合响应的缓存规则，但它们可被预取、重复读取，正是因为请求意图是只读。若把登出、购买或删除藏在 GET 地址后面，浏览器预取、链接扫描器、爬虫或缓存都可能触发不该发生的动作。重试库可以优先考虑幂等请求，却仍需检查认证、期限、请求体能否重放、条件版本和服务端是否已经提交。幂等不是分布式事务，也不保证客户端永远只看见一份响应。

PUT 请求创建或替换指定目标的状态，重复请求保持相同预期效果；DELETE 移除目标 URI 与其当前功能的关联，不保证物理删除底层数据。本例中条目变成不存在，第一次可能返回 204，后续可能返回 404。若服务端要选择新 ID 并创建对象，用 POST 加幂等键或单独的占位记录更准确，不能仅为了方便重试就假装它是 PUT。API 文档应同时写清方法、状态码、前置条件、版本冲突和重试策略，不能只写一个“请求成功”。

幂等性约束请求的预期效果，不要求响应文本、访问日志或修订历史完全一致。附带记录中的时间戳变化，不会自动破坏幂等性；但重复执行请求明确要求的购买或递增，是另一回事。重试需保留正文与适用的 If-Match 条件。幂等也不防止并发覆盖：无条件重放旧值，仍可能覆盖其他写入者刚提交的更新，必要时应核对条件失败后的权威状态。

坏掉的样子

用 GET 触发有副作用的接口，会破坏安全承诺，缓存可能发回旧结果，预取器可能提前执行动作；用 POST 进行完整替换时，重放行为取决于端点契约，不能反过来认定 POST 必然创建对象。把 PUT 叫作“绝对安全”也不准确：同一请求的效果可以幂等，但网络超时后客户端仍不知道第一次是否已提交。若没有保存可重放的请求体，重试可能送出空正文或另一版本。HEAD 处理器如果写入状态，也违反了它的只读语义。

方法边界还会与代理、重定向和媒体类型交错。代理可能保留动词却丢掉正文，重定向可能改变动词，415 则表示表示格式不被接受。应观察真实线上请求和最终响应，不要只读客户端日志里的初始对象。授权、输入 schema、条件头和持久化确认各有自己的检查；一个诚实的动词不能替代权限，也不能证明数据库已经提交。

工程上可以把契约拆成可观测断言：在本例的资源模型中，安全请求不修改业务值，重复 PUT 保持预期业务值，405 返回明确的 Allow，被拒绝的正文不增加写计数。再把断言放进代理、客户端和源站各自的测试，才能发现某一层偷偷重写方法或丢失正文。不要只在单元测试里调用处理函数，因为真实请求还会经过连接复用、重定向、认证中间件和缓存，这些边界可能改变你以为已经发送的内容。

快速验证

把下面程序保存为 methods_probe.go，用 Go 1.23 或更新版本运行。回环服务保留一个内存值，开放 GET、HEAD、PUT、DELETE、OPTIONS，拒绝其他方法，并限制 PUT 正文为 64 字节。写计数用来观察安全读取、重复幂等请求和真正副作用的区别；程序不代表持久事务。

package main

import (
 "errors"
 "fmt"
 "io"
 "net/http"
 "net/http/httptest"
 "runtime"
 "strconv"
 "strings"
 "sync"
 "sync/atomic"
 "time"
)

func must(err error) {
 if err != nil {
 panic(err)
 }
}

func check(ok bool, message string) {
 if !ok {
 panic(message)
 }
}

func main() {
 const allowed = "GET, HEAD, PUT, DELETE, OPTIONS"
 var mu sync.Mutex
 value, exists := "seed", true
 var handled, writeCalls atomic.Int64
 server := httptest.NewUnstartedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 handled.Add(1)
 defer r.Body.Close()
 if r.URL.Path != "/item" {
 http.NotFound(w, r)
 return
 }
 switch r.Method {
 case http.MethodGet, http.MethodHead:
 mu.Lock()
 body, found := value, exists
 mu.Unlock()
 if !found {
 http.NotFound(w, r)
 return
 }
 w.Header().Set("Content-Type", "text/plain; charset=utf-8")
 w.Header().Set("Content-Length", strconv.Itoa(len(body)))
 if r.Method == http.MethodGet {
 fmt.Fprint(w, body)
 }
 case http.MethodPut:
 body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 64))
 if err != nil {
 status := http.StatusBadRequest
 var oversized *http.MaxBytesError
 if errors.As(err, &oversized) {
 status = http.StatusRequestEntityTooLarge
 }
 http.Error(w, "body rejected", status)
 return
 }
 mu.Lock()
 created := !exists
 value, exists = string(body), true
 writeCalls.Add(1)
 mu.Unlock()
 if created {
 w.WriteHeader(http.StatusCreated)
 } else {
 w.WriteHeader(http.StatusNoContent)
 }
 case http.MethodDelete:
 mu.Lock()
 found := exists
 value, exists = "", false
 writeCalls.Add(1)
 mu.Unlock()
 if found {
 w.WriteHeader(http.StatusNoContent)
 } else {
 http.NotFound(w, r)
 }
 case http.MethodOptions:
 w.Header().Set("Allow", allowed)
 w.WriteHeader(http.StatusNoContent)
 case http.MethodPost, http.MethodPatch, http.MethodTrace, http.MethodConnect:
 w.Header().Set("Allow", allowed)
 http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
 default:
 http.Error(w, "unknown method", http.StatusNotImplemented)
 }
 }))
 server.Config.ReadHeaderTimeout = time.Second
 server.Config.ReadTimeout = 2 * time.Second
 server.Start()
 defer server.Close()
 transport := &http.Transport{}
 defer transport.CloseIdleConnections()
 client := &http.Client{Transport: transport, Timeout: 3 * time.Second}
 probe := func(method, payload string, status int, expected string) {
 request, err := http.NewRequest(method, server.URL+"/item", strings.NewReader(payload))
 must(err)
 response, err := client.Do(request)
 must(err)
 body, readError := io.ReadAll(response.Body)
 closeError := response.Body.Close()
 must(readError)
 must(closeError)
 check(response.Proto == "HTTP/1.1" && response.StatusCode == status, method+": wrong status/protocol")
 check(string(body) == expected, method+": wrong response body")
 if method == http.MethodHead {
 check(response.ContentLength == 4 && len(body) == 0, "HEAD must report the GET length without its body")
 }
 if method == http.MethodOptions || status == 405 {
 check(response.Header.Get("Allow") == allowed, "Allow must describe the target methods")
 }
 fmt.Printf("%s: status=%d body=%q\n", method, status, body)
 }
 probe("GET", "", 200, "seed")
 probe("GET", "", 200, "seed")
 probe("HEAD", "", 200, "")
 check(writeCalls.Load() == 0, "safe requests must not call the write operation")
 probe("PUT", "new", 204, "")
 probe("PUT", "new", 204, "")
 probe("GET", "", 200, "new")
 check(writeCalls.Load() == 2, "both repeated PUT requests must reach the server")
 probe("PUT", strings.Repeat("x", 65), 413, "body rejected\n")
 probe("GET", "", 200, "new")
 check(writeCalls.Load() == 2, "rejected PUT must leave state unchanged")
 probe("DELETE", "", 204, "")
 probe("DELETE", "", 404, "404 page not found\n")
 probe("GET", "", 404, "404 page not found\n")
 probe("OPTIONS", "", 204, "")
 probe("POST", "", 405, "method not allowed\n")
 probe("FROB", "", 501, "unknown method\n")
 check(writeCalls.Load() == 4, "method discovery and rejection must not write")
 probe("PUT", "ready", 201, "")
 probe("GET", "", 200, "ready")
 check(handled.Load() == 16 && writeCalls.Load() == 5, "wrong final request counts")
 fmt.Println("sixteen requests; five PUT/DELETE handler calls; final state ready")
 fmt.Println(runtime.Version())
}

十六次请求先执行两次安全 GET 和一次没有正文的 HEAD，写计数仍为零；两次相同 PUT 都到达源站，却收敛到同一个 new 状态。超过 64 字节的 PUT 返回 413，状态不变。第一次 DELETE 返回 204，第二次返回 404，但资源都保持不存在，体现幂等效果。OPTIONS 返回 Allow，POST 得到 405，未知的 FROB 得到 501。最后 PUT 创建 ready，GET 证明拒绝路径清理后服务仍可恢复。这些是本地处理器的可观察结果，不等于缓存新鲜度、授权、网络重放或持久化成功的证明。

来源

RFC 9110：HTTP 语义，安全与幂等方法、Allow 和状态语义，已核验 2026-09-09。
MDN：HTTP 请求方法，方法行为和实践用法，已核验 2026-09-09。
Go net/http，MaxBytesReader、请求方法和响应处理，已核验 2026-09-09。

幂等键归一到一次逻辑行动

Mon, 12 Oct 2026 00:00:00 +0000

一个幂等键只能在服务定义的作用域与保留窗口内标记一次逻辑行动。重复同一段字符串，不是放之四海皆准的“恰好执行一次”保证。服务需要把身份关联到正确的主体与操作，协调竞争中的请求，并保存足够权威的信息，以便稍后认出已经处理的行动。键只是入口，真实保证取决于这条处理链。

作用域是身份的一部分

如果全局只按客户端提交的键查找，就可能把不同租户的行动合并，甚至把别人的已存结果返回给当前调用方。查找或重放之前仍须完成认证与授权。应把可信作用域、稳定的操作标识、客户端行动键一起作为查找身份，并保留各组件边界，避免直接拼接字符串产生歧义。

究竟哪些维度属于作用域，要由 API 契约决定。EC2 明确区分地域级与可用区级幂等；按其文档规则，相同客户端令牌在不同地域或可用区可能允许执行不同的行动。因此，把重试切换到另一个地域，并不自动保留全局去重保证，不能只检查令牌文本是否一致。

请求含义也需要约束。同一个作用域内，原键配上不同参数时，必须按照已经声明的冲突规则处理。下面的实验只对一个正整数量生成比较表示，不比较任意 HTTP 正文，不执行认证，也不认为对正文取个哈希，就能自动推断业务语义是否相同。

让业务效果与结果记录一起提交

先查记录、再独立写入，会出现竞争：两个工作进程都没看见旧记录，于是都执行了业务。如果两份业务效果已经发生，之后只有一个结果记录插入成功，那么结果表上的唯一键本身并不能消除之前的重复效果。需要保护的是业务修改与记忆结果之间的完整边界。

两者都位于同一个事务数据库时，可以放在一个事务中提交。示例先执行 SQLite BEGIN IMMEDIATE，再查询记录，并在同一事务里写入业务行与结果记录。SQLite 同时只允许一个写事务，因此竞争连接会被串行处理；复合主键也明确表达了去重所依赖的身份组成。

事务保护止于这个数据库。外部支付、邮件发送或消息投递，不会因为本地事务失败就自动撤销；这些效果需要自己的端到端投递与去重契约。把整个流程命名为“恰好一次”，并不能凭空补出跨越多个系统的原子性，评审时必须沿真实副作用检查边界。

保留期也是正确性边界

如果旧请求仍可能回来，而记住它的键已经过期，那次请求就可能重新执行。Stripe API v1 文档明确说明，记录清理后的同键请求会成为新请求；其至少二十四小时的保留说明属于该提供方，并不是所有服务通用的计时器，更不能解释成永久去重。

恢复窗口应与保留期一致，还要区分临时去重记录和长期业务唯一性规则。删除结果记录，不会撤销原来的订单。如果业务禁止这笔订单在任何时候被重新创建，就需要一个比短期重试缓存更持久的权威约束，不能把希望都放在键还没过期这件事上。

恢复较旧的记录数据库、清空状态或切换到独立存储，也可能忘记已经完成的行动。恢复方案应保留业务数据与操作记录之间的关系，不能只证明各自的文件还能读取，却没有验证它们是否对应同一批已提交事实。

坏掉的样子

提交成功后丢失响应，会让客户端不知道结果，但不会自动删除已存记录。提交前事务失败，则应同时不留下业务效果与成功记录。这是两种不同情况，需要不同证据，不能把“客户端看到了错误”直接等同于“服务器没有执行”。

数据库竞争、存储不可用或未知结果，也不能被当成“查不到旧记录”。看到操作仍在执行，不应自动放行第二份业务效果。需要明确重复请求是等待、得到执行中响应，还是走另一条已有文档的恢复路径；成功结果重放只是可能状态之一，不覆盖所有中间阶段。

快速验证

保存为 scope_check.py，用 Python 3.10 以上版本执行 python3 scope_check.py。实验已在 Python 3.14.4、SQLite 3.53.0 上运行。标准库代码在私有临时目录创建数据库，结束后清理；每次尝试都打开自己的连接。租户与操作参数代表已经完成身份验证和路由解析的测试输入，不是客户端请求头的替代品。

from concurrent.futures import ThreadPoolExecutor
from contextlib import closing
import json
from pathlib import Path
import sqlite3
from tempfile import TemporaryDirectory
from threading import Barrier


with TemporaryDirectory(prefix="idempotency-scope-") as directory:
 database = Path(directory) / "orders.sqlite"
 with closing(sqlite3.connect(database)) as db:
 db.executescript("""
 CREATE TABLE effects (
 id INTEGER PRIMARY KEY, tenant TEXT NOT NULL,
 operation TEXT NOT NULL, quantity INTEGER NOT NULL CHECK (quantity > 0)
 );
 CREATE TABLE receipts (
 tenant TEXT NOT NULL, operation TEXT NOT NULL, request_key TEXT NOT NULL,
 fingerprint TEXT NOT NULL, result TEXT NOT NULL, expires_at INTEGER NOT NULL,
 PRIMARY KEY (tenant, operation, request_key)
 );
 """)

 def execute(tenant, operation, key, quantity, now, fail_before_receipt=False):
 # Tenant/operation are already authenticated/routed fixture identifiers.
 assert type(quantity) is int and quantity > 0
 fingerprint = json.dumps({"quantity": quantity}, separators=(",", ":"))
 scope = (tenant, operation, key)
 with closing(sqlite3.connect(database, timeout=5)) as db:
 with db:
 db.execute("BEGIN IMMEDIATE")
 previous = db.execute(
 "SELECT fingerprint, result, expires_at FROM receipts "
 "WHERE tenant=? AND operation=? AND request_key=?", scope,
 ).fetchone()
 if previous is not None and previous[2] > now:
 if previous[0] != fingerprint:
 return "conflict", None
 return "replay", json.loads(previous[1])
 if previous is not None:
 db.execute("DELETE FROM receipts WHERE tenant=? AND operation=? AND request_key=?", scope)
 cursor = db.execute(
 "INSERT INTO effects (tenant, operation, quantity) VALUES (?, ?, ?)",
 (tenant, operation, quantity),
 )
 result = {"effect_id": cursor.lastrowid, "quantity": quantity}
 if fail_before_receipt:
 raise RuntimeError("injected failure after effect insertion, before receipt insertion")
 db.execute("INSERT INTO receipts VALUES (?, ?, ?, ?, ?, ?)",
 (*scope, fingerprint, json.dumps(result), now + 60))
 return "created", result

 def counts():
 with closing(sqlite3.connect(database)) as db:
 return db.execute("SELECT (SELECT count(*) FROM effects), (SELECT count(*) FROM receipts)").fetchone()

 gate = Barrier(8)

 def attempt(_):
 gate.wait(timeout=5)
 return execute("north", "web-order", "intent-a", 2, 0)

 with ThreadPoolExecutor(max_workers=8) as pool:
 outcomes = list(pool.map(attempt, range(8)))
 assert [kind for kind, _ in outcomes].count("created") == 1
 assert [kind for kind, _ in outcomes].count("replay") == 7
 original = outcomes[0][1]
 assert all(result == original for _, result in outcomes) and counts() == (1, 1)
 print("eight independent connections produce one effect, one receipt, and seven replays")

 assert execute("north", "web-order", "intent-a", 3, 1) == ("conflict", None)
 assert counts() == (1, 1)
 assert execute("south", "web-order", "intent-a", 2, 1)[0] == "created"
 assert execute("north", "batch-order", "intent-a", 2, 1)[0] == "created"
 assert execute("north", "web-order", "intent-b", 2, 1)[0] == "created"
 assert counts() == (4, 4)
 print("changed parameters conflict; a different tenant, operation, or intent key has separate scope")

 try:
 execute("north", "web-order", "rolled-back", 1, 2, fail_before_receipt=True)
 except RuntimeError as error:
 assert str(error).startswith("injected failure")
 else:
 raise AssertionError("expected the transaction to fail")
 assert counts() == (4, 4)
 assert execute("north", "web-order", "rolled-back", 1, 2)[0] == "created"
 assert counts() == (5, 5)
 print("a raised exception rolls back the effect and receipt together; retry then creates one effect")

 _, committed = execute("north", "web-order", "committed-no-reply", 1, 3)
 # Discard the reply, then query through a fresh connection; no network loss is simulated here.
 assert execute("north", "web-order", "committed-no-reply", 1, 3) == ("replay", committed)
 assert counts() == (6, 6)
 print("a fresh connection replays a committed result without adding another effect")

 assert execute("north", "web-order", "intent-a", 2, 59) == ("replay", original)
 kind, after_expiry = execute("north", "web-order", "intent-a", 2, 60)
 assert kind == "created" and after_expiry["effect_id"] != original["effect_id"]
 assert counts() == (7, 6)
 print("at the explicit 60-second retention boundary, the same key creates a new effect")
 print("SQLite", sqlite3.sqlite_version, "verified counts: 7 effects, 6 retained receipts")

八条竞争连接最终产生一条业务记录、一条结果记录和七次重放，所有返回结果一致。改变数量会冲突；改变租户、操作或行动键，则按已经声明的作用域创建独立工作，使计数达到四条业务记录与四条结果记录。

在插入业务行后、保存结果之前抛出异常，事务会一起回滚两者；再次尝试才创建一份效果。已经提交的结果能通过新连接再次读取，不额外产生工作。这里丢弃的是应用调用返回值，并没有模拟网络传输丢失，也没有终止数据库进程来测试崩溃恢复。

注入时间验证第五十九秒仍然重放，而第六十秒到达过期边界时会创建新效果。最终留下七条业务记录与六条结果记录：消失的是已过期的记录，并不是它原先对应的业务行。这个结果直接展示去重保留期与业务数据寿命并不相同。

六十秒是明确的实验政策，不是生产参数建议。例子没有验证进程崩溃、断电、分布式数据库、外部副作用、真实认证或生产竞争负载。在更大的工作负载中，BEGIN IMMEDIATE 仍可能遇到数据库忙错误；本次小规模并发成功，不能证明任意压力下都不需要处理这些失败。

来源

EC2 API 幂等性，地域与可用区作用域以及参数不一致行为，已核验 2026-09-08。
Stripe：幂等请求，API v1 保留期、记录清理、参数检查与并发请求行为，已核验 2026-10-15。
SQLite 事务，单个并行写事务、BEGIN IMMEDIATE 与 SQLITE_BUSY，已核验 2026-09-08。
SQLite 原子提交，数据库修改的原子边界及存储假设，已核验 2026-09-08。
Python sqlite3，连接上下文的提交、回滚与显式关闭连接，已核验 2026-09-08。

HTTP 方法表达的是必须实现的契约

Thu, 08 Oct 2026 00:00:00 +0000

HTTP 方法描述客户端希望对目标资源执行的动作，客户端和中间层会据此判断抓取、缓存或重试方式。选择一个常见动词只是开始，应用还必须实现这个动词承诺的行为。把破坏性操作命名成 GET，并不会让它自动安全。可用的接口说明还需要交代资源模型、表示格式、授权和错误条件，不能认为方法名称已经替代了所有业务文档。

分清安全性与幂等性

安全方法具有基本只读的请求语义。GET 取得表示，HEAD 获取相应响应的元数据，却不携带响应内容。访问日志等附带效果，不会让一次读取在协议意义上变成不安全操作。但因为爬虫跟随 GET 链接就扣费，是另一回事：这个请求要求的业务动作本身改变状态，违反了安全方法的预期。判断时要看请求的预期目的，而不是要求服务器任何计数器都绝对不能变化。

幂等性关心同一个请求重复执行后的预期服务器效果。PUT 根据提交的表示替换目标资源状态；DELETE 移除目标与当前功能之间的关联。重复执行它们，预期效果应与一次执行相同，返回码、日志条数和耗时则可能不同。幂等性不能让请求自动获得权限，也不能保证不会受到其他并发写入影响。协议性质不是对任意业务实现的免费保护。

POST 请求目标资源按自身语义处理提交内容，创建资源只是常见用法，并不是全部定义。POST 通常不具备幂等保证，但应用可以另行提供明确的去重契约。PATCH 表达局部修改，具体性质取决于补丁格式和操作内容；重复“设成某个值”与重复“再增加一次”并不相同。不能看到方法名就认定所有局部修改都可以无条件重放。

坏掉的样子

重试组件如果把任何超时都当成可以重复 POST 的理由，就可能重复创建事件或扣款。即使使用幂等方法，也要理解并发与资源当前状态；条件请求可以防止覆盖已经被别人改过的表示。方法语义帮助定义动作，不会替代业务前置条件或事务规则。一次响应丢失，并不自动说明服务器没有执行原操作，重试判断必须考虑这个不确定窗口。

GET 也不代表所有缓存都可以自动重用任意响应，状态、保鲜指令、认证与表示选择仍然影响复用。GET 和 HEAD 的请求内容没有通用定义的语义，有些实现或中间层会拒绝它。不能因为本地处理器接受了读取请求中的正文，就认定这种查询方式在所有代理和客户端之间都能互通。设计公共接口时，应核对真实调用链的处理能力。

对于服务器认识、但目标不允许的方法，可以返回四零五，并用 Allow 指明支持的方法。这个能力列表不是授权凭据，也不同于 CORS 许可响应头。OPTIONS 可以说明通信选项，却不会因此让另一个浏览器来源自动有权读取响应。方法支持、账号授权和浏览器跨源限制，各自解决不同层面的问题，不能用同一个字段替代它们。

快速验证

将脚本保存为 methods.py 后执行 python3 methods.py。它使用标准库启动临时回环服务，提供一个条目资源和一个创建事件的端点。请求通过真实 HTTP 连接依次发送，断言同时检查响应与最终应用状态。这是一个小范围的方法契约实验，不是通用生产接口，没有接入外部账号或数据库，也没有修改现有站点。

from http.client import HTTPConnection
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from threading import Thread
import json

state = {'item': None, 'events': []}
allowed = 'GET, HEAD, PUT, DELETE, OPTIONS'


class Handler(BaseHTTPRequestHandler):
 def reply(self, status, data=b'', extra=None, head=False):
 self.send_response(status)
 if status != 204:
 self.send_header('Content-Length', str(len(data)))
 for key, value in (extra or {}).items():
 self.send_header(key, value)
 self.end_headers()
 if not head and status != 204:
 self.wfile.write(data)

 def do_GET(self):
 if self.path == '/item' and state['item'] is not None:
 self.reply(200, state['item'])
 else:
 self.reply(404, b'missing')

 def do_HEAD(self):
 data = state['item'] if self.path == '/item' else None
 self.reply(200 if data is not None else 404, data if data is not None else b'missing', head=True)

 def do_PUT(self):
 if self.path != '/item':
 self.reply(404, b'missing')
 return
 existed = state['item'] is not None
 state['item'] = self.rfile.read(int(self.headers['Content-Length']))
 self.reply(204 if existed else 201, extra={'Location': '/item'} if not existed else None)

 def do_POST(self):
 if self.path != '/events':
 self.reply(405, extra={'Allow': allowed})
 return
 state['events'].append(self.rfile.read(int(self.headers['Content-Length'])))
 self.reply(201, extra={'Location': f'/events/{len(state["events"])}'})

 def do_DELETE(self):
 existed = self.path == '/item' and state['item'] is not None
 if existed:
 state['item'] = None
 self.reply(204 if existed else 404)

 def do_OPTIONS(self):
 self.reply(204, extra={'Allow': allowed}) if self.path == '/item' else self.reply(404)

 def log_message(self, *args):
 pass


server = ThreadingHTTPServer(('127.0.0.1', 0), Handler)
thread = Thread(target=server.serve_forever)
thread.start()
try:
 observed = []

 def request(method, path, body=None):
 connection = HTTPConnection('127.0.0.1', server.server_port, timeout=5)
 try:
 connection.request(method, path, body)
 response = connection.getresponse()
 item = {'method': method, 'status': response.status, 'body': response.read().decode(),
 'length': response.getheader('Content-Length'),
 'location': response.getheader('Location'), 'allow': response.getheader('Allow')}
 observed.append(item)
 return item
 finally:
 connection.close()

 assert request('PUT', '/item', b'first')['status'] == 201
 assert request('PUT', '/item', b'first')['status'] == 204
 assert state['item'] == b'first'
 assert request('GET', '/item')['body'] == 'first'
 head = request('HEAD', '/item')
 assert head['body'] == '' and head['length'] == '5'
 assert request('POST', '/events', b'same')['location'] == '/events/1'
 assert request('POST', '/events', b'same')['location'] == '/events/2'
 assert len(state['events']) == 2
 assert request('DELETE', '/item')['status'] == 204
 assert request('DELETE', '/item')['status'] == 404 and state['item'] is None
 assert request('OPTIONS', '/item')['allow'] == allowed
 assert request('POST', '/item', b'wrong')['status'] == 405
 print(json.dumps({'responses': observed, 'final_item': state['item'], 'event_count': len(state['events'])}))
finally:
 server.shutdown()
 thread.join()
 server.server_close()

第一次 PUT 创建条目，返回二零一；重复完全相同的 PUT，返回二零四，但保存的值仍然是 first。GET 返回这五个字节，HEAD 没有响应内容，却报告 Content-Length 为五。该字段描述的是对应 GET 表示的长度，不能把它误解为 HEAD 响应实际携带了五字节正文。结果和消息语义需要一起阅读。

两次相同 POST 创建两个事件，并返回不同的 Location。随后第一次 DELETE 返回二零四，第二次返回四零四，条目仍然不存在。返回码不同并不违背删除效果的幂等性。OPTIONS 报告条目支持的方法，对这个条目使用 POST 则得到四零五和 Allow。这些断言把资源效果与响应形态区分开，避免用状态是否完全一样来判断幂等性。

实验没有执行 PATCH、缓存、条件更新或自动重试，因此不把这些能力算作已经验证。引入重试之前，应先说明重复请求的预期效果，再核对服务器是否真实实现。标准方法把承诺传递给其他组件；如果处理器本身违约，中间层不可能仅凭看到正确的方法名，就把错误的业务行为自动修正。

来源

RFC 9110: HTTP Semantics，安全性、幂等性、方法定义及 Allow 响应头，已核验 2026-09-13。
MDN: HTTP request methods，标准请求方法的用途与性质，已核验 2026-09-13。

HTTP 幂等让重试变安全

Wed, 26 Aug 2026 00:00:00 +0000

HTTP 幂等关注的是重复同一个请求时，服务器上预期发生的效果，而不是每次响应是否一模一样。服务器可能已经执行修改，却在客户端收到答案之前断开连接；这时重复请求可能合理，但前提是操作的真实语义允许重复，并且客户端仍遵守有界重试政策。不能把“可以重复”扩大成所有失败都应该立即重试。

相同效果，不代表相同响应

RFC 9110 用多次相同请求与单次请求的预期服务端效果来定义幂等。PUT、DELETE 和安全方法都属于幂等方法。第一次成功 PUT 可能创建资源并返回 201，再次发送则可能替换已有资源并返回 204；先删除存在的资源，再删除已经不存在的资源，也可以返回不同状态码，但最终都让目标保持不存在。

“安全”是另一种性质：客户端没有请求改变状态。GET、HEAD、OPTIONS、TRACE 被定义为安全方法，但允许附带访问日志等行为，因此不是说服务器任何地方都绝对不能写入。PUT 和 DELETE 可以符合幂等语义，却不是安全方法；把两个概念混用，会影响自动抓取与重试策略。

方法名称需要实现来兑现

把一个每次递增的接口命名为 PUT，不会让重复递增自动变成幂等。服务器需要真正兑现公开的方法语义。同样，用 GET 删除指定对象违反安全方法的约定，预取器或爬虫可能在没有删除意图时触发它。不能因为请求行上写着某个词，就跳过对业务状态变化的检查。

POST 通常不保证幂等，但某个具体 POST 操作可以通过应用层契约去重；它的用途也不局限于创建资源。自动重放之前需要理解实际契约，不能断言所有 POST 都不能重试，也不能反过来认定所有使用幂等方法名称的接口都已经正确实现。

天然可重复的写入与记住操作键，解决的是相关但不同的问题。用指定表示替换资源，是表达希望得到的状态；凭借幂等键重放订单创建，则是在识别某次特定行动。两者都不意味着每一个内部函数、访问日志或辅助步骤只会执行一次。

前置条件处理的是竞争修改

幂等本身不能阻止覆盖另一个客户端在两次请求之间写入的新内容。重复无条件替换，可能把自己的旧值重新盖到别人的新值之上。通过强实体标签与 If-Match，可以要求目标仍然是之前观察到的表示，才允许执行这次修改，而不是只比较方法名称。

条件重试也可能在原修改已经成功后失败：第一次写入完成却丢了响应，原先的标签已经不匹配。实验在这种情况下返回 412。RFC 9110 也允许服务器在判断所要求的修改已经应用时返回成功，因此不能把实验的一个选择当成所有服务必须采用的行为。

遇到结果不明确，应重新核对当前资源，或查询相应操作记录。一个状态码不足以还原多个写入者的全部先后历史；读到期望值，也不自动证明它只可能由自己那次请求产生。

坏掉的样子

盲目重试会放大负载、耗尽截止期限、重复不受保护的计费副作用，或覆盖中间写入。需要限制尝试次数和总耗时，保留原来的目标与请求意图，并遵守适用的服务端等待提示。幂等既不是并发控制方案，也不是无限重试的许可。

还应区分预期资源修改与附带日志、版本历史。出现两条诊断记录，本身不能证明业务效果发生了两次；反过来，两份看起来相同的成功响应，也不能证明只执行了一次业务行动。判断重复效果，需要读取有权威性的业务状态，而不是仅比对响应文本。

快速验证

保存为 methods_check.py，用 Python 3.10 以上版本执行 python3 methods_check.py。实验已在 Python 3.14.4 上运行，只使用标准库。代码会向自己创建的回环 HTTP 服务发送真实请求，端口由系统分配，完成后停止服务；所有业务状态都留在测试进程内存中，不访问线上系统。

from http.client import HTTPConnection, RemoteDisconnected
from http.server import BaseHTTPRequestHandler, HTTPServer
from threading import Thread


state = {"body": None, "version": 0, "orders": [], "requests": []}


def etag():
 return '"v%d"' % state["version"]


class Handler(BaseHTTPRequestHandler):
 def handle_request(self):
 state["requests"].append((self.command, self.path))
 body = self.rfile.read(int(self.headers.get("Content-Length", "0")))
 status, answer = 404, b""
 if self.path == "/item":
 if self.command in ("GET", "HEAD"):
 if state["body"] is not None:
 status, answer = 200, state["body"]
 elif self.command == "PUT":
 condition = self.headers.get("If-Match")
 # The fixture accepts one exact strong entity tag, not the full grammar.
 if condition is not None and (state["body"] is None or condition != etag()):
 status = 412
 else:
 status = 201 if state["body"] is None else 204
 if body != state["body"]:
 state["version"] += 1
 state["body"] = body
 elif self.command == "DELETE":
 status = 404 if state["body"] is None else 204
 state["body"] = None
 elif self.path == "/orders" and self.command == "POST":
 state["orders"].append(body)
 status, answer = 201, str(len(state["orders"])).encode()
 if self.headers.get("X-Fixture-Drop-Reply") == "yes" and 200 <= status < 300:
 self.close_connection = True # Apply the change, then close without a response.
 return
 self.send_response(status)
 if self.path == "/item" and state["body"] is not None:
 self.send_header("ETag", etag())
 if status != 204:
 self.send_header("Content-Length", str(len(answer)))
 self.end_headers()
 if self.command != "HEAD":
 self.wfile.write(answer)

 do_GET = do_HEAD = do_PUT = do_DELETE = do_POST = handle_request

 def log_message(self, *_):
 pass


with HTTPServer(("127.0.0.1", 0), Handler) as server:
 thread = Thread(target=server.serve_forever, kwargs={"poll_interval": 0.05})
 thread.start()

 def request(method, route="/item", body=b"", headers=None):
 client = HTTPConnection(*server.server_address, timeout=2)
 try:
 client.request(method, route, body=body, headers=headers or {})
 response = client.getresponse()
 return response.status, response.read(), response.getheader("ETag")
 finally:
 client.close()

 def lost_put(body, headers=None):
 try:
 request("PUT", body=body, headers={**(headers or {}), "X-Fixture-Drop-Reply": "yes"})
 except RemoteDisconnected:
 return
 raise AssertionError("the fixture should close before sending a response")

 try:
 assert request("PUT", body=b"blue")[0] == 201
 assert request("PUT", body=b"blue")[0] == 204
 before = len(state["requests"])
 assert request("GET")[1] == request("GET")[1] == b"blue"
 assert len(state["requests"]) == before + 2 and state["body"] == b"blue"
 assert request("HEAD")[1] == b""
 assert [request("DELETE")[0], request("DELETE")[0]] == [204, 404]
 print("PUT returns 201 then 204; DELETE returns 204 then 404; intended state is unchanged by repeats")
 print("GET appends separate diagnostic records without changing the requested resource")

 lost_put(b"blue")
 assert request("GET")[1] == b"blue"
 assert request("PUT", body=b"blue")[0] == 204
 old_tag = request("GET")[2]
 lost_put(b"green", {"If-Match": old_tag})
 assert request("PUT", body=b"green", headers={"If-Match": old_tag})[0] == 412
 assert request("GET")[1] == b"green"
 print("a lost reply can follow a committed PUT; replaying its old precondition can return 412")

 tag = request("GET")[2]
 assert request("PUT", body=b"other-writer")[0] == 204
 assert request("PUT", body=b"green", headers={"If-Match": tag})[0] == 412
 assert request("GET")[1] == b"other-writer"
 assert request("PUT", body=b"green")[0] == 204
 assert request("GET")[1] == b"green"
 print("a stale conditional PUT is refused; an unconditional repeat overwrites the intervening writer")

 first = request("POST", "/orders", b"same order")
 second = request("POST", "/orders", b"same order")
 assert first[:2] == (201, b"1") and second[:2] == (201, b"2")
 assert state["orders"] == [b"same order", b"same order"]
 print("two identical POST bodies create two orders in this endpoint's contract")
 finally:
 server.shutdown()
 thread.join(timeout=2)
 assert not thread.is_alive()

重复 PUT 得到 201、204，重复 DELETE 得到 204、404。两次 GET 增加两条诊断记录，却不改变所请求的资源；HEAD 不返回响应体。断言将业务状态与响应分别比较，不要求幂等操作的状态码完全一致。

随后服务器故意先应用 PUT，再不发送任何响应就关闭连接。无条件重试保持目标值；带旧 If-Match 的条件写入已经成功后，再次发送旧条件会得到 412。另一个写入者的修改能抵挡过期条件请求，却会被后来的无条件替换覆盖，展示幂等和防止丢失更新并非一回事。

最后，同样的 POST 正文在这个没有幂等键的创建接口中生成两笔订单。实验验证的是传输结果不明与状态转移，不证明生产持久化、分布式并发、完整 HTTP 解析或业务去重。这里的 If-Match 只处理一个完全匹配的强标签，不实现完整字段语法；Python 基础 HTTP 服务也只作为隔离测试工具。

来源

RFC 9110，9.2.1–9.2.2 与 13.1.1 节区分安全方法、幂等性、重试和 If-Match，已核验 2026-09-08。
MDN：幂等，预期效果、实现责任与不同响应，已核验 2026-09-08。
Python HTTP 服务，本地实验使用的服务 API 及不适合生产部署的警告，已核验 2026-09-08。

游标分页从明确边界继续读取

Wed, 19 Aug 2026 00:00:00 +0000

键集分页从客户端上一页实际收到的最后一个排序键继续。它不再从当前结果开头数过多少行，而是把候选行与一个具体边界比较。因此，信息流顶部新插入一条记录时，后面的页不会仅因位置整体后移就跟着错开一行。但这种方法不会冻结整个数据集，也不承诺后续每次请求都读取同一份记录。

坏掉的样子

单独使用时间戳，通常无法给出唯一边界。即使时间精度很细，多行也可能拥有相同创建时间。严格比较会跳过尚未返回的并列记录，包含等号的比较又可能重复已经展示的行。正确做法是增加一个唯一的决胜字段，并在排序与继续查询的谓词中始终使用完整键，不能一边按两个字段排序，另一边只保存其中一个。

排序字段可修改时，会产生另一类问题。已经展示过的行可能移到游标后面，于是再次出现；尚未展示的行可能移到游标前面，于是后续翻页一直看不到它。删除记录、改变过滤条件的匹配状态，也会改变下一次请求能够返回的内容。比较边界保持不变，并不能让持续变化的数据具有不可变快照的性质。

偏移分页也有明确用途：它表达当前查询结果中的编号位置，适合需要页码的界面。但在下一次偏移位置之前插入记录，可能造成重复；删除记录则可能造成遗漏。无论哪一种分页，只因为接口返回字段叫作“一页”，都不会自动获得跨请求的一致快照。需要先把产品希望保证的事情说清楚。

快速验证

把 SQL 保存为 cursor.sql，连接可丢弃的 PostgreSQL 数据库，运行 psql -X -v ON_ERROR_STOP=1 -f cursor.sql。确认实验模式 article_cursor 没被使用，并保持自动提交。遇错即停，避免建模式失败后继续操作已有对象，甚至执行最后的清理。记录中的运行版本为 PostgreSQL 18.6。实验特意让每个时间戳对应两行，先保存实际返回的第一页，再向顶部插入新行，最后修改两个已有排序键：

CREATE SCHEMA article_cursor;
SET search_path=article_cursor,public;
SET TIME ZONE 'UTC';
CREATE TABLE feed (id bigint PRIMARY KEY,published_at timestamptz NOT NULL);
INSERT INTO feed VALUES
 (1,'2026-01-01 10:00:00+00'),(2,'2026-01-01 10:00:00+00'),
 (3,'2026-01-01 11:00:00+00'),(4,'2026-01-01 11:00:00+00'),
 (5,'2026-01-01 12:00:00+00'),(6,'2026-01-01 12:00:00+00');
CREATE INDEX feed_order ON feed (published_at DESC,id DESC);
CREATE TEMP TABLE first_page AS
 SELECT id,published_at FROM feed ORDER BY published_at DESC,id DESC LIMIT 3;
SELECT array_agg(id ORDER BY published_at DESC,id DESC) FROM first_page;
SELECT published_at AS cursor_time,id AS cursor_id FROM first_page
ORDER BY published_at,id LIMIT 1 \gset

SELECT array_agg(id ORDER BY published_at DESC,id DESC)
FROM feed WHERE published_at<:'cursor_time'::timestamptz;

PREPARE after_cursor(timestamptz,bigint) AS
SELECT array_agg(id ORDER BY published_at DESC,id DESC) FROM (
 SELECT id,published_at FROM feed
 WHERE (published_at,id)<($1,$2)
 ORDER BY published_at DESC,id DESC LIMIT 3
) AS page;
INSERT INTO feed VALUES (7,'2026-01-01 13:00:00+00');
SELECT array_agg(id ORDER BY published_at DESC,id DESC) FROM (
 SELECT id,published_at FROM feed
 ORDER BY published_at DESC,id DESC LIMIT 3 OFFSET 3
) AS page;
EXECUTE after_cursor(:'cursor_time'::timestamptz,:cursor_id);

UPDATE feed SET published_at='2026-01-01 09:00:00+00' WHERE id=6;
UPDATE feed SET published_at='2026-01-01 14:00:00+00' WHERE id=3;
EXECUTE after_cursor(:'cursor_time'::timestamptz,:cursor_id);
DEALLOCATE after_cursor;
DROP TABLE first_page;
DROP SCHEMA article_cursor CASCADE;

第一个数组是 {6,5,4}，因此游标来自编号四的时间戳与编号。代码先把真正返回的第一页保存到临时表，再从它取得边界，而不是另外查询一次正在变化的原表来猜测客户端看到了什么。在读写交错时，这个区别直接决定后续边界是否对应上一份响应。

只按时间戳严格比较，得到 {2,1}，错误漏掉了与边界时间相同的编号三。向顶部加入编号七之后，偏移查询返回 {4,3,2}，其中编号四已经在第一页出现过。改用完整元组，返回 {3,2,1}，这才是在原排序键未变条件下正确接续第一页的结果。

最后两次更新把已经展示的编号六移到边界之后，把尚未展示的编号三移到边界之前。使用完全相同的游标，结果变成 {2,1,6}。编号六重复出现，编号三则从剩余遍历中消失。这些精确数组同时展示了键集分页的价值和限制，不能只引用中间一次成功结果，就宣称游标永远不会重复或遗漏。

游标要携带完整查询契约

时间戳降序、编号降序时，继续查询采用严格小于的元组比较。整体升序遍历需要相反方向。如果不同字段采用不同排序方向，谓词也必须按照真实排序关系设计，不能不加分析地照抄一个元组比较。示例把时间戳设为非空，是因为空值参与比较另有语义，实际产品需要明确它们位于哪里、如何继续翻页。

游标应完整保留实际取值，包括时间戳精度；同时要与相应的过滤和排序约定关联，避免客户端把某个搜索的边界套到另一个搜索。将字段编码成不透明字符串，可以方便接口演进，但编码本身既不防篡改，也不提供对象权限。输入仍要校验，每一页仍须遵守当前用户的访问规则。能够解码一个游标，不等于可以读取它指向的所有记录。

匹配排序的索引有机会支持直接定位边界并读取附近条目，从而避免丢弃很深的偏移区间。不过，这个很小的样本不能证明优化器一定选择该索引，也没有测量性能提升。需要结合真实数据量、过滤选择性与翻页深度观察执行计划，再判断索引是否有效，不能把建立了索引当作已经获得提速的证据。

如果需求是固定的一次导出，应另行定义更强的保证，例如有明确寿命的数据库快照或物化结果集合，并承担对应保留时间和资源成本。如果需求是实时信息流，也可以明确告知记录会在两次请求之间变化。关键是让接口的保证与用户期望相符，区分正在浏览当前数据，还是正在遍历一份被保存下来的结果。

来源

PostgreSQL 18 LIMIT 与 OFFSET，确定性排序和跳过记录的工作量，已核验 2026-09-12。
PostgreSQL 18 行比较，元组顺序与空值语义，已核验 2026-09-12。
Relay Cursor Connections，游标边界与一致的边顺序，已核验 2026-09-12。

API · XB 现场笔记

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

分开看待不同维度

坏掉的样子

快速验证

延伸阅读

来源

Protobuf 兼容性会在 JSON 边界发生变化

新增字段是否安全，取决于表示形式

跟踪中间转换，不只比较两个端点

坏掉的样子

快速验证

来源

幂等键是客户端的承诺

创建一次，在后续尝试中保留

接收方必须真正实现这份承诺

让键的含义保持稳定

坏掉的样子

快速验证

延伸阅读

来源

HTTP 方法在描述意图

安全与幂等不是一回事

让动词帮助基础设施判断

坏掉的样子

快速验证

延伸阅读

来源

幂等键归一到一次逻辑行动

作用域是身份的一部分

让业务效果与结果记录一起提交

保留期也是正确性边界

坏掉的样子

快速验证

延伸阅读

来源

HTTP 方法表达的是必须实现的契约

分清安全性与幂等性

坏掉的样子

快速验证

延伸阅读

来源

HTTP 幂等让重试变安全

相同效果，不代表相同响应

方法名称需要实现来兑现

前置条件处理的是竞争修改

坏掉的样子

快速验证

延伸阅读

来源

游标分页从明确边界继续读取

坏掉的样子

快速验证

游标要携带完整查询契约

延伸阅读

来源