← 学习中心

重试是最危险的动作:为什么每个写接口都需要一把幂等钥匙

网络超时的时候,客户端只知道「没收到回应」,不知道「对方到底执行了没有」。这时候重试一次,就可能变成执行两次。解法不是不重试,而是让重复执行无害:给请求配一把幂等钥匙,服务端按键去重,配合指数退避与副作用拆分。这篇把至少一次、至多一次、恰好一次这三种语义讲清楚,并给出可落地的键设计。

本节你将能

读完能判断一个接口能不能安全重试,能设计出一把可用的幂等键,能说清为什么「恰好一次」在工程上通常是「至少一次加去重」实现的,也能在扣款、发货、发通知这类有副作用的场景里,把该拆开的步骤拆开。

直觉模型:客户端永远在猜

一次请求走网络,可能出现三种结局:对方收到并成功、对方收到但失败、对方根本没收到。客户端能观测到的只有「收到回应」与「超时」两种。超时把后两种混在一起,于是客户端必须做一个决定:重试,或者放弃。

幂等的四个动作:客户端生成键、服务端唯一索引、记录状态、重试返回同结果。

幂等的四个动作:客户端生成键、服务端唯一索引、记录状态、重试返回同结果。

重试的风险不在于「再发一次」,而在于「上一次可能已经生效」。如果接口的动作是「扣 100 元」,第二次执行就是扣 200 元;如果动作是「把状态设为已发货」,第二次执行没有额外影响——这就是幂等与不幂等的分界。

核心要点

  • 三种投递语义要分清。至多一次:可能丢,但不会重复;至少一次:不会丢,但可能重复;恰好一次:既要可靠又不重复,实现成本最高。
  • 工程上的通行做法是「至少一次加幂等」。让重试自由发生,用去重把重复挡在业务之前,最终效果接近恰好一次。这比在设计阶段追求完美的恰好一次要现实得多。
  • 幂等键由客户端生成。每次业务意图分配一个唯一键(通常是 UUID),重试时复用同一个键;服务端以键为唯一索引,第一次执行后把结果与状态记下来,后续同键请求直接返回同一结果。
  • 幂等表要防并发。两个同键请求同时到达时,唯一索引或行锁只能让一个进入执行,另一个要么等待、要么返回「处理中」。没有这一步,去重只在串行场景有效。
  • 重试要退避、要抖动、要有上限。指数退避避免把下游压垮,抖动避免大量客户端同时重试形成尖峰,次数与总时长上限避免请求永远挂着。
  • 只对可重试的错误重试。超时、连接失败、限流与 5xx 可以重试;参数错误、权限错误这类 4xx 重试多少次结果都一样,只会放大负载。
  • 副作用要拆开。扣款成功但通知失败时,不该回滚扣款再重试整笔;把通知放进待发表,用补偿任务重发,把「钱」和「消息」分开对待。

案例锚点

一个常见场景:用户点了一次「提交订单」,前端因为网络抖动重发了一次请求。服务端两次都收到,于是创建了两笔订单、扣了两次款。事后排查时,日志里两条请求长得几乎一样,唯一区别是时间戳差 800 毫秒。

修法分三步。第一步,前端在进入提交页时生成一个订单意图键,把键随请求一起发;重发时复用同一个键。第二步,服务端用这个键做唯一索引,第一次请求写入后开始执行,第二次请求要么撞索引被拒、要么查到已有记录直接返回第一次的结果。第三步,把「扣款」与「发通知」拆开:扣款在事务内完成,通知写进待发表,由后台任务发送,发送失败只重发消息,不回滚资金。

改完之后的行为是这样的:网络再抖三次,用户也只会看到一条订单、一次扣款,第二、三次请求拿到同一份结果。重试从「危险动作」变成了「免费动作」。

互动

三个问题:你现在负责的写接口,如果同一个请求被发两次,会发生什么?幂等键是用请求体哈希算出来的吗(如果是,它多半不能用,因为里面通常带时间戳)?下游超时后,你的客户端会立刻重试、还是退避之后再试?

常见误区

  • 以为「加了重试就变可靠」。重试提高的是送达率,不是正确性。没有幂等,重试只是把偶发的重复变成常态的重复。
  • 用请求体哈希当幂等键。请求体里常带时间戳、随机数或自增序号,哈希每次都不同,去重形同虚设。键要代表「业务意图」,不是「这一次调用」。
  • 把至少一次当成恰好一次。消息队列承诺的通常是最少送达一次,重复是正常现象,消费端必须自己去重。
  • 无上限重试。下游故障时,所有客户端同时重试会形成放大效应,把小故障变成雪崩。退避加抖动是必需项,不是优化项。
  • 忘记幂等记录的生命周期。幂等表需要保留窗口与清理策略:太短会漏掉迟到的重试,太长会拖累写入。窗口应大于「最长可能的业务重试周期」。

本节小结

记住三句话:网络超时意味着「不知道有没有执行」,所以重试必须有幂等兜底;幂等键代表业务意图,由客户端生成,服务端用唯一索引加状态记录去重;重试要退避加抖动、有上限、只对可重试错误,副作用要拆开而不是整笔回滚。

[关联推荐]

- 分布式系统投递语义与幂等设计的通行实践(至少一次 / 至多一次 / 恰好一次) - HTTP 幂等语义约定(GET、PUT、DELETE 的幂等性,POST 的非幂等性)
重试是最危险的动作:为什么每个写接口都需要一把幂等钥匙 | 必学必会