2026-11-18-Go接口幂等设计实战

你好,我是利威尔xu。这是「项目实战」系列里讲接口幂等的一篇,前面写过分布式锁和消息消费幂等,这篇专门讲一个高频翻车点:HTTP 接口的幂等设计。如果你是做 Go 后端、又遇到过"用户重复点击扣了两次款"的读者,建议先收藏,设计接口时对着查。

文章目录

一、为什么接口要幂等

幂等的意思是:同一个请求执行一次和执行多次,结果一样。

网络重试、用户重复点击、客户端超时重发,都会让"同一个业务操作"被提交多次。如果接口不幂等,就会:

  • 重复扣款、重复下单
  • 重复创建记录
  • 重复发券

典型场景:用户点"支付",网络卡了一下,前端重试,后端收到两次支付请求,结果扣了两次钱。

二、幂等的三把钥匙

1. 唯一约束兜底

数据库层面加唯一索引,是最后的防线:

sql 复制代码
CREATE UNIQUE INDEX uk_order_no ON orders(order_no);

重复插入会被唯一索引拦住,即使上层逻辑漏了,数据也不会错。这是最可靠的一层。

2. 幂等键 + 状态机

请求带一个幂等键(idempotency key),服务端用它去重:

go 复制代码
func Pay(ctx context.Context, req *PayReq) error {
    // 1. 用幂等键查是否已处理
    if processed, _ := isProcessed(ctx, req.IdempotencyKey); processed {
        return nil // 已处理过,直接返回成功
    }
    // 2. 处理业务
    if err := doPay(ctx, req); err != nil {
        return err
    }
    // 3. 标记已处理
    return markProcessed(ctx, req.IdempotencyKey)
}

面试追问:幂等键存在哪?

答:通常是 Redis(SETNX 或 SET key value NX EX)+ 数据库落一条记录。Redis 负责快速去重,数据库记录负责持久化兜底,防止 Redis 挂了丢状态。更严谨的做法是"先落库标记、再处理业务",用唯一索引保证幂等键本身的唯一性。

3. 乐观锁 / 版本号

go 复制代码
// UPDATE ... SET balance = balance - 100, version = version + 1
// WHERE id = ? AND version = ?
// 影响行数为 0 说明版本号不对,被并发改了,重试或报错

三、一个完整的幂等扣款流程(建议收藏)

步骤 动作 目的
1 请求带幂等键 标识"这是同一次业务"
2 Redis SETNX 幂等键 快速去重,占坑
3 检查是否已处理 已处理直接返回成功
4 执行扣款 业务逻辑
5 落库标记 + 唯一索引 持久化兜底
6 释放/过期幂等键 防止键永久占用

关键点:第 2 步的占坑和第 3 步的检查之间要有原子性,否则并发请求会同时通过检查。

四、哪些接口必须幂等

接口 必须幂等吗
支付、扣款 ✅ 必须,重复扣款是事故
下单、创建订单 ✅ 必须,重复下单
发券、发奖励 ✅ 必须
普通查询 GET 天然幂等
单纯日志写入 ⚠️ 看业务,通常容忍

规则一句话:凡是"改变资金、库存、权益"的写接口,都要幂等。

五、本章面试要点

  • 幂等 = 同请求执行多次结果一致,防网络重试、重复点击。
  • 三把钥匙:唯一约束兜底、幂等键+状态机、乐观锁版本号。
  • 幂等键存 Redis(快)+ 数据库(持久化),占坑和检查要原子。
  • 扣款、下单、发券必须幂等;查询天然幂等。
  • 数据库唯一索引是最后防线,永远别省。

最后问你一个一句话能答的问题:你项目里的支付接口,幂等键是前端生成还是后端生成? 评论区聊聊。

建议收藏这篇,那张幂等扣款流程表,下次设计支付接口直接照着搭。

下一篇预告:项目实战继续------Go 服务如何优雅停机,正在处理的请求不能丢。

作者:利威尔xu | CSDN 专栏《项目实战》

相关推荐
喵个咪39 分钟前
RushWind Admin — update_mask 写面:字段级白名单、显式清除与点路径合并
后端·rust
喵个咪1 小时前
RushWind Admin — 多租户行级隔离与租户回收站:Viewer 三态、repo_shell! 与全域级联清除
后端·rust
喵个咪1 小时前
RushWind CMS — 三服务拓扑:core 领域层、双 BFF 薄代理与一份契约的双面输出
后端·rust
eggwyw1 小时前
linux下的C\C++多进程多线程编程实例详解
开发语言·c++
天多高_风不晓得1 小时前
Comparable 与 Comparator
后端
程序员鱼皮2 小时前
这 3 年 AI Agent 到底进化了啥?万字大白话,一次讲透!
前端·后端·aigc
一条Go2 小时前
SSH 命令审核流:为什么「能执行」必须先「被批准」
后端·架构·github
布莱克6052 小时前
Swift 枚举详解:从基础语法到关联值与模式匹配
开发语言·ios·swift·枚举
__underline__2 小时前
冷门Python知识点007篇:list[int]不是类,为什么能当基类?
后端·python