技术解析 · 附来源的解答

幂等键：防止重复发送邮件

幂等键是由客户端生成并随 API 请求发送的唯一值，用于确保某个操作只执行一次。如果使用相同的键重试请求，服务器会识别出重复，直接返回原始响应，而不会再次执行该操作。

工作机制

当客户端发送带有幂等键的请求时，服务器会将该键及对应的响应存入缓存。如果之后又收到使用相同键的请求，服务器会跳过执行逻辑，直接返回缓存的响应。对于分布式系统而言，这一机制至关重要，因为网络超时可能让客户端无法确定请求是否已到达服务器。

在事务性邮件场景中，同一封邮件发送两次会造成糟糕的用户体验，并增加垃圾邮件举报。借助幂等键，开发者可以为失败的网络调用实现积极的重试逻辑，而不必担心向收件人重复发送邮件，从而保证整个投递管道的可靠性和一致性。

应使用 UUID 或高熵随机字符串生成键，以避免冲突。服务器通常在 24 小时后使这些键过期。开发者必须确保键与邮件的具体意图绑定；如果保持同一个键却修改了邮件正文或收件人，应返回错误，而不是返回缓存的成功结果。

某 SaaS 应用为一封密码重置邮件生成了唯一的键。应用调用邮件 API，但在收到响应之前连接断开。应用使用相同的键重试请求。API 发现该键已存在，于是返回 200 OK，而不会向用户发送第二封邮件。SendHQ 免费工具可以帮助开发者高效管理邮件基础设施。

如果请求内容已被修改，却仍使用已有的幂等键发送，服务器应返回冲突错误。这可以防止不小心将同一个键复用于不同的邮件。正确的处理方式是捕获这类冲突，并为更新后的请求体生成一个新键。

幂等键和 Message-ID 是一回事吗？

不是。Message-ID 由服务器在处理之后分配，而幂等键由客户端在发送请求之前分配。

幂等键过期后会发生什么？

如果键已从服务器缓存中过期，重试会被视为新请求，可能导致邮件被重复发送。

幂等键最适合使用哪种数据类型？

UUID v4 是业界标准，因为它在分布式系统中发生冲突的概率可以忽略不计。