Golang Web服务如何防止重复请求_幂等性处理方案说明

POST请求必须考虑幂等性，因刷新、重试或重复点击会导致重复执行，引发重复扣款等问题；需通过唯一标识（如Idempotency-Key）配合sync.Map（单机）或Redis+Lua（分布式）实现幂等控制，并需前后端协同设计。

为什么 POST 请求必须考虑幂等性

浏览器刷新、网络重试、前端按钮重复点击，都会导致同一个业务请求被多次发到后端。如果后端没做控制，就可能重复扣款、重复下单、重复发消息。Golang Web 服务本身不自动解决这个问题，http.Handler 对每个请求一视同仁，你得自己加判断逻辑。

核心思路是：为每次请求绑定唯一标识（如 X-Request-ID 或业务侧生成的 idempotency-key），并在处理前检查该标识是否已成功处理过。

用 sync.Map 实现轻量级内存幂等控制（适合单机场景）

适用于 QPS 不高、部署单实例、且允许短暂窗口内重复（如秒级）的场景。比 Redis 简单，无外部依赖，但不能跨进程共享状态。

• sync.Map 存储格式建议为 map[string]struct{ done bool; result interface{} }，避免写入时竞争
• 请求进来先 Load，若存在且 done == true，直接返回缓存结果（需注意序列化一致性）
• 若不存在，用 LoadOrStore 占位（值设为 done: false），再执行业务逻辑，最后 Store 更新为 done: true
• 务必设置超时清理机制（比如用 time.AfterFunc 或后台 goroutine 定期 Range 删除过期项），否则内存泄漏

var idempotentMap sync.Map // key: idempotency-key, value: *idempotentItem

type idempotentItem struct {
	done   bool
	result []byte // 假设返回 JSON 字节
	once   sync.Once
}

func (i *idempotentItem) SetResult(r []byte) {
	i.once.Do(func() {
		i.result = r
		i.done = true
	})
}

用 Redis + Lua 脚本保证分布式幂等（推荐生产环境）

多实例部署下，必须依赖外部存储。Redis 是最常用选择，但要注意原子性——不能先 GET 再 SET，中间可能被并发请求插入。必须用 Lua 脚本一次性完成「判断+写入+设置过期」。

• 键名建议格式：idempotent:{service_name}:{key}，避免不同服务冲突
• 过期时间要大于业务最大执行耗时（比如业务最长 5s，

  

  设 EXPIRE 10），防止误判
• Redis 返回 1 表示首次写入成功，可执行业务；返回 0 表示已存在，直接读取之前结果（需提前把结果也存进 Redis）
• 不要在 Lua 中做耗时操作（如 DB 查询），只做状态判断和简单写入

const idempotentScript = `
if redis.call("GET", KEYS[1]) == false then
    redis.call("SETEX", KEYS[1], ARGV[1], ARGV[2])
    return 1
else
    return 0
end
`

// 使用 client.Eval(...) 执行，KEYS[1] 是 idempotency-key，ARGV[1] 是过期秒数，ARGV[2] 是初始占位值（如 "processing"）

前端配合与 header 设计细节

光靠后端不够。前端必须主动提供幂等标识，并遵守重试规则。

• 建议统一使用 Idempotency-Key header（RFC 兼容，比自定义名更易排查）
• 该 key 应由前端生成（如 uuid.New().String()），且同一业务动作生命周期内固定不变（例如「提交订单」按钮点击一次，生成一个 key 并缓存，直到接口返回成功或明确失败）
• 前端收到 409 Conflict 或自定义 425 Too Early（RFC 8470）时，应停止重试并提示用户；收到 5xx 且无响应体时才可按策略重试（带相同 Idempotency-Key）
• 注意：不要把用户 ID、订单号等业务字段直接当幂等 key，它们不具备「请求唯一性」，多个用户可能同时提交相同订单号

真正难的不是写几行 SETNX 或 sync.Map，而是厘清哪些接口需要幂等、key 生命周期怎么管、失败后前端要不要降级展示、缓存结果是否包含敏感字段——这些往往比技术选型更花时间。