科普 · 工程

什么是幂等键:以及您的应用为什么需要一个

2026年11月4日 · Software by Design

每个能离线工作的应用,迟早都要回答同一个问题:用户连点两下“发送”,或者网络在请求中途断掉、客户端重试时,会发生什么? 答案是一个叫幂等键的小机制,这里讲它怎么工作,以及它在我们自己的代码里长什么样。

一句话说清问题

网络不可靠,所以客户端必须重试;重试意味着同一个逻辑动作会到达不止一次;没有保护,“不止一次”就是两条工时记录、两张发票、两笔预订。

注意问题不是什么:不是“用户双击了”。用户确实会双击,但更常见的情形远不那么显眼:工地上的移动应用失去信号,把上班打卡排进队列,服务器应用了它,响应死在半路上,应用(正确地)又发了一遍。这条重复,是系统在按设计工作。

机制

幂等键是客户端按逻辑动作生成的唯一标识:不是按 HTTP 请求。客户端把同一个键附在原始请求和该动作的每一次重试上。服务器记录它见过的键;当一个键第二次到达,服务器返回第一次的结果,而不是把变更执行两遍。

三个特性让它成立:

  • 键归客户端所有。如果由服务器发放,客户端在收到它之前的重试就无法被识别。键在设备上铸出:在我们的移动应用里,是用户打卡那一刻创建的 UUID,而不是发起网络调用的时候。
  • 记录是认领,不是结果。服务器先写认领(“这个键归我了,结果待定”),再做变更。并发的重试撞上这条认领,会等待或重放第一次的结果:它绝不可能在底下塞进第二次变更。
  • 认领绑定载荷。我们把动作及其归一化输入的哈希和键一起存。同一个键配上不同的载荷 → 409 冲突,而不是静默覆盖。重试永远只该意味着“同一件事再来一次”。

它出现在我们应用的哪里

ArbeitszeitCheck 的移动打卡队列在每次重放中都带着一个 clientRequestId;TourCheck 把同一份契约绑在检查点确认里的 client_event_id 上,一次重放会把整条认领(备注、照片、时间戳)与已存的行做比较。过期时间和去重一样重要:我们的认领行存活七天,够长,盖得住一个长周末的信号盲区,又够短,让这张表一直是队列而不是日志。

给您自己应用的短版本

如果您的 API 会改变状态、客户端又能重试:而每个客户端都能重试:您需要的恰好是三样东西:每个动作一个客户端生成的键、一条先写的认领记录、一个让“同一个键”也意味着“同一个意图”的载荷哈希。这就是整个模式。其余一切:重放窗口、清理作业、冲突状态码:都只是围着这三条承诺的管道工程。