1. 从一次线上事故说起超时重试为什么总在制造重复工单凌晨两点被电话叫醒运维群里甩过来一张截图同一个用户反馈的故障工单系统里躺着七条内容几乎一模一样的记录创建时间集中在三分钟内。值班同学的第一反应是谁在刷接口排查一圈才发现是上游那个负责自动派单的 Agent 在搞事情——它调用工单创建接口时超时了于是按重试策略又发了一次再超时再发直到拿到一个成功响应为止。这个场景在引入 Agent 做自动化处理的团队里太常见了。Agent 的本质是感知—决策—行动的循环而行动这一步往往就是调用外部工具或 API。网络抖动、下游服务 GC 停顿、数据库锁等待任何一个环节慢一点调用方等不到响应就会判定失败。问题在于超时并不等于失败。请求可能已经到达下游并被成功处理只是响应在回来的路上丢了或者下游处理得慢超过了调用方设定的等待窗口。这时候如果 Agent 无脑重试就会在下游制造出重复的副作用。工单创建是典型的非幂等副作用操作。查询接口重试一百次也没关系反正不改变状态但创建接口每成功执行一次就多一条记录。所以这个问题的核心不是怎么让重试更聪明而是怎么让重复的请求在下游被识别出来并安全丢弃。这就是幂等性设计要解决的问题。这篇内容适合正在做 Agent 工具调用、自动化工作流、任务编排的开发和运维同学。我会从超时的本质讲起拆解几种主流的幂等方案给出可以直接落地的代码结构最后聊聊那些文档里不会写、只有踩过才知道的坑。不管你是刚接触这块还是已经被重复工单折磨过几轮应该都能找到能直接抄作业的部分。2. 超时判定与真实执行结果的错位理解问题的根因2.1 超时是调用方的单方面判断很多人对超时的理解有个误区觉得超时了就是没成功。实际上超时完全是调用方视角的判断我在约定的时间内没收到响应所以我认定这次调用失败。但下游到底发生了什么调用方一无所知。下游的真实状态可能有四种请求根本没到达下游没做任何处理请求到达了下游正在处理还没处理完请求到达了下游处理完了但响应在返回途中丢失请求到达了下游处理完了响应也发出了但调用方因为网络延迟在超时窗口之后才收到。只有第一种情况是真正安全的未执行后三种里下游都已经或即将产生副作用。Agent 如果对这四种情况一视同仁地重试后三种就会变成重复操作。2.2 重试放大效应为什么一次抖动变成七条工单单看一次超时重试最多产生两条记录。但实际系统里往往叠加了多层重试Agent 框架层有自己的重试HTTP 客户端库有重试网关有重试甚至下游服务内部调用其他服务时还有重试。这些重试策略如果各自为政次数就会相乘。我见过的一个真实配置是Agent 层重试 3 次HTTP 客户端重试 2 次网关重试 2 次理论最大请求数就是 3×2×212 次。再叠加并发场景下多个 Agent 实例同时处理同一批任务重复量级就更夸张。所以解决重复工单不能只盯着某一层的重试开关要从整体链路上做幂等兜底。2.3 幂等键让重复请求自己暴露身份幂等设计的核心思路是给每次业务意图分配一个唯一标识也就是幂等键idempotency key。同一个业务意图无论被提交多少次只要带着同一个幂等键下游就能识别出这是同一个操作从而只执行一次。关键在于幂等键的生成时机和粒度。它必须在第一次调用之前就确定下来并且在所有重试中保持不变。如果每次重试都重新生成一个键那幂等机制就完全失效了。粒度上一个幂等键对应一次业务操作而不是一次 HTTP 请求。比如为用户 A 创建一条关于故障 B 的工单是一个业务意图对应一个键如果用户 A 又反馈了故障 C那是另一个业务意图要用新的键。3. 幂等键的生成策略与生命周期管理3.1 键从哪来业务标识 vs 随机 UUID幂等键的生成有两种主流思路各有适用场景。第一种是基于业务字段派生。比如用用户ID 故障类型 时间窗口拼出一个确定性字符串再做哈希。这种做法的好处是天然去重即使 Agent 完全重启、状态全丢只要业务参数一样算出来的键就一样重复请求照样能被拦住。缺点是业务字段的选择很讲究选多了容易把本该合并的请求拆开选少了又会误伤不同的业务意图。第二种是随机生成 UUID。Agent 在决定执行某个操作时生成一个 UUID把它和请求一起发出去重试时复用同一个 UUID。这种做法简单直接不依赖业务字段的语义但要求 Agent 必须把生成的键持久化下来——如果 Agent 在处理过程中崩溃重启内存里的键丢了重新生成的键就和之前的不一样幂等就失效了。我的建议是两者结合用业务字段派生一个业务指纹作为主键的一部分再拼上一个在任务开始时生成并持久化的随机后缀。这样既能抵御 Agent 重启又能区分同一业务字段下的不同批次操作。3.2 键的存储位置别放在内存里幂等键必须在重试期间保持可用所以它的存储位置很关键。放在进程内存里是最脆弱的方案进程一重启就没了。放在本地文件里稍好但多实例部署时会各存各的无法共享。生产环境推荐放在外部共享存储里比如 Redis 或数据库。Agent 在发起调用前先把幂等键写入存储标记为进行中调用成功后再更新为已完成。重试时先查这个键的状态如果已经是已完成直接返回上次的结果不再真正调用下游。这里有个细节写入幂等键和调用下游之间存在时间窗口如果 Agent 在写入键之后、调用下游之前崩溃重启后会看到一个进行中的键但它其实没真正调用过。所以进行中状态需要配合超时机制超过一定时间还停留在进行中的允许重新执行。3.3 键的过期与清理幂等键不能永久保存否则存储会无限膨胀。过期时间要覆盖最坏情况下重试可能持续的时间。如果 Agent 的重试策略是最长持续 10 分钟那幂等键至少保留 10 分钟以上通常留 24 小时比较稳妥给人工介入和延迟重试留足空间。清理策略上可以用 Redis 的 TTL 自动过期也可以在数据库里定期归档。要注意的是过期时间不能太短。我踩过一个坑把幂等键 TTL 设成了 5 分钟结果有个任务因为下游排队严重重试间隔拉长到 6 分钟第二次重试时键已经过期下游又创建了一条重复工单。后来把 TTL 统一调到 24 小时这类问题就再没出现过。4. 下游服务的幂等接收把判断权交给数据层4.1 唯一约束最可靠的最后一道防线不管 Agent 侧做多少幂等控制最可靠的兜底永远在数据层。给工单表加一个基于幂等键的唯一索引重复插入时数据库会直接报唯一约束冲突下游捕获这个异常后返回已存在的结果即可。ALTER TABLE work_order ADD COLUMN idempotency_key VARCHAR(128), ADD UNIQUE KEY uk_idempotency (idempotency_key);这个方案的好处是绝对可靠不依赖任何应用层逻辑并发场景下也不会漏。缺点是它只能防插入这类操作对于更新类的副作用唯一约束就无能为力了得靠别的机制。4.2 先查后插的竞态问题很多团队的第一反应是插入前先查一下有没有。这个思路在低并发下能用但高并发下会出问题两个请求同时查询都发现不存在然后都执行插入结果还是两条。要解决这个竞态要么依赖数据库的唯一约束让数据库来保证原子性要么用分布式锁把查插包成一个原子操作。分布式锁的实现成本更高还要处理锁超时、锁误删等问题所以能用唯一约束就用唯一约束。4.3 状态机让重复请求落到合法状态对于更新类操作可以用状态机来兜底。比如工单有待处理→处理中→已完成的状态流转重复的开始处理请求到达时如果工单已经是处理中就直接返回当前状态不再重复执行副作用。状态机的关键是定义清楚每个状态允许的转换以及重复转换时的处理策略幂等返回还是报错。5. 重试策略的精细化设计不是所有超时都该重试5.1 区分可重试与不可重试的错误超时只是错误的一种。Agent 拿到的错误类型至少有这么几类错误类型典型表现是否可重试连接超时连不上下游可重试读超时连上了但没等到响应谨慎重试需幂等保护4xx 客户端错误参数错误、鉴权失败不可重试5xx 服务端错误下游内部异常视情况需幂等保护限流错误429可重试但要退避读超时是最危险的因为下游很可能已经执行了。所以读超时的重试必须配合幂等机制不能裸重试。5.2 指数退避与抖动重试间隔不能是固定的否则多个 Agent 实例会在同一时刻一起重试形成脉冲流量把下游打垮。标准做法是指数退避第一次等 1 秒第二次 2 秒第三次 4 秒以此类推再叠加一个随机抖动。import random import time def backoff_delay(attempt, base1.0, cap60.0): delay min(cap, base * (2 ** attempt)) # 加入 ±20% 的抖动避免重试风暴 jitter delay * 0.2 * (random.random() * 2 - 1) return delay jitter抖动这一步很多人会忽略但在多实例场景下它是防止重试同步的关键。5.3 重试预算给整个链路设一个总上限单次调用的重试次数好控制难的是整个任务链路的总重试量。一个 Agent 任务可能调用十几个工具每个都重试几次累积起来就很可观。可以引入重试预算的概念给每个任务分配一个总的重试次数或总时间预算任何一次重试都从这个预算里扣扣完就不再重试直接失败上报。这样做的好处是避免某个环节的持续失败拖垮整个任务也避免无限重试消耗资源。6. 实战落地一套可复用的幂等调用封装6.1 整体结构设计把幂等逻辑封装成一个统一的调用器Agent 的所有工具调用都走这个调用器而不是各自实现。调用器的职责包括生成或复用幂等键、查询键状态、执行调用、更新键状态、处理重试。class IdempotentInvoker: def __init__(self, store, max_retries3): self.store store # 幂等键存储如 Redis self.max_retries max_retries def invoke(self, idempotency_key, func, *args, **kwargs): # 1. 查状态 state self.store.get(idempotency_key) if state completed: return self.store.get_result(idempotency_key) if state in_progress: # 可能上次执行到一半崩了检查是否超时 if not self.store.is_stale(idempotency_key): raise ConcurrentExecutionError(idempotency_key) # 2. 标记进行中 self.store.set(idempotency_key, in_progress) # 3. 带重试地执行 last_error None for attempt in range(self.max_retries): try: result func(*args, **kwargs) self.store.set(idempotency_key, completed) self.store.set_result(idempotency_key, result) return result except RetryableError as e: last_error e time.sleep(backoff_delay(attempt)) except NonRetryableError: self.store.delete(idempotency_key) raise self.store.delete(idempotency_key) raise last_error6.2 幂等键的传递HTTP 头还是请求体如果下游是 HTTP 服务幂等键通常放在请求头里比如Idempotency-Key。这是业界比较通行的做法好处是不污染业务请求体下游可以统一在中间件层处理。如果下游是 RPC 或消息队列就把键放在消息的元数据字段里。不管放哪里关键是下游必须能读到这个键。我见过有的团队在 Agent 侧辛辛苦苦生成了键结果下游接口根本没接收这个字段等于白做。所以联调时一定要确认键能端到端传下去。6.3 结果缓存让重试直接返回上次结果幂等不只是不重复执行还包括重复请求返回一致的结果。如果第一次调用成功创建了工单返回了工单 ID第二次重试时应该返回同一个工单 ID而不是报错说已存在。所以幂等存储里不仅要记状态还要记结果。结果缓存要注意序列化问题。如果结果是复杂对象要能序列化成字符串存进去取出来再反序列化。同时要控制缓存大小避免大结果把存储撑爆。7. 那些文档不会写的坑并发、时序与监控7.1 并发请求同时到达的窗口即使有幂等键两个请求几乎同时到达下游时仍然可能都通过了查状态这一步然后都去执行。这时候唯一约束就是最后防线。所以幂等键查询和唯一约束要配合使用不能只靠其中一个。如果下游没有唯一约束就得用分布式锁。锁的粒度要细到幂等键级别不能用一个全局锁否则并发性能会很差。7.2 幂等键生成后、写入前崩溃这个窗口很窄但确实存在。Agent 生成了键还没来得及写入存储就崩溃了重启后重新生成一个不同的键重复请求就漏过去了。要彻底解决得让键的生成和持久化在一个原子操作里完成或者让键的生成完全确定化基于业务字段派生这样重启后算出来的键还是一样的。7.3 监控指标怎么知道幂等机制在起作用光有机制不够还得能观测。建议埋这几个指标幂等命中次数有多少请求被幂等机制拦下了这个数字直接反映重复请求的规模幂等键冲突率冲突率高说明上游重试频繁要回头查重试策略唯一约束冲突次数这是最后防线被触发的次数理想情况下应该接近零如果很高说明前面的幂等控制有漏洞。把这些指标接到告警上一旦冲突率突增就能第一时间发现重试风暴。7.4 一个容易被忽略的细节日志里的键排查重复工单问题时最痛苦的是不知道哪几条记录来自同一次业务意图。如果每条工单记录里都存了幂等键排查时直接按键分组一目了然。所以幂等键不仅要用于去重还要落库、进日志作为可观测性的一部分。我在实际项目里养成的习惯是任何有副作用的调用日志里必须带上幂等键和调用来源哪个 Agent 实例、哪次任务。这样出问题时五分钟就能定位到根因而不是花两小时翻日志。8. 从工单场景延伸这套思路还能用在哪幂等这套东西不只适用于工单创建。凡是Agent 调用外部工具产生副作用的场景都能套用支付扣款、消息推送、文件生成、库存扣减、状态变更。区别只在于幂等键怎么派生、唯一约束加在哪、结果怎么缓存。比如支付场景幂等键通常用订单号唯一约束加在支付流水表上消息推送场景幂等键用用户ID消息模板ID业务时间窗口避免同一活动给同一用户重复推送。核心逻辑是一样的先确定业务意图的唯一标识再让下游能识别并安全处理重复。真正难的不是技术方案而是团队有没有形成凡副作用必幂等的意识。我见过太多项目功能跑通了就上线等出了重复数据才回头补幂等那时候数据已经脏了清理成本远高于一开始就设计好。所以如果你正在做 Agent 相关的开发建议在写第一个工具调用的时候就把幂等框架搭起来后面所有调用都走统一封装省心得多。