【API 设计之道】07 幂等性设计：处理网络抖动与重复请求的“唯一真理”

大家好，我是Tony Bai。

欢迎来到我们的专栏 《API 设计之道：从设计模式到 Gin 工程化实现》的第七讲。

在上一讲中，我们构建了结构化的错误处理机制。今天，我们来聊聊一个让无数后端工程师在深夜惊醒的话题：重复请求。

设想这样一个场景：

你的用户在 App 上点击了“立即支付”。 请求发出了，服务端扣款成功了。 但是，恰好此时用户进入了电梯，网络断了一秒。App 没收到服务端的“200 OK”，以为请求失败了。 于是，App 的重试机制（或者用户不耐烦的手指）再次发送了同样的支付请求。

结果：服务端收到了两份请求，扣了用户两次钱。

这就是分布式系统中经典的“二将军问题”变种。在网络不靠谱的现实世界里，“超时”不代表“失败”，它可能代表“成功了，但我没收到通知”。

如果你的 API 无法正确处理这种情况，那么数据一致性将无从谈起。

今天这一讲，我们将探讨如何通过幂等性（Idempotency）设计来解决这个问题。我们将参考业界标准（如 Google AIP-154），并在 Gin 中结合 Redis 实现一个幂等性中间件。

什么是幂等性？

我们要从数学原理和API 语义两个维度来彻底理解它。

数学视角：绝对值函数