🏠 总目录📚 本教程 03c · 幂等与条件请求 ← →

AI全栈 / 03c

重发一次请求,会不会多做一次业务动作?

幂等、安全和响应相同是不同判断;条件请求还要处理并发版本。

能按动作选择幂等键、缓存验证或版本前置条件。

看幂等键的边界

📑 本页目录(点开跳转)

03c · 幂等与条件请求:让「重试」变成安全动作

⏱ 66 分钟 | ⭐ 在别的系统里重试是优化,在 AI 应用里它是默认会发生的事


🎯 一句话

你的接口迟早会收到同一个请求的第二份拷贝 —— 问题不是「怎么不让它发生」,是「它发生时账上会不会多一笔」。 三样东西解决它:Idempotency-Key(同一次意图只执行一次)、ETag(没变就别再传一遍)、If-Match(别无声覆盖别人的修改)。


🧩 一、为什么这一章在 AI 板块里

普通 Web 教程把幂等放在「进阶话题」。在这里它是基础题,因为本板块自己就在三处制造重复请求:

哪一章 它做了什么
04 · 调用层 重试白名单让 429 / 5xx / 超时自动重发,而读取超时是几十秒量级。⚠️ 那张表的原话:「读取超时要小心,上游可能已在生成,重试 = 付两次钱」
10 · 把流式接到界面上 第七节:⚠️ 前端自动重发 = 一次真金白银的新调用;结论是「一定要自动重试,就必须配合幂等键」
11 · 长任务与队列 第四节开头:任务被执行两次不是「可能」,是「一定」

⭐ 根问题只有一句:出错时客户端分不出「没做成」和「做成了但回复没送到」 —— 两者在它眼里都只是一个超时。 它只能二选一:不重试(可能丢单)或重试(可能重复)。服务端要给同一意图一个可查询、可核对的结果,减少重复副作用。

💀 一个没有幂等保护的 POST /charges:上游生成慢触发 04 章那条自动重试,而上游其实已经在生成 —— 同一业务意图可能变成两次扣费或生成,⚠️ 全程不报错,日志里是两条漂亮的 200。


🧩 二、幂等 ≠ 安全 ≠ 相同响应

安全(safe)表示客户端没有请求改变资源状态;幂等(idempotent)表示重复相同请求的预期效果与一次相同。日志等附带记录可以改变,响应也可以不同。依据 RFC 9110 §9.2.1–2。

方法 安全 幂等 备注
GET / HEAD ✅ ✅ 安全的一定幂等,反过来不成立
PUT ❌ ✅ ⭐ 「把它替换成这个样子」
DELETE ❌ ✅ ⚠️ 第一次 204、第二次 404,响应不同,它仍然幂等
POST ❌ ❌ 「再来一件」
PATCH ❌ 看实现 见下

⚠️ 第三行最常被答错:幂等说的是状态 —— 两次之后那东西都没了,状态一致,变的只是响应。

⭐ PATCH 幂不幂等全看这条判据:「绝对」的操作幂等,「相对」的不幂等。 {"title": "新标题"}(赋值)幂等;{"views": "+1"}(增量)不幂等。同理 balance = 70 幂等,balance -= 30 不幂等。

⚠️⚠️ 幂等是你实现出来的协议承诺,不是写了 PUT 就自动有的。 把 PUT 实现成「往列表里追加一条」照样不幂等 —— 只是它违反了所有人对 PUT 的预期,而客户端、代理、重试库全都按那个预期在行动。

⭐ 这一节兑现的是一张欠条:04 的重试白名单和 11 的死信规则都在讲「哪些错该重试」,没人讲过「哪些请求经得起被重试」。


🧩 三、Idempotency-Key:服务端拿到这个头之后

第 11 章演示了队列消费怎样用稳定任务号和同库事务去重。这一节把边界移到 HTTP 接口。客户端重发同一次业务意图时,接口要识别原操作,并返回它的状态或可重放结果。

⭐ 客户端传键和服务端算键,差在「谁来判断这是不是同一次意图」:

同一个用户故意用完全相同的参数下两单(买两份一样的、把同一份文档再总结一版)—— 服务端算出的键一模一样,第二次被当成重试吞掉了。⚠️ 用户没收到任何错,只是东西没出现。

在发起业务操作时生成一次键,重试时复用。随机生成的 uuid4() 可以作键。每次重发都生成新键,服务端就无法把它关联到原操作。

服务端要回答四个问题:

问题 答案 为什么
① 同键、不同 body 409,绝不执行 ⭐ 422 说的是「请求本身有毛病」,可这里 body 完全合法 —— 毛病在「它和这个键先前绑的那份对不上」,那是请求与当前状态的冲突
② 并发同键 409,⚠️ 不要挂着等 靠唯一约束抢占:插得进去的干活,撞约束的知道有人在干。挂着等意味着两条连接被占几十秒,就是 06 章那个「持有时长才是瓶颈」
③ 同键、同 body ⭐ 重放第一次的响应 见下
④ 键存多久 由「客户端最长的重试窗口」定 前端手动重试、11 章的退避(MAX_ATTEMPTS = 5 封顶 60 秒)都是分钟级,跨天跑的补偿脚本是天级。🗓️ 常见 24 小时量级,⚠️ 这个数必须写进 API 文档,客户端才知道超过多久重试就不再安全
同一意图重试:何时执行,何时重放 先鉴权确定租户,再用租户与幂等键查询记录。没有记录时原子抢占;已有记录且请求体不同则拒绝,处理中不重复执行,已完成则重放结果。这是本章示例协议,不能保证远程上游恰好执行一次。 同一意图重试何时执行,何时重放先鉴权,再查(租户,键)同一次意图,重试沿用同一键① 尚无记录 → 原子抢占只有成功认领者执行业务保存结果,标记为已完成② 已有记录,请求体不同拒绝复用:本章示例返回 409不执行新的业务操作③ 已有记录,仍在处理中返回处理中:本章示例为 409按协议稍后查询或重试④ 已有记录,处理已完成同键、同请求体 → 重放结果重放不是再下一个新订单四项是互斥情况,不是四个步骤。到期、崩溃与上游副作用需要额外的恢复和对账设计。
同一租户和幂等键下,四项是互斥情况。只有首次原子认领成功者执行业务;完成后重放结果。图中 409 是本章协议选择。 单独打开图解

认领后、完成记录前崩溃,会留下 in_progress。下面的教学实现未包含租约、恢复或外部副作用对账;不能仅在 TTL 到期后无条件再调用收费上游。需要保留同一业务意图,核对实际结果,再决定恢复或补偿。

⭐ ③ 是它和「只是去重」的分界线。 11 章那段返回的是 'skipped',在队列侧够用(投递方不关心结果);接口侧不行:

客户端之所以重试,恰恰是因为它没收到第一次的响应。 你回它一句「这个做过了」,它拿不到订单号、拿不到 job id、拿不到那段结果 —— 等于失败。

服务端可以保存首次操作的状态码和业务结果,重放时给出同一个订单号。正文可能包含用户信息,留存按数据留存规则设计。正在生成的流可能还没有完整结果可重放。响应头发出后也无法改状态码(第 05 章)。可把创建任务或预留预算与读取结果分开。先用幂等键创建,拿到任务号后再查状态或接收流。

⭐ 键要有业务作用域。本例只演示一个订单操作,用 (tenant_id, key) 作主键。真实服务要按租户、操作以及需要的用户边界限定键,每次请求与重放都重新核验访问权。租户范围来自已认证身份与服务端授权关系,幂等键本身不授予访问权。见 第 08 章。

# idem_server.py —— Idempotency-Key 的服务端协议(sqlite3,直接可跑)
import sqlite3, hashlib, json

db = sqlite3.connect(":memory:")
db.execute("""CREATE TABLE idem(
  tenant TEXT, key TEXT, fingerprint TEXT,          -- ⭐ 指纹:同键不同 body 靠它认出来
  status TEXT,                                      -- in_progress / done
  resp_code INTEGER, resp_body TEXT,                -- ⭐ 第一次的响应存这,重试时原样重放
  PRIMARY KEY (tenant, key))""")                    # ⭐ 键限定在租户内,不能全局唯一
db.execute("CREATE TABLE orders(id TEXT PRIMARY KEY, tenant TEXT, cents INTEGER)")
SEQ = [0]


def fp_of(body):   # 固定字段顺序,避免把 JSON 对象的键顺序差异误判成内容变化
    return hashlib.sha256(json.dumps(body, sort_keys=True).encode()).hexdigest()


def create_order(tenant, key, body):
    fp = fp_of(body)
    try:
        with db:      # ⭐ 抢占:唯一约束保证同一时刻只有一个请求能插进来
            db.execute("INSERT INTO idem(tenant,key,fingerprint,status)"
                       " VALUES(?,?,?,'in_progress')", (tenant, key, fp))
    except sqlite3.IntegrityError:
        r = db.execute("SELECT fingerprint,status,resp_code,resp_body FROM idem"
                       " WHERE tenant=? AND key=?", (tenant, key)).fetchone()
        if r[0] != fp:                # ① 同键不同 body
            return 409, {"code": "idempotency_key_reused", "message": "这个键绑的是另一个请求体"}
        if r[1] == "in_progress":     # ② 并发同键,⚠️ 不挂着等
            return 409, {"code": "request_in_progress", "message": "同一个键正在处理中"}
        return r[2], {**json.loads(r[3]), "replayed": True}   # ⭐ ③ 重放,不是「跳过」

    SEQ[0] += 1
    out = {"order_id": "ord_%d" % SEQ[0], "cents": body["cents"]}
    with db:          # ⭐ 干活和写响应在同一个事务里(11 章第四节同款理由)
        db.execute("INSERT INTO orders VALUES(?,?,?)", (out["order_id"], tenant, body["cents"]))
        db.execute("UPDATE idem SET status='done', resp_code=?, resp_body=?"
                   " WHERE tenant=? AND key=?", (201, json.dumps(out), tenant, key))
    return 201, out


b = {"cents": 3000, "item": "pro-plan"}
print("① 第一次        ", create_order("acme", "k-1", b))
print("② 原样重试      ", create_order("acme", "k-1", b))
print("③ 同键换 body   ", create_order("acme", "k-1", {"cents": 9900, "item": "pro-plan"}))
print("④ 别的租户同键  ", create_order("globex", "k-1", b))
print("⑤ 换个键        ", create_order("acme", "k-2", b))
with db:          # 手动造一个「另一个请求正在处理中」的状态
    db.execute("INSERT INTO idem(tenant,key,fingerprint,status)"
               " VALUES('acme','k-3',?,'in_progress')", (fp_of(b),))
print("⑥ 同键正在处理中", create_order("acme", "k-3", b))
print("库里的订单:", db.execute("SELECT id,tenant,cents FROM orders").fetchall())

实跑输出:

操作步骤

  1. 第一次 (201, {'order_id': 'ord_1', 'cents': 3000})
  2. 原样重试 (201, {'order_id': 'ord_1', 'cents': 3000, 'replayed': True})
  3. 同键换 body (409, {'code': 'idempotency_key_reused', · })
  4. 别的租户同键 (201, {'order_id': 'ord_2', 'cents': 3000})
  5. 换个键 (201, {'order_id': 'ord_3', 'cents': 3000})
  6. 同键正在处理中 (409, {'code': 'request_in_progress', · })
  7. 库里的订单: [('ord_1', 'acme', 3000), ('ord_2', 'globex', 3000), ('ord_3', 'acme', 3000)]

② 和 ⑤ 的正文相同,重用同一个键时返回原订单 ord_1,换键则创建 ord_3。④ 是租户隔离的正面用例,同样的键在 Globex 对应它自己的订单 ord_2。本例在重放 JSON 中附加 replayed 标记。实际接口也可使用自定义响应头。


🧱 四、条件请求:那个 304 是怎么来的

上面解决的是「写」。读这一侧也有重复:用户每隔几秒刷一次会话列表,内容一个字没变,你却把整段 JSON 又发了一遍。

重看同一份会话,怎样省掉正文

第一次读取 c_42 时,浏览器会收到 JSON。服务器给这份表示附上实体标签(Entity Tag,ETag),这里的 "c_42-v7" 对应第 7 版。ETag 由服务器签发,客户端只需要记住并带回它。下列报文使用同一份 UTF-8 JSON 表示。为突出条件,省略了实际服务所需的身份凭证。

GET /conversations/c_42 HTTP/1.1
Host: app.example.invalid


HTTP/1.1 200 OK
Date: Mon, 09 Nov 2026 12:00:00 GMT
ETag: "c_42-v7"
Cache-Control: private, no-cache
Content-Type: application/json
Content-Length: 45

{"id":"c_42","title":"旧标题","version":7}

GET /conversations/c_42 HTTP/1.1
Host: app.example.invalid
If-None-Match: W/"c_42-v7"


HTTP/1.1 304 Not Modified
Date: Mon, 09 Nov 2026 12:00:01 GMT
ETag: "c_42-v7"
Cache-Control: private, no-cache

第二个 GET 带 If-None-Match。对 GET 而言,弱比较允许忽略标签前的 W/,所以 W/"c_42-v7" 与服务器的 "c_42-v7" 匹配。服务器只发 304 和相关响应头,客户端继续显示先前保存的正文。标签不匹配时,服务器正常返回 200、新的标签和正文。先完成身份与访问检查,再判断能否复用表示。

本例的 private, no-cache 允许私有缓存存储,但每次复用前必须验证。下文用 If-None-Match 做 GET 缓存验证。它也能作为写入前置条件,例如用 If-None-Match: * 表达「仅当目标不存在时才创建」。RFC 9110 §13.1.2 · 304 响应。

304 省掉正文传输。浏览器仍发出请求,服务端仍要做鉴权和版本检查。正文大且更新少时更容易见到收益,实际成本要看验证方式。

服务器可以按选定表示的内容生成标签,也可以用版本字段派生。用版本作强标签时,本示例固定表示格式,并约定会改变该表示的更新都会递增版本。若响应还会因格式、内容编码等变化,要保证强标签能区分不同表示。updated_at 的精度未必够区分每次更新。

强比较要求双方都是强标签,且引号内的值相同。弱比较只比较引号内的值。If-Match 使用强比较,If-None-Match 使用弱比较。RFC 9110 §8.8.3.2。

Last-Modified 精度只到秒,回滚还会让时间和内容对不上 —— 两个都能给就给 ETag。

⚠️ 两个必须点破的边界:

可跳过:先判断新鲜,再决定是否发起条件验证

新鲜度回答“可否直接复用”,ETag验证回答“旧表示是否仍可用”。以允许存储的私有HTTP缓存为例,响应max-age给新鲜寿命;没有它时,显式Expires可用Expires−Date算寿命。共享缓存还须处理s-maxage等适用规则,不能把这个私有缓存算例不加条件照搬。Age是已经积累的年龄,不是“还剩几秒”。

按RFC9111的保守年龄计算:apparent_age=max(0,收到响应时刻−Date),corrected_age_value=Age+本次响应延迟;初始年龄取二者最大值,再加驻留缓存的时间。只有 current_age < freshness_lifetime 才是fresh,边界相等已经不新鲜;过期也不等于内容必定变化,通常再用If-None-Match验证,304可更新缓存元信息后继续使用。

教学手算:假设max-age=60秒,apparent_age=4秒,Age=10秒,本次请求到响应耗时2秒,之后在缓存里又待15秒,则初始年龄max(4,10+2)=12秒,当前年龄27秒,距寿命还有33秒。这里已明示输入,不是实际浏览器抓包;Date/时钟与传输时间不能都忽略后只看本机存了多久。

无字段参数的响应 no-cache 允许存储,但每次复用前须成功验证;no-store 要求不存储该请求/响应相关内容,不是“照存、立刻过期”。它们不替代TLS、鉴权或当前ACL,也不保证擦除已存在的所有副本。含私人会话的数据还要明确private/no-store等缓存策略,不能只因有ETag就允许共享缓存。依据 RFC9111 §4.2/5.2。


🔍 五、If-Match 就是 HTTP 层的乐观锁

同一个会话还可以被改名。A 和 B 都打开第 7 版。A 保存后,B 仍拿着旧标题修改。如果后端只认会话号,B 的提交就可能覆盖 A 刚保存的标题。让客户端带上编辑所基于的版本,服务端就能识别这类丢更新。

先比较版本,再改数据。用 GET 取强 ETag,编辑完成后把它放进 If-Match。数据库必须把版本条件和写入放在同一次更新里。这里只演示已经通过授权且仍存在的会话,匹配失败时返回 412 Precondition Failed。数据库更新时仍会加写锁,这样做可以把锁限制在短事务内,避免跨模型调用持锁。

UPDATE docs SET title = ?, version = version + 1
 WHERE id = ? AND version = ?      -- 已确认记录存在时,版本不匹配导致 0 行更新
码 含义 本章的例子 客户端该做什么
412 ⭐ 你自己提的前置条件不成立 If-Match 对不上 重新 GET → 合并 → 再提交
409 请求与服务器当前状态冲突 同键不同 body、并发同键 查看业务 code。若同一操作处理中,按约定查询或等待

⭐ 记法:412 是「你提的条件不成立」,409 是「你和服务器现在的状态对不上」。 412 的可贵之处是客户端知道下一步该干什么;409 往往只能告诉它「别再原样重试了」。

这条编辑接口要求带具体的强标签。缺少 If-Match 时,本例返回 428 Precondition Required。协议还定义了 If-Match: *,它只检查是否存在当前表示。它无法证明版本没变,因此本例的编辑策略要求具体标签。RFC 6585 §3 · RFC 9110 §13.1.1。

B 收到 412 后,怎样继续编辑

① A 保存带 v7,更新成功,库里成为 v8。
② B 的旧版本被拒也带 v7,收到 412。A 的标题保持不变。
③ B 重新读取并确认对照自己的草稿与 A 的修改。确认新标题后,以 v8 提交。

本接口的 PUT 替换客户端可编辑的完整字段,这里只有标题。响应里的 id 和版本由服务端管理。成功用 204,省略响应正文,也不在这份 PUT 响应里发送新标签。下一次 GET 再取新表示和标签。RFC 9110 §9.3.4。

PUT /conversations/c_42 HTTP/1.1
Host: app.example.invalid
If-Match: "c_42-v7"
Content-Type: application/json
Content-Length: 23

{"title":"A 的标题"}

HTTP/1.1 204 No Content
Date: Mon, 09 Nov 2026 12:00:02 GMT


PUT /conversations/c_42 HTTP/1.1
Host: app.example.invalid
If-Match: "c_42-v7"
Content-Type: application/json
Content-Length: 23

{"title":"B 的标题"}

HTTP/1.1 412 Precondition Failed
Date: Mon, 09 Nov 2026 12:00:03 GMT
Content-Type: application/json
Content-Length: 34

{"error":{"code":"stale_version"}}

收到 412 后,B 保留自己的草稿,重新 GET 取 v8。确认把两人的修改合并成一个标题后,再提交。如果又有人先保存,则再次显示冲突,让用户决定下一步。

GET /conversations/c_42 HTTP/1.1
Host: app.example.invalid


HTTP/1.1 200 OK
Date: Mon, 09 Nov 2026 12:00:04 GMT
ETag: "c_42-v8"
Cache-Control: private, no-cache
Content-Type: application/json
Content-Length: 47

{"id":"c_42","title":"A 的标题","version":8}

PUT /conversations/c_42 HTTP/1.1
Host: app.example.invalid
If-Match: "c_42-v8"
Content-Type: application/json
Content-Length: 37

{"title":"A 的标题 + B 的补充"}

HTTP/1.1 204 No Content
Date: Mon, 09 Nov 2026 12:00:05 GMT

动手核对。保存为 conditional.py,用 Python 3.11 或以上运行 python conditional.py。函数返回「状态码、响应头、正文」三项。程序只用标准库和 SQLite 内存数据库。它用一个合法标签演示比较规则,省略了认证、HTTP 传输和完整的标签列表解析。

import sqlite3

db = sqlite3.connect(":memory:")
db.execute("CREATE TABLE docs (id TEXT PRIMARY KEY, title TEXT, version INTEGER)")
db.execute("INSERT INTO docs VALUES ('c_42', '旧标题', 7)")
db.commit()


def current():
    return db.execute("SELECT id, title, version FROM docs WHERE id=?", ("c_42",)).fetchone()


def tag_for(row):
    # 表示固定,表示发生变化时递增版本。
    return f'"{row[0]}-v{row[2]}"'


def GET(if_none_match=None):
    row = current()
    tag = tag_for(row)
    headers = {"ETag": tag, "Cache-Control": "private, no-cache"}
    if if_none_match and if_none_match.removeprefix("W/") == tag:
        return 304, headers, None
    return 200, headers, {"id": row[0], "title": row[1], "version": row[2]}


def PUT(title, if_match=None):
    if if_match is None:
        return 428, {}, {"error": {"code": "if_match_required"}}
    row = current()
    stale = (412, {}, {"error": {"code": "stale_version"}})
    if if_match != tag_for(row):
        return stale
    with db:
        result = db.execute(
            "UPDATE docs SET title=?, version=version+1 WHERE id=? AND version=?",
            (title, row[0], row[2]),
        )
    return (204, {}, None) if result.rowcount == 1 else stale


first = GET()
v7 = first[1]["ETag"]
unchanged = GET("W/" + v7)
assert unchanged == (304, first[1], None)
assert PUT("缺少标签")[0] == 428
assert PUT("弱标签", "W/" + v7)[0] == 412
assert GET() == first
assert PUT("A 的标题", v7) == (204, {}, None)
assert PUT("B 的标题", v7)[0] == 412
latest = GET("W/" + v7)
assert latest[0] == 200 and latest[2]["title"] == "A 的标题"
assert PUT("A 的标题 + B 的补充", latest[1]["ETag"]) == (204, {}, None)
assert GET()[2] == {"id": "c_42", "title": "A 的标题 + B 的补充", "version": 9}
print("读旧版 200 → 弱比较 304 → 缺条件 428 → 弱标签写 412")
print("A 保存 204 → B 冲突 412 → 读取新版 200 → 确认合并 204")
print("最终版本", GET()[1]["ETag"])
db.close()

预期输出依次为 200 → 304 → 428 → 412、204 → 412 → 200 → 204、最终 "c_42-v9"。弱标签能匹配读取条件,但无法通过强比较的写入条件。被拒的写入都没有改变当时的标题。正式应用还要在更新范围内核对租户和对象权限,并处理资源被删除的分支。

同一种短事务思路也出现在 第 06 章的事务边界和第 11 章的条件认领中。先让数据库用一个条件决定能否更新,外部调用在事务之外执行。


📋 六、把三件事拼起来

创建任务时可以用 Idempotency-Key 关联同一意图。读已有表示时用 ETag 和 If-None-Match 验证缓存。基于旧版编辑时用强标签和 If-Match 保护写入。三种检查分别看业务操作、缓存表示和写入所基于的版本。

接口设计时,先确认业务是创建新操作,还是替换已知资源,再选择方法与保护方式。会产生副作用且允许重发时,约定原操作的标识与可恢复结果。

⚠️ 客户端也有三件事必须配合:① 键原样带回;② 尊重 429 带回来的 Retry-After(12 章讲它怎么从令牌桶算出来);③ 退避加抖动。


🔄 换个栈怎么对应

概念 Python / FastAPI(本板块主栈) Node(Express / Hono) Go
读请求头 Header(default=None)(下划线自动转连字符) req.get('Idempotency-Key') / c.req.header(...) r.Header.Get("Idempotency-Key")
幂等键存储 ⭐ 一张带唯一约束的表 —— 就是 06 章那个库 同左 同左
返 304 Response(status_code=304) res.status(304).end() w.WriteHeader(http.StatusNotModified)
⚠️ 自动 ETag 没有内置,自己算 🗓️ Express 有个 etag 应用设置(给 res.send 加弱 ETag) http.ServeContent 只对静态文件处理条件请求
乐观锁 UPDATE … WHERE version = ? 看受影响行数 同左 同左

⭐ 这张表要看出的是:哪些是概念、哪些只是这个框架的叫法。 没有任何一个框架内置 Idempotency-Key —— 它必须落在你的存储上、按你的业务语义决定什么算「同一次意图」,外包不出去。而 ETag/304 有的框架替你做了一半,⚠️ 可它替你做的恰好是「把整个 body 算出来再哈希」那一半 —— 省传输不省计算,真正值钱的版本派生仍然得你自己写。


🔗 这一章连到哪里

去哪 为什么
⭐ 11 · 长任务与队列 本章是它第四节末尾「更稳的是让客户端传 Idempotency-Key 头」那句话的下半截。⭐ 两侧一起看:那边管「同一个任务被消费两次」(服务端算键),这边管「同一个请求被发两次」(客户端传键)
⭐ 04 · 调用层 那一章先判断错误可否恢复,再判断原操作能否安全重放。发送后的超时可能需要查询原结果
10 · 把流式接到界面上 第七节说「一定要自动重试就必须配合幂等键」—— 服务端那一半在本章第三节:键怎么存、怎么重放、怎么按租户隔离
⭐ 06 · 关系数据库 乐观锁的 version 列和幂等键表都落在那一章的库上。⭐ 反过来也成立:那一章禁止攥着行锁调外部服务,本章的版本号正是那条禁令下还能用的并发控制
⭐ 03b · 接口的形状 那一章讲资源、方法和状态码的整体选择。本章接着拆开业务重放、缓存验证与写入前置条件
08 · 认证、会话与多租户 幂等键需要限定在授权租户和业务范围内,重放前再查当前对象权限
16 · 上线前检查单 那份清单里「同一个 Idempotency-Key 投三次 → 账上只有一笔」,验的就是本章第三节

✅ 检查点

  1. 「安全」「幂等」「相同响应」分别是什么?DELETE 第二次返 404,它还幂等吗?PATCH 幂不幂等取决于什么?
  2. 客户端传 Idempotency-Key 比服务端自己算键好在哪?客户端唯一的硬规矩是什么?
  3. 同键不同 body 为什么返 409 而不是 422?本例遇到同键正在处理时,客户端下一步该做什么?
  4. 为什么接口重放要给出原结果或查询入口?生成流还没完成时,如何分离创建与读取?
  5. 本例为什么把租户加入幂等键表的主键?实际重放还要检查什么?
  6. 304 省掉的是什么、没省掉的是什么?它和 04 章的 LLM 结果缓存差在哪?
  7. 412 和 409 怎么分?为什么这个板块更该用乐观锁而不是 SELECT ... FOR UPDATE?
  8. 服务器当前标签为 "c_42-v7"。若带 W/"c_42-v7",条件 GET 与条件 PUT 各返回什么?写请求没带条件呢?
👀 答案
  1. 安全表示客户端没有请求改变资源状态。幂等看重复相同请求的预期效果是否与一次相同。附带日志和响应可以不同 —— DELETE 第二次返 404 仍然幂等,两次之后那东西都没了。PATCH 取决于补丁语义:「绝对」的操作幂等({"title": "新标题"}),「相对」的不幂等({"views": "+1"})。
  2. 服务端算的键分不出「重试」和「用户故意再来一次」 —— 同一个用户用相同参数下两单,算出的键一样,第二单被当成重试吞掉,用户还收不到任何错。客户端传键把「是不是同一次意图」的判断权交回发起方。硬规矩:发起时生成一次、重试时原样带回;可以首次用 uuid4() 生成。
  3. 422 说的是「请求本身有毛病」,而这里的 body 可能完全合法,毛病在「它和这个键先前绑的那份对不上」—— 那是请求与当前状态的冲突,所以是 409。本接口约定同键处理中返回独立的错误码。客户端按约定查询状态,或在预算内稍后用原键重试。
  4. 客户端需要原订单号或任务号,才能继续查询。可以先用幂等键创建任务,再按任务号读取状态或流。
  5. 本例同一个键在不同租户可对应不同订单。重放前仍要检查当前访问权。保留时间按业务恢复和客户端重试窗口设计,并写进接口文档。
  6. 304 省正文传输,仍有请求往返和授权检查。模型结果缓存决定能否复用生成结果,条件 GET 则验证先前保存的 HTTP 表示是否还能使用。
  7. 412 表示前置条件不成立。重新 GET 后比对草稿与新表示,确认后再提交。409 表示请求与当前状态冲突,按业务错误码处理。用短事务检查版本,可把模型调用放在事务之外。
  8. 条件 GET 用弱比较,返回 304 并继续用旧正文。条件 PUT 用强比较,返回 412 且不写入。没有提供写入条件时,本例返回 428。

本节回顾

⚡ 走神救援

根问题:出错时客户端分不出「没做成」和「做成了但回复没送到」,只能在丢单和重复之间二选一。服务端的活,是让「重试」不再有代价。

⭐ 这在本板块是基础题,因为板块自己就在制造重复:调用层必须检查超时后的结果和安全重放条件、前端重发是一次真金白银的新调用、队列里任务可能重复执行。

安全表示客户端没有请求改变资源状态。幂等比较重复相同请求的预期效果,响应和附带日志可以不同。

⭐ Idempotency-Key 由客户端传,强过服务端自己算——差别在谁判断「是不是同一次意图」:服务端按内容算哈希,会把「用户故意再下一单」当成重试吞掉。

本例对同键异体或同键处理中都用 409,但用不同错误码。已完成时给出原业务结果。键保留多久、如何查询状态和处理过期,都是接口合同的一部分。

⭐ 本例按租户和键查记录,重放仍要通过当前授权检查。

⭐ If-Match 就是 HTTP 层的乐观锁,治丢更新:两个人都拿着同一版本,后存的无声覆盖先存的,全程零报错。服务端只要一条带版本条件的 UPDATE,将版本比较和写入放在同一个短事务内。⭐ 412 是「你提的条件不成立」,409 是「你和服务器当前状态打架」。

⭐ 这个板块尤其该用乐观锁:写路径是「读 → 调模型几十秒 → 写回」,而攥着行锁调外部服务是明令禁止的。

对会产生副作用的请求,写清重发能否安全,以及怎样查到原结果。

下一节 👉 04-调用层.md

打卡记录保存在你的浏览器里,首页能看到总进度