幂等是靠什么实现的？幂等键，每一步都讲透

大模型智能体的网络抖了一下，同一笔请求发了两遍，多扣一次款、多建一条单都是事故，幂等键就是防这个的——服务端靠它认出重复请求并只执行一次。这篇把幂等键兜住重试的原理讲透。

同一笔请求发了两次怎么办

先说结论：重复无法杜绝，只能保证重复不产生第二次效果。超时重试是所有分布式系统的日常——请求发出去了，回应没回来，发还是不发？不发可能漏，重发可能重。幂等给的答案是：放心重发，服务端自会识别这是同一笔，已处理过就直接返回上次的结果，不再执行第二遍动作。

幂等键的生成与传递

幂等键是一枚唯一凭据，由发起方在首次请求前生成——通常是随机或按任务派生的不重复标识，随请求一并发出。关键规矩是：同一个动作，重试时必须带着同一枚键；换了动作，键也要换。键用错了地方，防重就失效：新任务复用旧键，会被误判为重复而拒绝执行，效果比没有幂等还糟。通义千问、豆包的开发平台在接口文档里都强调写操作的幂等要求，规矩是相通的。

服务端怎么认出重复请求

服务端按键查登记簿：这枚键见过且已成功，直接返回原结果；见过但还在处理中，返回处理中状态让调用方稍候；没见过，登记后正常执行。登记簿本身要防并发——两笔同键请求同时到达，只能有一个获得执行权，另一个等待或返回进行中，并发控制的细节见多个工具是怎么并行调用的。窗口期的长短、登记簿的清理节奏，都是工程实现的细节功课。

同键请求进来，服务端按登记簿的三种状态分流：

超时重试为什么离不开它

回看前面的问题：回应没回来时重发，正因为带着同一枚键，重发才变得安全。没有幂等键的重试，等于每次都开新单，重试机制越激进，事故越多。这也是为什么工具调用失败是怎么重试的里的退避策略总把幂等列为前提——两者是一对搭档：键负责兜底，退避负责节奏，缺了哪个都不完整。执行失败后的补救则交给补偿事务是怎么回滚的，那是另一道兜底工序。

幂等自查清单：写操作是否都带了幂等键；重试是否复用同一枚键；服务端是否登记了处理结果；登记簿是否有清理节奏。四条都过，重试才敢放开手。

最后给个记忆锚点：幂等回答的是「做过了就是做过了」。它不追求不重复，只追求重复无害——理解了这句，重试、防重、回滚这些机制在你眼里就串成了一条线。

幂等范围的边界与嵌套

幂等并非无限保障：它只保证同一动作不被执行两遍，不保证动作本身的正确性——第一次就发错了收款对象，幂等会忠实地只错一次。范围也要划清：一次任务里连续三个写入动作，各自带各自的键，互相独立；若把整段任务当作一个动作做幂等，中间某步失败后整段重跑，又要靠步骤级凭据防止内部重复。嵌套场景里外层键与内层键各管各的层级，登记簿分开记，才不会互相误判。另外，返回结果的缓存与幂等登记要区分开：前者为了省算力，后者为了保证不重复，混在一个机制里早晚出问题。幂等键还有一个使用细节：请求体内容变更时要不要换键，各家约定不同，接入前先读平台的接口文档，按它的规矩来，别凭感觉自创一套。键的命名也建议带上任务与步骤前缀，排查时一眼能看出是哪个环节发的。

关于幂等键再多问三句

• 查询类请求需要幂等键吗？：查询天然无害，可以不带；凡是产生写入或扣减的动作都必须带。
• 幂等键由谁生成更合适？：发起方生成，因为只有它知道「这是同一个动作的重试」，服务端只负责登记比对。
• 登记结果保留多久？：覆盖重试可能发生的最大时间窗即可，过期清理，避免登记簿无限膨胀。