1. 从一个真实故障场景说起工单系统对接智能 Agent 这件事这两年落地的团队越来越多。我参与过的一个客服自动化项目里Agent 负责识别用户意图、判断是否需要建单、然后调用工单服务的创建接口。上线头两周一切正常第三周开始陆续收到用户投诉同一个问题被建了两张甚至三张工单客服重复跟进用户被反复打扰。翻日志才发现根因很典型Agent 调用创建工单接口时网络抖动或者工单服务响应慢客户端等到了超时时间就抛异常。Agent 的编排逻辑捕获到异常后按照失败就重试的默认策略又发起了一次调用。但问题在于——第一次请求其实已经到达服务端并且成功创建了工单只是响应在回程路上丢了。于是重试变成了重复创建。这个问题的本质是分布式系统里经典的超时≠失败。超时只代表客户端没有在预期时间内拿到结果服务端到底执行没执行、执行到哪一步客户端一无所知。Agent 工具调用场景把这个矛盾放大了因为 Agent 的重试往往是自动的、高频的、甚至并发的一旦没有幂等保护重复副作用就会成倍出现。这篇内容就是围绕Agent 工具调用超时后如何避免重复创建工单展开把幂等设计的完整思路、参数计算、代码实现、排查技巧都拆开讲清楚。适合正在做 Agent 工具集成、工单系统对接、或者任何有副作用接口调用的后端和平台同学参考。不管你是刚接触幂等概念的新手还是想系统梳理一遍的老手应该都能拿到可以直接抄作业的东西。2. 为什么超时重试一定会踩重复创建的坑2.1 超时语义的三种真实状态很多人下意识把超时等同于失败这是所有重复创建问题的思想根源。实际上一次超时的调用服务端可能处于三种状态之一服务端真实状态客户端感知直接重试的后果请求根本没到达超时重试成功无副作用请求到达但未执行完超时重试可能并发执行两次请求已执行完响应丢失超时重试导致重复创建只有第一种情况重试是安全的。第二、三种情况下盲目重试就会产生重复工单。而客户端在没有额外机制的情况下根本无法区分这三种状态。这就是为什么幂等不能靠判断要不要重试来解决只能靠让重复调用不产生重复副作用来解决。2.2 Agent 场景把风险放大了普通人工点击创建工单用户看到转圈会等一等重复点击的概率低。但 Agent 不一样重试是自动的编排框架通常内置重试策略指数退避、固定间隔都有人不会盯着。可能并发有些 Agent 会并行调用多个工具或者多个子任务同时触发建单。链路更长Agent 到工具网关、到工单服务中间可能经过好几跳任何一跳超时都会触发上游重试。缺乏人工兜底没有客服肉眼判断这张单是不是已经建过了。所以 Agent 场景对幂等的要求比人工场景高一个量级。你不能指望重试前先查一下有没有建过这种朴素方案因为查询和创建之间有时间窗口并发下照样重复。2.3 幂等键是唯一可靠的抓手真正可靠的方案只有一个方向让每一次逻辑上的创建意图携带一个全局唯一的标识服务端基于这个标识做去重。这个标识就是幂等键idempotency key。它的工作方式很像快递单号不管你打几次电话催单只要单号是同一个系统就知道这是同一件事不会给你发两次货。幂等键由调用方生成随请求一起发送服务端收到后先查这个键有没有处理过处理过就直接返回上次的结果没处理过才真正执行。关键点在于幂等键必须在第一次调用之前就生成好并且在所有重试中保持不变。如果每次重试都生成新的键那幂等就完全失效了。这是新手最容易犯的错误后面会专门讲怎么保证这一点。3. 幂等方案的整体设计与选型考量3.1 三种主流方案的取舍围绕工单创建这个具体场景业界常见的幂等实现有三类各有适用边界方案一数据库唯一索引。在工单表上对幂等键建唯一索引插入冲突就说明重复。优点是实现简单、强一致、不依赖外部组件。缺点是幂等键会占用业务表空间且如果工单表已经很大加唯一索引有锁表风险。适合中小规模、工单表可控的场景。方案二独立幂等表 状态机。单独建一张幂等记录表记录 key、状态处理中/成功/失败、结果快照。创建前先插入幂等记录插入成功才继续建单。优点是职责清晰、可以记录中间状态、支持处理中的并发拦截。缺点是多一次写库需要处理幂等表本身的清理。适合对可靠性要求高的场景。方案三Redis 分布式锁 结果缓存。用 Redis 的 SETNX 做互斥把结果缓存起来。优点是性能高、天然支持过期。缺点是 Redis 不是强一致存储主从切换可能丢数据且缓存过期后幂等保护就消失了。适合对性能敏感、能容忍极小概率重复的场景。我的建议是方案二为主方案一作为兜底。也就是幂等表负责拦截和状态管理工单表上的唯一索引作为最后一道防线。两层保护任何一层生效都能挡住重复。Redis 方案我不太推荐单独用在工单这种有真实业务副作用的场景因为它的可靠性等级和不能重复建单这个要求不太匹配。3.2 幂等键怎么设计才靠谱幂等键的设计直接决定方案成败。几个原则全局唯一不同业务、不同租户、不同时间都不能撞。推荐用 UUID v4 或者业务前缀 雪花 ID。可复现同一个逻辑意图在重试时必须能生成同一个键。所以键不能包含随机数、时间戳这类每次都变的东西除非你在第一次生成后就把它持久化下来。长度可控建议控制在 64 字符以内方便建索引和传输。可追溯键里最好能看出业务来源比如ticket:create:{tenant}:{uuid}排查问题时一眼能定位。这里有个容易忽略的点幂等键的生成位置。如果 Agent 编排层生成键然后传给工具调用层那重试时只要复用同一个键就行。但如果键是在工具调用层内部生成的重试时就会生成新键幂等失效。所以键的生成必须发生在重试逻辑的外层也就是一次逻辑调用的起点。3.3 状态机设计处理中、成功、失败幂等表不能只记有没有处理过还要记处理到哪一步了。我通常设计三个状态PROCESSING已占位正在执行。这个状态用来拦截并发重复请求。SUCCESS执行成功结果已落库。重复请求直接返回缓存的结果。FAILED执行失败且确认没有产生副作用。重复请求可以重新执行。状态流转的关键在于只有确认无副作用时才能标记 FAILED。如果建单过程中超时服务端自己也不知道工单建没建成这时候不能简单标 FAILED否则重试又会重复建。正确做法是标记为 PROCESSING 并设置一个较短的过期时间让后续请求要么等待、要么走对账补偿。4. 核心实现细节与参数计算4.1 幂等表的字段设计一张够用的幂等表大概长这样CREATE TABLE idempotency_record ( id BIGINT PRIMARY KEY AUTO_INCREMENT, idem_key VARCHAR(64) NOT NULL, biz_type VARCHAR(32) NOT NULL, status TINYINT NOT NULL DEFAULT 0, -- 0处理中 1成功 2失败 result_snapshot TEXT, -- 成功后的结果JSON created_at DATETIME NOT NULL, updated_at DATETIME NOT NULL, expire_at DATETIME NOT NULL, UNIQUE KEY uk_idem_key (idem_key) ) ENGINEInnoDB;几个字段的用意说明一下。idem_key上的唯一索引是并发拦截的核心两个请求同时插入只有一个能成功另一个直接拿到唯一键冲突异常就知道自己该走已存在分支。result_snapshot存成功后的结果重复请求直接返回它避免重复查询业务表。expire_at用于定期清理幂等记录不需要永久保留一般保留 7 到 30 天足够覆盖所有可能的重试窗口。4.2 过期时间的计算逻辑过期时间设多长取决于你的重试窗口有多长。假设 Agent 的重试策略是最多重试 5 次间隔按指数退避 1s、2s、4s、8s、16s那么总重试窗口约 31 秒。但还要考虑人工介入、消息队列积压、定时补偿等情况实际窗口可能拉长到几小时甚至一天。我的经验公式是幂等记录保留时长 最大重试窗口 × 安全系数建议 3~5 倍 对账补偿周期如果重试窗口是 1 小时对账补偿每天跑一次那保留时长至少 1×3 24 27 小时取整 48 小时比较稳妥。对于工单这种业务我一般直接设 7 天成本可忽略换来的是几乎不会因为记录过期而重复建单。4.3 并发拦截的时序把并发场景走一遍看看幂等表怎么挡住重复请求 A 到达尝试插入idem_keyK状态 PROCESSING插入成功。请求 B重试或并发到达尝试插入同一个 K唯一键冲突。请求 B 捕获冲突查询 K 的当前状态。如果状态是 PROCESSINGB 可以选择短暂等待后重查或者直接返回处理中请稍后。如果状态是 SUCCESSB 直接返回result_snapshot。如果状态是 FAILEDB 可以尝试重新执行需要先原子地把状态改回 PROCESSING。这个时序里第 4 步的等待后重查是很多实现会偷懒的地方。直接返回处理中对 Agent 来说体验不好因为它可能又触发一次重试。更好的做法是让 B 轮询等待一小段时间比如 200ms 一次最多等 3 秒大概率 A 已经完成B 就能拿到结果。5. 完整实操流程与代码实现5.1 调用方幂等键的生成与传递先看 Agent 侧怎么生成和传递幂等键。核心原则是键在重试外层生成一次然后一路透传import uuid def create_ticket_with_idempotency(agent_context, ticket_data): # 关键幂等键在重试逻辑之外生成整个逻辑调用生命周期内不变 idem_key agent_context.get(idem_key) if not idem_key: idem_key fticket:create:{agent_context[tenant_id]}:{uuid.uuid4()} agent_context[idem_key] idem_key # 持久化到上下文重试时复用 max_retries 5 for attempt in range(max_retries): try: resp tool_client.call( ticket.create, payloadticket_data, headers{X-Idempotency-Key: idem_key}, timeout3.0 ) return resp except TimeoutError: # 超时后继续重试但 idem_key 保持不变 backoff 2 ** attempt time.sleep(backoff) continue raise Exception(create ticket failed after retries)注意agent_context[idem_key]这一步。如果 Agent 框架支持把上下文持久化比如存到会话存储里那即使 Agent 进程重启重试时也能拿到同一个键。如果上下文只在内存里进程重启后键就丢了这时候需要靠服务端的对账来兜底。5.2 服务端幂等拦截的完整逻辑服务端收到请求后先走幂等检查再走业务逻辑def handle_create_ticket(request): idem_key request.headers.get(X-Idempotency-Key) if not idem_key: raise BadRequest(missing idempotency key) # 第一步尝试占位 try: record idem_repo.insert( idem_keyidem_key, biz_typeticket_create, statusPROCESSING, expire_atnow() timedelta(days7) ) except DuplicateKeyError: # 已存在走查询分支 return handle_existing(idem_key) # 第二步占位成功执行真正的建单 try: ticket ticket_service.create(request.body) idem_repo.mark_success(idem_key, resultticket.to_dict()) return success(ticket) except BusinessError as e: # 明确的业务失败确认无副作用标记失败 idem_repo.mark_failed(idem_key, reasonstr(e)) raise except Exception as e: # 未知异常含超时不能确定有无副作用保持 PROCESSING # 交给对账任务后续处理 log.warn(funknown error for {idem_key}, keep processing) raise这里最关键的是最后那个except Exception分支。未知异常绝对不能标 FAILED因为可能工单已经建了只是响应没回来。保持 PROCESSING 状态让对账任务去查真实结果是唯一安全的做法。5.3 处理已存在记录的三种分支handle_existing要根据状态分别处理def handle_existing(idem_key): for _ in range(15): # 最多等3秒 record idem_repo.get(idem_key) if record.status SUCCESS: return success(record.result_snapshot) if record.status FAILED: # 原子地把状态改回 PROCESSING抢到的人重新执行 if idem_repo.cas_status(idem_key, FAILED, PROCESSING): return execute_business(idem_key) continue # PROCESSING等待后重查 time.sleep(0.2) return accepted(processing, please retry later)cas_status用的是数据库的乐观锁UPDATE ... WHERE statusFAILED保证只有一个请求能把 FAILED 改回 PROCESSING避免多个重试同时执行。5.4 对账补偿兜住 PROCESSING 的残留总有一些请求会卡在 PROCESSING 状态比如服务端进程崩溃、建单成功但标记状态失败。这时候需要一个定时对账任务def reconcile_stale_processing(): # 找出超过5分钟还是PROCESSING的记录 stale idem_repo.find_stale(PROCESSING, older_thannow() - timedelta(minutes5)) for record in stale: # 用幂等键去业务侧反查看工单到底建没建 ticket ticket_service.find_by_idem_key(record.idem_key) if ticket: idem_repo.mark_success(record.idem_key, resultticket.to_dict()) else: # 确认没建标记失败允许后续重试 idem_repo.mark_failed(record.idem_key, reasonreconcile: not found)这个对账任务要求工单表本身也存了幂等键这样才能反查。所以前面说方案一作为兜底就是这个意思——工单表上的idem_key字段和唯一索引既是对账的依据也是最后一道防重复的防线。6. 常见问题与排查技巧实录6.1 问题速查表现象可能原因排查方向解决手段仍然重复建单幂等键每次重试都变检查键生成位置是否在重试外层把键生成提到重试循环外并持久化大量请求返回处理中PROCESSING 残留过多查对账任务是否正常运行修复对账、缩短 PROCESSING 超时幂等表膨胀过期记录未清理查清理任务加定时清理按 expire_at 删除并发下仍重复唯一索引缺失或失效检查表结构补唯一索引确认没被误删重试拿到旧结果result_snapshot 未更新查 mark_success 是否执行修复状态更新逻辑6.2 几个踩过的坑坑一把幂等键放在请求体里而不是 header。有些网关或框架对请求体做签名、压缩、改写可能导致键被改动。放 header 更稳定也符合语义。坑二用业务字段拼幂等键。比如用用户ID问题描述拼键看起来能去重但用户同一问题在不同时间提两次是合理的会被误判为重复。幂等键应该代表一次逻辑调用意图而不是一个业务实体。坑三PROCESSING 超时设太短。设成 30 秒结果建单本身要 40 秒对账任务就会误判为残留去反查时工单还没建好标记成 FAILED然后重试又建一张。PROCESSING 超时一定要大于建单的 P99 耗时建议至少 5 分钟。坑四忽略幂等表本身的写入失败。如果幂等表所在库挂了插入失败整个建单就失败了。这时候要考虑降级幂等表不可用时是否允许直接建单牺牲幂等保可用还是直接拒绝保幂等牺牲可用。工单场景我倾向后者宁可让用户稍后重试也不要重复建单。6.3 一个实用的排查脚本线上怀疑有重复建单时用这个 SQL 快速定位-- 找出同一幂等键对应多张工单的情况 SELECT idem_key, COUNT(*) AS cnt FROM ticket WHERE idem_key IS NOT NULL GROUP BY idem_key HAVING cnt 1 ORDER BY cnt DESC LIMIT 20;如果这条查出来有结果说明幂等防线被击穿了重点查幂等表里这些键的状态以及对应的调用日志看是键生成问题还是并发拦截问题。正常情况下这条 SQL 应该永远返回空。7. 我个人的几点实操体会幂等这件事方案本身不复杂难的是在整条链路上保持一致。我见过太多团队在服务端做了完美的幂等结果调用方每次重试都生成新键前功尽弃。所以落地时一定要把键的生成和传递作为独立的一环去 review最好在 Agent 框架层面就把它固化下来而不是指望每个工具调用方自觉。另一个体会是不要试图用重试前先查询来替代幂等。查询和创建之间的时间窗口在并发下必然出问题而且查询本身也可能超时。幂等键 唯一约束是唯一可靠的方案查询只能作为辅助。最后对账补偿不是可选项是必选项。任何依赖状态一定能正确更新的设计在分布式环境下都会出问题。留一个对账任务兜底成本很低但能在关键时刻救你一命。我现在的习惯是只要涉及有副作用的接口调用幂等表、唯一索引、对账任务三件套一起上基本可以睡个安稳觉。