通过代理实现幂等与重试:如何避免重复请求创建重复订单
引言:一次点击,两个订单,一条丢失响应的隧道
想象一个运行多年的集成系统。你的服务向外部系统发送订单,流量经过移动代理池,以分散请求到不同地区并避免单个地址触发限流。一切稳定。突然,财务部门拿来一份报告:这个月合作伙伴那里出现了四十七个孪生订单。商品相同,金额相同,创建时间只差三四秒。没人改过任何东西。发生了什么?
发生了再普通不过的事:通过代理的连接在返回路径上断了。服务器收到了请求,创建了订单,发送了响应,但响应没有到达客户端。客户端诚实地认为请求失败,于是重试。第二个请求也执行了。重复订单就此诞生,而任何重试策略本身都无法防止它。
这里需要先划清界限。关于如何在 429 错误后正确重试、尝试之间等待多久、如何构建指数退避,我们另有文章讨论:那是重试策略的话题。今天我们要谈的是另一件事:客户端与服务器之间的契约,它决定了重试是安全还是危险,无论你具体怎样执行。这个契约叫做幂等性,而它的核心工具就是幂等键。
为什么通过代理工作时这个问题尤其尖锐?因为代理在链路中又增加了一段响应可能丢失的环节。移动代理还会在轮换时改变外部 IP,服务器完全可能从另一个地址看到第二个请求。如果你的防重复机制依赖会话、IP 或时间窗口,它就会崩溃。如果依赖幂等键,那么重复来自哪里都无所谓。
通过本指南,你将了解幂等性在协议层和业务逻辑层如何运作,如何生成和存储键,如何设计能承受并发重试的服务端存储,外部 API 不支持键时该怎么办,以及经验丰富的团队也会踩哪些坑。我们会用带数字的案例来分析,整理检查清单,并回答那些让人不舒服的问题。本文面向集成开发者、架构师和技术负责人,他们处理订单、支付以及任何“两次”意味着“糟糕”的操作。
基础:什么是幂等性,为什么重试请求本来就危险
用简单的话定义
如果一个操作执行多次的结果与执行一次相同,它就叫做幂等操作。按十次电梯按钮是幂等的:电梯只会来一次。再往购物车放一件商品则不是幂等的:每次点击都会改变状态。转账当然也不是幂等的,除非系统专门设计成相同标识符的重复转账什么都不做。
HTTP 中有一些按规范被视为幂等的方法:GET、PUT、DELETE、HEAD。还有一个 POST 方法,默认不被视为幂等。而创建订单、支付、发送消息最常用的恰恰是 POST。也就是说,最危险的操作存在于最不幂等的方法里。是巧合吗?更像是我们不得不面对的历史规律。
任何请求的三种结局
当客户端发送请求却没有收到响应时,它就陷入了不确定状态。正好有三种可能:
- 请求没有到达服务器。 重试是安全的:什么都没发生。
- 请求到达了,服务器执行了操作,响应丢失了。 重试是危险的:操作会执行第二次。
- 请求到达了,服务器开始执行但还没完成。 重试加倍危险:两个操作会并行执行。
关键问题在于,客户端无法区分这些情况。超时在三种情况下看起来都一样。连接断开也一样。由此得出分布式系统的一条基本原则:可靠投递只能是“至少一次”(at-least-once)。在传输层无法获得“恰好一次”(exactly-once)保证;只能在应用层通过让重试无害来模拟。幂等性就是这种模拟方式。
代理如何延长不确定性的链路
没有代理时,客户端和服务器之间只有一段网络。有代理时变成两段:客户端—代理和代理—服务器。响应可能在任何一段丢失。而且如果它在第一段丢失,代理其实已经收到了响应,服务器已经完成了操作,而客户端永远不会知道。
移动代理还有特殊之处。它们按计划或按请求轮换 IP,在基站之间切换,无线信道质量自然波动。这些事件中的任何一个都可能在任意时刻断开 TCP 连接。而且断得最多的往往不是请求体传输时(请求体很小,很快就飞走了),而是等待响应时,连接只是保持打开。恰恰在这个时刻,服务器正在处理你的订单。恰恰在这个时刻,断连产生重复订单的概率最大。
什么是幂等键
幂等键(Idempotency-Key)是业务操作的唯一标识符,客户端生成一次,并在每次尝试执行该操作时随请求传递。服务器记住这个键和结果。当带同一键的重复请求到来时,服务器不会重新执行操作,而是返回已保存的结果。客户端可以随意重试:订单只会创建一次。
注意这个表述:键标识的是操作,而不是HTTP 请求。这个区别在后面分析实现错误时会成为核心。
深入探讨:服务端契约与安全重试的解剖
契约作为行为约定
幂等性不是一个请求头,也不是一个库。它是一个契约:服务器承诺在重复请求时对客户端表现出特定行为,客户端承诺遵守键的生成规则。好的契约要回答以下问题:
- 哪个实体是幂等性的单位:订单、支付、订单行、批次?
- 客户端怎样传递键:请求头、请求体字段、URL 的一部分?
- 如果键相同但请求体不同,会发生什么?
- 如果第一个请求还在执行,而带同一键的第二个请求到了,会发生什么?
- 服务器记住键多久?
- 重复请求返回什么:与原始响应逐字节相同的响应,还是实体的当前状态?
- 在日志和指标中,重试如何与新请求区分?
如果 API 文档中没有回答其中任何一个问题,契约就是不完整的,在不确定情况下行为将取决于实现、版本和月亮相位。
键的三种状态
在服务器上,每个键都有一个由三种状态组成的生命周期。理解这个周期能解释百分之九十的重复订单问题。
- 不存在。 第一次看到这个键。服务器必须原子性地预留它并开始处理。
- 进行中(in-progress)。 第一个请求正在处理。带同一键的第二个请求不应该启动第二次处理。可选方案:返回 409 Conflict 并提示等待,阻塞直到第一个完成并返回其结果,返回 202 Accepted 并附带状态链接。
- 已完成。 结果已保存。重复请求返回已保存的结果,不产生副作用。
最常见的架构错误是跳过中间状态。开发者检查“数据库里有没有这个键”,没找到,就开始处理,而此时并行的重复请求也做了同样的事。两个线程,两次检查,两个订单。检查和预留必须是单个原子操作:带唯一索引的插入、Redis 条件写入、带锁的事务。
请求指纹
键标识操作,但是什么内容上的操作?如果客户端因 bug 用键 K 发送了金额 1000 卢布,然后又用同一个键重复发送金额 10000,服务器应该怎么做?默默返回第一次操作的结果是危险的:客户端会以为支付了 10000。执行第二个又违反幂等性。
正确答案是:服务器保存请求指纹(fingerprint)——规范化后的请求体和重要请求头的哈希。当同一键但不同指纹的重复请求到来时,返回 422 Unprocessable Content 或 400,并带明确的错误码,如 idempotency_key_reused_with_different_payload。这可以防止客户端的逻辑错误和重复请求被伪造。
响应的存储:快照还是当前状态
重复请求返回什么有两种思路。快照:服务器保存原始响应的状态码、请求头和请求体,原样返回。这严格幂等且可预测。当前状态:服务器通过键找到已创建的实体并返回其当前表示。如果订单在尝试之间已进入其他状态,这更方便,但可预测性较差。
支付系统占主导的是快照:客户端必须收到第一次尝试时的那份响应。订单管理系统常用混合方式:错误码返回快照,成功返回当前状态。关键是选择要在契约中固定下来。
代理在契约层面改变了什么
从技术上讲,代理不参与幂等性契约:它对请求头和请求体是透明的。但它改变了概率。通过直连时,成功执行但响应丢失是罕见中的罕见,概率的百分之几的百分之几。通过带轮换的移动代理链路时,这个事件会变得频繁。我们观察到一些集成中,在五分钟轮换 IP 时,大约 0.3%–0.8% 的请求在等待响应阶段以连接断开告终。每天一万个订单就是每天三十到八十个潜在重复。没有幂等键,每一个都会变成真实重复。
还有第二个微妙之处。很多服务器在反欺诈逻辑中检查“来自不同 IP 的重复请求”。移动代理轮换时,重复几乎总是来自新地址。如果服务器把这当作可疑活动并在不查询键存储的情况下拒绝重复,客户端就得不到已保存的结果,仍然处于不确定状态。好的契约会在任何与网络相关的启发式检查之前先检查键。
方法一:在客户端生成并传递幂等键
键在哪里诞生
首要规则:键每个业务操作只生成一次,在第一次发送尝试之前,并与执行操作的意图一起保存。如果键是在 HTTP 客户端内部每次调用时创建的,重试就会得到新键,所有保护都会归零。这个错误如此常见,我们会在反模式部分单独列出,但这里也要重复:键活在订单服务层,而不是传输层。
实际操作顺序如下:
- 用户或内部流程发起创建订单。
- 服务创建本地“订单意向”记录,状态为 pending,并生成键。
- 键和有效负载在同一事务中保存到本地数据库。
- 事务提交后才开始通过代理发送到外部 API。
- 所有重试从本地记录读取键,而不是生成新键。
- 收到响应后,本地记录更新结果和外部订单标识符。
这种顺序保证即使你的服务在重试过程中重启,键也不会改变:它在数据库里。
键的格式
键必须全局唯一,并且对第三方不可预测。可行方案:
- UUID 版本 4——经典方案,122 位随机性,到处都适用。
- UUID 版本 7 或 ULID——高位包含时间戳,便于排序和在服务器数据库索引。到 2026 年,这已经是新系统的标准选择。
- 从自然标识符派生的确定性键——例如由购物车标识符、用户标识符和购物车版本的哈希。当客户端自己可能丢失状态并能从相同数据重新生成键时很有用。
要避免的:连续数字(容易被猜到别人的键并获取别人的响应)、短字符串、只依赖低精度时间的键。
传递方式
事实标准是 Idempotency-Key 请求头。IETF 规范草案固定了这个名称,大多数现代 API 都遵循它。通过代理调用的示例:
curl -x http://user:pass@proxy.example:8080 -H "Idempotency-Key: 018f3a2c-7b1e-7c3d-9a4e-1f2b3c4d5e6f" -H "Content-Type: application/json" -d '{"cart_id":"c-9921","amount":149000}' https://api.partner.example/v1/orders
有些 API 接受请求体中的键(字段 client_reference_id、external_id、request_id)。这也是可行方案,但有一个细节:如果服务器用请求体字段作为键,它必须参与唯一索引,否则它只是一个标记,不是保护。
键的作用域
键应该在一个客户端账户和一个端点范围内唯一。好的服务器把内部存储键组成账户标识符、方法、路径和传递的键的组合。这可以防止不同客户端之间的冲突,以及键被意外复用于另一个操作。
客户端检查清单
- 键在第一次尝试之前生成,并与意向一起存在数据库中。
- 所有重试使用同一个键。
- 重试时请求体与第一次尝试逐字节相同。
- 客户端能把 409(操作进行中)当作等待并重试的信号处理,而不是错误。
- 客户端能把带指纹不匹配码的 422 当作需要人工介入的逻辑错误处理。
- 客户端在与操作相关的所有日志中记录键,以便调查重复。
- 客户端在更换代理、轮换 IP 或切换到备用池时不会重置键。
方法二:服务端键存储的实现
如果你拥有客户端或合作伙伴通过代理访问的服务器,这一节就是为你写的。如果你只是客户端,它可以帮助你根据文档和行为评估别人实现的质量。
存储结构
键的最小表或结构包含以下字段:
- scope_key——组合键:账户、方法、路径、传递的 Idempotency-Key。唯一索引。
- fingerprint——规范化请求体的哈希。
- state——in_progress、completed、failed 之一。
- response_status、response_headers、response_body——响应快照,完成时填写。
- resource_id——创建的实体标识符,如适用。
- locked_at、completed_at、expires_at——处理挂起操作和清理的时间戳。
原子预留
实现的核心是一个操作,它要么一次性创建 in_progress 状态的记录,要么告知记录已存在。在关系数据库中,这是带唯一索引冲突处理的插入。在 Redis 中,是带 NX 和 EX 标志的 SET 命令,只在键不存在时写入值并同时设置生存时间。绝不能“先 SELECT,再 INSERT”:并行的重复请求会从中间钻过去。
逻辑层面的伪代码:
- 计算 scope_key 和 fingerprint。
- 尝试插入 state = in_progress 的记录。如果插入成功,转到执行操作。
- 如果冲突:读取已有记录。
- 如果 fingerprint 不匹配——返回 422 和不匹配错误码。
- 如果 state = in_progress——返回 409 并带 Retry-After 头,或等待完成(在合理超时内)。
- 如果 state = completed——返回保存的响应快照,并带标记重复的请求头,例如
Idempotent-Replayed: true。
执行与结果固化
这里藏着第二个陷阱。操作执行了,订单创建了,但进程在把结果写入键存储之前崩溃了。记录永远停留在 in_progress 状态。重复请求收到 409,再 409,无限循环。
有三种解决方法:
- 单一事务。 创建订单和更新键记录在同一数据库事务中执行。如果订单和键在同一个数据库,这是最可靠的方案。
- 键作为实体的一部分。 幂等键直接存在订单表中,带唯一索引。那么订单本身就是键的记录;不需要单独的表。对于每个操作只有一个实体的场景,简单且可靠。
- 挂起恢复。 后台进程找到超过阈值(例如 60 秒)的 in_progress 记录,检查操作是否实际执行过(通过 resource_id 或搜索实体),然后要么完成固化,要么把记录转为 failed 允许重试。
第一次尝试错误的处理
如果第一次尝试以错误告终,应该保存什么?取决于错误类型。验证错误(400、422)是确定性的:相同请求体重试会得到相同结果,可以缓存。基础设施错误(500、503、数据库超时)不是确定性的:如果缓存它们,客户端就永远无法成功执行操作。正确行为:基础设施错误时释放键(删除记录或转为 failed 并允许重新获取),让下一次重试再试。
键的生存时间
键不能永久保存:表会膨胀。但太短的期限也危险:如果客户端在网络故障半小时后重试,键必须还活着。大型支付提供商的做法收敛于至少 24 小时。电商订单 24–72 小时比较合理。对于客户端可能在长时间故障后重试的操作(例如每天一次同步目录),期限至少应是同步间隔的两倍。
可观测性
每次重试都应留下痕迹。值得收集的指标:命中 completed 的重试次数(无害重试)、409 次数(并发重试)、422 次数(指纹不匹配——几乎总是客户端 bug)、最旧 in_progress 记录的年龄(挂起操作指标)。重试与唯一操作的比例是客户端和服务器之间网络质量的直接度量。如果它急剧上升,说明代理通道质量恶化或轮换方式改变了。
服务端检查清单
- 键的预留是原子的。
- 有单独的 in_progress 状态和对并发重试的明确响应。
- 保存请求体指纹,不匹配时用明确错误拒绝。
- 结果固化是事务性的,或有恢复挂起记录的机制。
- 基础设施错误不缓存,确定性错误缓存。
- TTL 不少于 24 小时并已记录文档。
- 重复请求用请求头标记并在指标中可见。
- 键检查发生在反欺诈网络启发式检查之前。
方法三:不破坏幂等性的代理重试协议
重试策略是另一篇文章的话题,但有一小部分重试策略与幂等性交叉:代理链路传来的哪些信号意味着需要重试,以及重试不应该破坏契约。我们来分析这一点。
区分代理故障和上游故障
通过代理工作时,客户端会收到三种来源的错误,需要区别对待:
- 连接代理的错误。 无法连接代理,代理返回 407(需要认证),代理在发送请求前关闭连接。请求保证没有到达服务器。即使没有键,重试也是安全的,但有键更好。
- 代理访问上游时的错误。 代理返回 502 Bad Gateway 或 504 Gateway Timeout。这里不确定性最大:502 通常意味着上游没有正确响应,但可能已执行操作;504 意味着代理等累了,而服务器可能还在处理。只有带键才能重试。
- 通过代理传递的上游响应。 目标服务器的 500、503、429。它们的语义由目标 API 的契约定义。按重试策略规则带键重试。
特别值得关注的是读取响应期间连接断开。请求头已经到达,请求体中断了。这是最狡猾的情况:你可能看到了 201 Created 状态码,但没有从请求体中获得订单标识符。带键重试会返回完整响应快照。没有键,你会得到第二个订单,而且仍然不知道第一个订单的标识符。
IP 轮换作为事件而非背景
如果你的移动代理池按计划轮换地址,就把关键操作的发送与稳定窗口同步。一个简单技巧:向代理服务的 API 询问距离下次轮换的时间,如果距离轮换小于你的响应等待超时,就不要开始创建订单。这不能替代幂等性,但能减少重试次数,从而减轻键存储和合作伙伴反欺诈系统的负担。
如果轮换是按请求触发的,不要在同一个操作的尝试之间无必要地调用 IP 切换。有些团队这样做“是为了绕过粘滞”,但服务器看到同一个键来自新地址时,可能会启用额外检查。键能防止重复,但重试可能会变慢。
超时:两条边界而非一条
直连时通常设置一个响应超时。通过代理至少需要两个:与代理建立连接的超时(短,几秒)和等待上游响应的超时(较长,考虑订单处理时间)。如果合并成一个,短超时会在处理缓慢时不断触发,产生多余重试;长超时会让不可用的代理多等几秒。
重要:响应等待超时不应小于服务器上实际的订单创建时间。否则你会系统性地在正好处理时断开连接,每个操作都会变成“中断的尝试加重试”的一对。键能防止重复,但服务器会白白消耗资源来处理。
通过另一个代理重试
合理策略:第一次重试走同一个代理(可能只是连接闪了一下),第二次走池中另一个代理(可能具体通道有问题)。键不变。请求体不变。只有路由改变。这样能把网络问题与请求本身的问题分开,并获得诊断信息:如果通过第二个代理立即成功,问题就在通道。
安全重试的分步协议
- 从本地意向记录读取键和请求体。
- 通过当前代理发送请求,使用两个超时。
- 成功时:保存结果,结束。
- 服务器返回 409 时:等待指定时间或合理间隔,用同一个键重试。
- 返回带指纹不匹配码的 422 时:停止,升级事件,不自动重试。
- 连接代理出错时:更换代理,立即重试。
- 遇到 502、504、断开或超时时:应用延迟策略,用同一个键重试;从第二次重试起通过另一个代理。
- 尝试耗尽后:把记录留在 unknown 状态,交给核对队列(见方法四)。
第八点至关重要。“不知道订单是否创建”是一个合法状态,不能默默折叠成“已创建”或“未创建”。
方法四:当服务器不支持幂等键时
理想世界在第一个文档中没有“幂等性”一词的合作伙伴 API 处就结束了。如果你是客户端,而服务器对每个 POST 都直接创建订单,该怎么办?有几种技术,从简单到架构级。
请求字段中的自然键
很多 API 没有正式的 Idempotency-Key,但接受 external_order_id、client_reference、merchant_order_number 之类的字段,并承诺在账户范围内按其唯一。这就是换了个名字的幂等性。查阅文档,更重要的是检查行为:在测试环境发送两个相同外部标识符的请求,看看是返回重复错误还是创建第二个实体。文档承诺和实际行为的分歧比我们希望的更常见。
重试前读取
如果服务器能按你的外部标识符或参数搜索实体(例如按时间和金额过滤的订单列表),那么每次重试前做一次检查请求:是否已经出现了带我的特征的订单?这不能提供严格保证(检查和重试之间可能闪过窗口),但能把重复概率降低一个数量级。方案:
- 第一次尝试以不确定告终。
- 等待足够服务器完成处理的间隔。
- 执行 GET,按外部标识符或唯一字段组合过滤。
- 如果找到订单——记录其标识符,不需要重试。
- 如果没找到——重试 POST。
为了搜索有效,在订单中留下可查找的标记:注释、自定义字段、唯一的位置编号。即使服务器忽略它作为键,它也会在响应中返回,你就能核对。
把操作拆分为预留和确认
有些 API 支持两阶段模型:先创建草稿或预占(可以安全重试或取消的操作),然后按草稿标识符确认。按标识符确认本身是幂等的:同一个草稿不能确认两次。如果这种模型可用,它比单步创建更可取,即使有键,因为它缩小了最危险步骤的不确定性窗口。
你这边的 Outbox 模式
即使服务器什么都不保证,你也能保证从你这边每个操作只带一个意向发出。事务性 Outbox 是一张外发操作表,记录与业务变更(例如把购物车转为“结算中”状态)在同一事务中写入。单独的发送进程从 Outbox 取出记录并通过代理执行请求。每条记录有唯一标识符,用作键或 external_id。即使发送者在工作中途崩溃,记录仍留在 Outbox,重试会带同一个标识符。
核对作为最后一道防线
核对(Reconciliation)是定期比较你的操作列表与合作伙伴实体列表并找出差异的流程:合作伙伴有但你没有关联的订单;状态为 unknown 的操作;特征匹配的重复。核对不能防止重复,但能在几分钟内发现它,而不是一个月后通过财务报表。对于通过不稳定通道的操作,这是必需组件,不是可选项。
实践:对超过最大重试超时的操作每 10–15 分钟运行一次核对,自动把发现的实体关联到 unknown 记录,把发现的重复送到取消队列,如果金额超过阈值则人工确认。
Saga 与补偿
如果订单是操作链的一部分(库存预留、支付、配送),一个环节的重复会破坏整条链。Saga 模式假设每个步骤都有补偿动作:取消订单、退款、释放预留。补偿也必须是幂等的,否则你会与取消操作的重复作斗争。设计集成时,立即写出“动作—补偿”对,并验证两者的重试都是安全的。
常见错误:团队如何自己制造重复
错误 1:键在 HTTP 客户端内部生成
最常见。HTTP 库的包装器每次调用都用新 UUID 添加 Idempotency-Key 头。同一个库内部的重试机制再次发送——得到新键。表面上一切看起来正确:头都在。实际上没有保护。通过服务器或代理日志检查重复时键是否相同。
错误 2:“修正”请求时键随请求体一起改变
客户端因无效字段收到 400,修正字段后用同一个键重试。带指纹检查的服务器会返回 422。没有指纹检查的服务器会返回缓存的 400 错误,客户端就会撞墙。修正后的请求是新操作,需要新键。
错误 3:通过 SELECT 检查键,然后 INSERT
上面分析过,但再重复一次:读取和写入之间并行重复能钻过去。通过代理工作时尤其常见,因为客户端超时产生的重试间隔只有几秒,而订单处理也差不多这么久。只有原子预留才行。
错误 4:按 IP 或会话做幂等
服务器“记住”这个 IP 刚有过相同请求,于是拒绝重复。移动代理轮换时重复来自另一个地址,保护失效。反向也糟糕:来自同一个代理地址的合法不同订单(一个 IP 后面有很多客户)会被当作重复拒绝。键必须是显式的并由客户端传递。
错误 5:TTL 太短
键只活五分钟,“以免弄脏 Redis”。网络故障持续二十分钟。重试队列半小时后才到达操作。键已忘,订单第二次创建。TTL 必须覆盖延迟重试的最长现实场景。
错误 6:缓存基础设施错误
第一次尝试因数据库临时不可用返回 500。服务器按键保存了 500 作为结果。后续所有重试都从缓存得到 500,尽管数据库早已恢复。客户端不得不改键,失去与原始操作的联系。只能缓存确定性结果。
错误 7:折叠 unknown 状态
尝试耗尽后,客户端把操作标为 failed,允许用户重新下单。但服务器第一次操作执行了。用户得到两个订单和两次扣款。unknown 状态必须显式存在,并通过核对解决,而不是乐观假设。
错误 8:“因为更简单”而重试非幂等操作
通用重试层对所有请求一视同仁地重复,包括没有键的 POST。这在第一次网络风暴之前一直有效,之后一小时内出现数百个重复。重试层必须知道哪些请求允许重复,并拒绝在没有显式键的情况下重试非幂等请求。
错误 9:一个键用于整个批次
客户端用一个键发送一百个订单的数组。服务器处理了六十个后崩溃。同一键的重试得到 409 或部分快照。怎么知道需要创建哪四十个?批次要么每个位置一个键,要么服务器保证整个批次原子性,要么返回逐项状态的响应。没有这些,通过不稳定通道的批次就是混乱之源。
错误 10:日志中没有键
重复发生了,你试图弄清这是同一个键的重试(服务器 bug)还是两个不同操作(客户端 bug)。日志里没有键。调查变成猜谜。键必须在两边的每一行日志中,如果代理服务支持请求头日志,也要在代理日志中。
实现工具与资源
客户端
- 标识符库。 UUIDv7 和 ULID 生成器在所有主流语言中都有。如果键进入服务器数据库索引,选择能保证毫秒内单调性的。
- 带独立超时的 HTTP 客户端。 确保你的客户端能分别设置连接代理的超时和读取响应的超时。大多数现代客户端都能做到,但默认常常是统一超时。
- 有投递保证的队列。 实现 Outbox 可以用任何有处理确认的消息代理系统。重要的是消息标识符在重复投递之间稳定——它便于作为键的基础。
- 代理管理 API。 优质的移动代理服务有编程接口,可以了解通道状态、距离轮换的时间、按请求更换 IP。与这个 API 集成可以在轮换前不启动关键操作,并有意识地更换尝试之间的路由。
服务器
- 带唯一索引的关系数据库。 如果容量允许,键存储最可靠的方案。带冲突处理的插入是开箱即用的原子操作。
- Redis 或类似系统。 用于高负载系统:带 NX 和 EX 标志的 SET 用于预留,单独的键用于响应快照。注意节点故障时的数据丢失风险,配置持久化。
- 幂等中间件。 流行 Web 框架有现成的中间层,实现基本契约:预留、指纹、快照。检查它们在并发重试和执行与固化之间崩溃时的行为——好实现和形式实现在这里分道扬镳。
- API 网关。 有些网关能按入口请求头去重。这减轻了应用负担,但网关通常不知道业务结果,可能缓存基础设施错误。用作第一道过滤器,不要作为唯一保护。
测试
- 网络故障注入。 能断开请求发送后但响应前的连接、让响应超过超时、返回 502 和 504 的代理测试工具。没有这样的测试,你无法看到系统在唯一重要场景中的行为。
- 并发测试。 用同一个键同时发送 N 个请求。预期结果:恰好创建一个实体,N-1 个 409 或快照响应。任何其他结果都是缺陷。
- 操作中重启测试。 在创建订单后但固化键之前杀死进程。检查挂起记录恢复机制是否生效。
- 轮换测试。 第一次尝试通过一个 IP,重复通过另一个。检查服务器返回了快照,而不是用启发式拒绝重复。
标准与文档
IETF 关于 Idempotency-Key 头的规范草案是制定契约的起点:其中定义了头名称、冲突语义和建议的响应码。大型支付提供商的公开文档是描述外部集成者契约的好范例:TTL、请求体不匹配时的行为、并发请求处理。HTTP 语义规范中关于幂等方法的部分解释了为什么 PUT 和 DELETE 可以重复而 POST 不行,设计端点前值得重读。
案例与结果
案例 1:订单聚合器和每月 47 个重复
一家聚合公司通过每五分钟轮换的移动代理池向物流合作伙伴系统传递订单。每天约 1.2 万订单。没有幂等键:合作伙伴 API 没有文档。重复每月通过财务核对发现一次,每个平均花费 900 卢布用于取消、退款和人工处理。
代理日志诊断显示:0.4% 的请求在发送请求体后、收到响应前以连接断开告终,主要发生在轮换分钟。三秒后重试,30% 的情况下第一次尝试此时已经执行。计算与观察到的重复一致。
分三步解决。第一,发现合作伙伴 API 接受 external_id 字段并按它拒绝重复,尽管文档只提了一行。开始用本地 Outbox 的稳定标识符填充。第二,轮换窗口与发送同步:轮换前 15 秒不发送新订单。第三,每 10 分钟添加核对。季度结果:零重复,通过同步轮换重试次数降低 70%,平均下单时间因等待窗口增加 1.2 秒——可接受的代价。
案例 2:支付服务和并发重试
一家金融科技服务在自己这边实现了幂等性:接受头,把键保存到数据库,重复时返回快照。重复仍然出现,很少但规律:大约每 4 万次操作一次。调查发现键检查通过读取然后写入进行,而超时激进的客户(一秒内通过不同代理两次重试)钻进了它们之间的窗口。
改为带唯一索引的插入,并添加 in_progress 状态,响应 409 和一秒 Retry-After 头。添加并发重试指标。它显示了意外情况:2% 的操作至少收到一个 409,也就是说客户端的重试比预期激进得多。服务更新了超时建议文档,两个月后 409 比例降到 0.3%。半年内零重复。
案例 3:市场平台集成和批次
卖家通过代理以 500 个位置为一批上传库存和价格到市场平台。批次幂等性在整个请求层面。连接断开时,重试要么被拒绝(批次进行中),要么返回部分结果的快照,无法知道哪些位置更新了。卖家得出“没更新”的结论重新上传,造成新旧批次之间的竞争。
解决方案:改用带逐项操作标识符的批次,在不确定完成后请求逐项状态。批次大小降到 100 个位置,使处理时间不超过超时。“挂起”更新从每天几十个降到零,以前经常导致买家订单取消的库存差异也消失了。
案例 4:自动化代理和链式重试
2026 年趋势:越来越多的集成由基于大语言模型的自主代理执行,按指令调用 API。一个团队部署了这样的代理来向供应商下采购单。代理在不确定响应时“推理”并决定重复操作,生成新请求。没有键,因为代理每次都重新形成调用。第一周——11 个重复采购。
修复:禁止代理直接形成创建请求。它通过内部工具在 Outbox 创建意向记录,发送由带键和核对的确定性服务执行。代理只收到最终状态。重复消失,同时获得了谁为什么发起每次采购的完整追踪。总体结论:有重试能力的自主系统是重复的新强大来源,对它们必须设置幂等性屏障。
FAQ:关于幂等性和重试的复杂问题
如果 PUT 和 DELETE 按规范是幂等的,还需要幂等键吗?
形式上不需要:相同请求体的 PUT 重复会得到相同状态。但有细微差别。如果 PUT 创建时返回 201、更新时返回 200,重复会返回不同状态码,客户端可能不同地解释。DELETE 重复会返回 404 而不是 204,通常被当作错误处理。带响应快照的键使行为可预测。此外,如果 PUT 引起副作用(发送通知、写审计),它们会重复执行。方法幂等不等于所有副作用幂等。
如果服务器返回 409 in_progress,而第一次尝试实际上已经死了,怎么办?
这是服务器的责任:它必须有带时间阈值的挂起记录恢复机制。客户端应该等待 409 有限次数(例如最多两分钟),然后把操作转为 unknown 并交给核对。如果服务器系统性地让 in_progress 持续超过合理时间,这是实现缺陷,应告知 API 所有者。
如果请求经过链中的多个代理,键怎么办?
不需要特别处理:键在请求头中传递,透明通过任何链路。唯一要检查的是某个中间节点是否删除非标准头。有些企业网关按白名单过滤头。简单测试:通过整个链路向自己的调试端点发送请求,确认头到达了。
可以把请求体哈希作为键而不在客户端存任何东西吗?
可以,但有条件。两个内容相同的不同订单(同一商品、同一金额、同一买家)会得到同一个键,第二个会被当作重复拒绝。为避免这一点,在请求体中加入唯一组件——购物车标识符或本地序号。那么请求体哈希就成为操作的确定性键。这种方法适合没有可靠本地存储的客户端,但需要严格规范化请求体:JSON 字段顺序变化会改变哈希。
重试前等多久才能让服务器完成第一次尝试?
这是重试策略问题,但从契约角度看重要的是:如果服务器支持 in_progress 和 409,就不需要“凭感觉”等待——服务器自己会告知操作仍在执行。如果服务器没有这种状态,重试前的间隔必须超过服务器操作处理时间的 99 百分位。可以从文档、成功请求的指标或测试环境经验中了解。
读操作也应该幂等吗?
GET 按定义是幂等的,不需要键。但有一个例外:带副作用的“读”,例如把通知标记为已读或扣除配额。这是架构异味;这类操作最好改成带键的 POST,而不是给 GET 硬加幂等性。
迁移或 API 版本变更时键怎么办?
在服务器端把端点版本包含在键的作用域中。那么 v1 中使用的键不会与 v2 中的同一个键冲突。对客户端规则很简单:迁移是新操作带新键,旧键不迁移。如果迁移时操作处于 unknown,先用核对解决它,再迁移。
如果重复“几乎不发生”,如何向业务解释为什么要花一个冲刺做幂等性?
计算一个重复的成本:取消、退款、支持、声誉,有时还有合作伙伴罚款。乘以观察到的频率。然后展示频率在网络事件中非线性增长:平静的一天零重复,运营商故障的一天一小时内数百个。幂等性是保费已知、收益未知但可能巨大的保险。此外它还有副作用:可以无恐惧地激进重试,加速故障恢复。
幂等性会增加服务器负载吗?
微乎其微:每个操作多一次写入和一次读取。但它在故障场景中降低负载,因为重试在毫秒内返回快照,而不是完整处理订单。在重试风暴中,带幂等性的服务器比没有的承受得更好——这反直觉,但被实践证实。
结语:契约而不是希望
让我们总结要点。任何网络都按“至少一次”投递请求。代理——尤其是带轮换和无线信道的移动代理——让重试不是罕见现象而是常态。重试策略回答“何时以及如何重试”。幂等性回答“为什么重试不会破坏任何东西”。没有第二个答案,第一个就是危险的。
安全重试靠三根支柱。操作键,在第一次尝试前诞生,活在你的数据库里,而不是 HTTP 客户端里。服务端契约,包含原子预留、in_progress 状态、请求体指纹、响应快照和合理 TTL。核对,作为陷入不确定状态的操作的最后防线。如果服务器不提供契约,自然标识符就承担键的角色,你的 Outbox 就承担存储的角色。
今天就可以做的事:
- 在你的集成中找到所有会自动重复的 POST 操作。对每一个回答:有没有键,在哪里生成,重试时是否相同。
- 阅读合作伙伴 API 文档中关于 external_id 字段和 Idempotency-Key 头的内容。在测试环境用两个相同请求检查行为。
- 在操作模型中加入 unknown 状态以及针对它的核对流程。
- 如果你拥有服务器,跑三个测试:并发重试、执行与固化之间崩溃、从另一个 IP 重试。
- 在仪表盘上展示重试与唯一操作的比例。这是通过代理的通道健康指标。
幂等性是工程纪律直接转化为业务安宁的罕见例子。一次设计好的契约能多年防止重复、重试风暴和财务部门的深夜电话。而且说实话,看着通过不稳定通道的数千次重试图表,在重复一栏看到坚定的零,有一种特别的满足感。