幂等密钥是客户端随请求发送的自选标识符,使超时或错误后的重试返回原始结果,而不会重复发送消息。
网络总在最糟糕的时刻出故障:服务器已经执行了操作,而客户端还没收到结果。一个超时的请求可能已经发出了消息,也可能没有,客户端无从判断。没有幂等机制时,安全的做法是什么也不做;而诱人的做法,也就是重试,则有重复发送的风险。有了幂等密钥,客户端就可以放心重试:服务器识别出密钥,返回第一次尝试的结果,不会再发送任何新消息。
Idempotency-Key 标头是由支付 API 推广开来的惯例,此后被广泛采用。服务器会在有限的期限内保留密钥,而且许多服务器会拒绝带着不同有效载荷再次出现的同一密钥,因为这说明客户端有缺陷,而不是在重试。密钥应来自你自己的业务标识符,例如订单号加事件,或用户加尝试次数,这样来自不同进程或服务器的重试才能正确地落到同一个密钥上。密钥必须在第一次尝试之前创建,与任务一起保存,并在每次重试时原样重复使用。
示例
假设一家商店为订单 4821 发送发货通知,使用的密钥是 order-4821-shipped。第一次 POST 超时了。使用同一密钥的重试返回了原始消息 ID 和状态;客户只收到一条 SMS,账户也只为一条付费。如果重试使用了新密钥,客户就会收到两条。
常见错误
- 每次重试都生成新的随机密钥,这完全违背了初衷。
- 使用范围过宽的密钥(例如只用用户 ID),导致之后的不同消息被当作重放,永远不会发送。
- 在重试循环内部创建密钥,而不是把它与任务一起持久保存。
在 SMSMeteor:任何 POST 请求都接受 Idempotency-Key,即由你自选、最长 128 个字符的字符串。24 小时内使用相同密钥和相同有效载荷:返回原始响应,并带有标头 Idempotent-Replayed: true。相同密钥、不同有效载荷:返回 409 idempotency_conflict。这一点很重要,因为消息一旦交给运营商就会计费,重复发送就意味着第二次扣费。收到 429 后,请等待 Retry-After 指定的时间,再用同一密钥重试。API 参考提供了详细信息,测试密钥则让你无需发送任何消息即可演练超时和重试。
