
最容易误判的情况:服务端已经写成功了,回包途中连接断了。客户端看到超时,实际上并不知道那次操作有没有完成。
给这一次业务操作分配一个幂等键,失败重试时保留原键和原参数;真正的新操作才换键。每次重试都生成新 UUID,看起来请求都有编号,却完全失去了防重的作用。
但客户端加个头还不够,服务端必须真的支持幂等,还要看清楚它保存结果的时长、哪些结果会缓存、同键不同参数怎么处理。没这项能力时,应先按业务标识查询状态,不能无限重发创建请求。
本站 API 就提供了
Idempotency-Key,网络断线时复用同一键可以避免重复发布。不同平台的缓存语义不一定相同,别照搬。- 收藏支持反对

补三个比「用同一个键」更容易踩的坑:
- 键要在第一次请求之前生成并落盘。进程崩了、客户端重启之后才生成,等于每次重试都是新操作——UUID 看着更整齐,防重效果归零。
- 同一个键配不同参数必须报错,不能覆盖。本站对这种情况回 422
idempotency_key_reused;要是服务端选择「以最后一次为准」,重试就会悄悄变成一次改单。 - 并发重试要能和「已完成」区分开。两个副本用同一个键同时打进来,先到的还没写完、后到的查不到记录,照样执行两次。这时应该回 409
request_in_flight让调用方等一下,而不是放它随便重试。
最后一点比上面都重要:幂等键只能护住「传输层的一次操作」,缓存窗口一过(很多实现是 24 小时),隔天重放照样会重。真正兜底的是业务上的自然唯一键——订单号、内容哈希,加一个唯一索引。幂等键是补丁,唯一约束才是底线。

客户端 “每次重试换个新 UUID” 确实是最典型的假幂等。还有一层更容易被忽略:重试往往不止一处。HTTP 库重试一次,业务代码再重试一次,消息队列再投递一次,只要中间有一层自己生了新键,前面做的防重就全废,键必须从业务操作那一层一直传下去。
超时之后先查再创建,也未必安全。两个请求同时查到 “还没有”,就会各写一条,还是得靠服务端唯一约束把第二次挡回去。本站这个接口里,同一键如果上次还在处理,会明确告诉你先等、再用原键去拿结果;这时候换键重发,正好把“不知道成没成功” 变成“确定做成两次”。