应对 Agent 重试，幂等键要绑定操作意图

同一份 webhook 载荷，两秒内收到三次，作者的工具就存出了三个「独立」事件。问题出在一个默认假设：收到一次 POST，就执行一次变更。遇到会自动重试的 agent，这个假设很快失效。

作者给出的办法是：每个逻辑操作携带一个幂等键，服务端记住它对应的响应，重试时直接返回。对提供 webhook 接收、短链接创建或文档转换接口的开发者，这篇短文值得读：它讨论的是请求超时后，怎样避免把已经成功的事再做一遍。

为什么要按操作意图去重，而不是比较载荷

作者最初的 webhook-catch 工具把事件保存在内存里，并接受每一次 POST。后来，agent 的重试循环在两秒内发送了三次相同载荷，工具把它们记录成了三个事件。

相同请求再次到达，并不代表调用方又想执行一次操作。第一次请求可能已经成功，只是响应没有送到调用方。

但反过来，载荷相同也不能证明它们属于同一次操作。用户可能确实想执行两次内容相同的操作。因此，作者主张让调用方为每个逻辑操作生成一个幂等键（idempotency key），服务端保存「key → response」映射，并设置 TTL，也就是记录的有效期。

重试复用同一个键，新操作生成新键。

作者的短链接创建工具采用了这个办法：创建请求携带相同的键再次到达时，返回原来的链接，不再生成重复链接。这里决定是否重复执行的，是调用方声明的操作身份，而不是服务端对载荷相似度的猜测。

幂等不只是不重复执行，还要返回同一个结果

作者特别强调：第一次调用成功、客户端却没收到响应时，重试应当拿到字节完全一致的数据。

短链接场景尤其直观。第一次返回的 slug 和管理密钥（manage secret），重试时都必须保持一致。否则，即使没有再次创建链接，调用方也可能拿到另一组结果，导致后续状态不一致。

这也是保存「key → response」而不只是保存「这个键用过了」的原因。调用方不仅要知道操作发生过，还需要拿回那次操作的结果。

另外两条规则决定了这套机制的边界：

• 键要限定在具体端点内。用于 /create 的键，不能在 /delete 上生效。
• 键要有明确的过期策略。作者认为，内存加 TTL 符合其工具「按设计短暂存在」的定位；如果采用持久化存储，就需要配套清理机制。

TTL 不是随手加上的缓存参数。它决定服务端能在多长时间内识别一次重放请求。记录过期之后如何处理再次到达的请求，原文没有进一步说明。

我的判断

我认同作者把幂等设计放到接口起点的做法。对会产生副作用的接口，只在事后补载荷去重，很难准确区分「同一次操作的重试」与「内容相同的新操作」。

不过，这篇是故障经验分享，没有给出完整实现，也没有对照数据。作者提到固定间隔退避会让失败同步发生，主张把随机抖动退避（jittered backoff）和幂等键一起使用，但没有提供不同重试策略的测试结果。这个建议有清晰的工程理由，仍不能据此认定某个配置已经得到验证。

落到一般 Node 服务，还需要补齐并发问题：两个相同键的请求同时到达，怎样保证只有一个执行？业务写入成功、响应记录尚未保存时进程退出，又怎么办？这些都不是单纯查一次缓存就能解决的，原文没有交代。

内存存储的适用前提也比较窄。进程重启或多实例部署时，记录能否继续被查到，需要另行设计。持久化存储能扩大保障范围，但会增加存储、清理和一致性成本，不能直接照搬作者的小工具方案。

能拿来做什么

• 给短链接创建、文档转换等写接口梳理「一次逻辑操作」的边界，由调用方生成幂等键，并在超时重试时复用它。
• 在 Node 服务中保存原始响应，检查重试返回的 slug、manage secret 等字段是否与第一次完全一致，别只记录一个「已处理」标记。
• 明确键的端点作用域、TTL 和清理方式，再结合进程重启、多实例及并发请求检查保障范围。
• 为自动重试加入随机抖动，并分别验证「请求未成功」和「请求成功但响应丢失」两类故障下的行为。