如何在 Go 中实现对 API 接口的幂等性校验

如何在 Go 中实现对 API 接口的幂等性校验

为什么直接用 uuid 作为幂等键会出问题

不少开发者第一步就想当然地让前端传一个 idempotency-key，比如直接用 uuid.New() 生成，后端存进 Redis 并设置 TTL，请求来了先查是否存在。这套路听起来挺合理，对吧？但实际踩坑的人可不少。核心问题在于：当同一个业务操作被重复提交时，前端完全可能生成多个不同的 uuid。想想这些场景：用户连续点击两次按钮、网络超时触发自动重试、或者 SDK 的默认重发机制。在这些情况下，随机生成的 uuid 根本无法识别“这是同一笔转账”或“这是重复创建同一订单”。这里有个关键认知需要扭转：幂等性校验的本质，不是简单地防止请求重放，而是要准确识别出「具有相同业务语义的操作」。

用业务参数哈希构造幂等键才是正解

那什么才是可控、可靠的做法呢？答案是：从请求体中提取那些稳定、可复现、且能真正代表业务意图的字段，拼接后计算哈希值，以此作为幂等键。以转账接口为例，我们需要仔细甄别字段：

• 必须包含的字段：from_account_id、to_account_id、amount、currency，以及一个精确到秒的 timestamp（避免因毫秒级差异导致哈希值不一致）。
• 必须排除的字段：像 request_id、trace_id、随机 nonce 这类每次请求都可能变化的字段，一定要剔除。
• 标准化建议：为了进一步保证一致性，最好将 amount 统一转换为整数分单位，并把 timestamp 强制截断到秒级，这样可以有效规避浮点数精度或时区带来的偏差。

下面是一个用 sha256 生成幂等键的示例代码片段：

func genIdempotencyKey(req TransferRequest) string {
    data := fmt.Sprintf("%s:%s:%d:%s:%d",
        req.FromAccountID,
        req.ToAccountID,
        req.Amount * 100, // 转为分
        req.Currency,
        req.Timestamp.Unix(),
    )
    return fmt.Sprintf("%x", sha256.Sum256([]byte(data)))
}

Redis 存储策略要兼顾原子性与过期控制

存储校验环节也有讲究，千万别先 GET 再 SET，否则并发请求下仍然可能穿透。正确的姿势是使用 SET key value EX 3600 NX 这样的原子操作：

• NX 选项保证了只在键不存在时才执行写入，天然解决了竞态条件问题。
• EX 3600 设置了1小时的过期时间，避免脏数据长期滞留（这个时间应根据业务最长处理周期加上缓冲来设定）。
• 如果 SET 命令返回 false，说明该操作已存在，这时应该直接返回上次成功的响应（需要提前缓存响应体，或者至少缓存状态和业务ID供查询）。

这里有个技术细节需要注意：在 Go 语言的 github.com/go-redis/redis/v8 客户端中，对应的方法是 client.SetNX(ctx, key, value, ttl)，可别误用成非原子的 Set() 方法。

失败回滚和状态机设计常被忽略

话说回来，幂等键只是入口的“守门员”，它可不是万能的。真实业务场景中，一个操作完全可能卡在中间状态——比如扣款成功了，但后续的记账步骤却失败了。这时候，仅靠 Redis 里一个键存在与否，根本无法判断业务的最终结果。因此，下面这几步设计常常被忽略，却至关重要：

• 必须持久化操作状态：例如在数据库里增加 idempotency_key 和 status 字段。而且，状态更新必须与主业务逻辑放在同一个事务中完成（或者通过本地消息表加补偿机制来实现）。
• 设计明确的状态机：幂等接口首次被调用时，应写入「processing」状态；成功后更新为「success」；失败则标记为「failed」。后续的重复请求根据这个持久化的状态来决定是返回缓存结果、触发重试还是直接拒绝。
• 区分可重试与不可重试的错误：不要把所有失败都当成可重试的。例如“余额不足”这种业务错误，应该明确返回给调用方，而不是反复尝试。

最后提一个最容易被绕过的点：如果没有把「业务状态查询」和「幂等键检查」这两步做统一的抽象设计，很容易导致部分接口处理器漏掉校验，或者状态更新操作漏掉了事务包裹，从而埋下一致性隐患。