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 脚本一次性完成「判断+写入+设置过期」。
立即学习“go语言免费学习笔记（深入）”；
- 键名建议格式：
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-Keyheader（RFC 兼容，比自定义名更易排查） - 该 key 应由前端生成（如
uuid.New().String()），且同一业务动作生命周期内固定不变（例如「提交订单」按钮点击一次，生成一个 key 并缓存，直到接口返回成功或明确失败） - 前端收到 409 Conflict 或自定义 425 Too Early（RFC 8470）时，应停止重试并提示用户；收到 5xx 且无响应体时才可按策略重试（带相同
Idempotency-Key） - 注意：不要把用户 ID、订单号等业务字段直接当幂等 key，它们不具备「请求唯一性」，多个用户可能同时提交相同订单号
真正难的不是写几行 SETNX 或 sync.Map，而是厘清哪些接口需要幂等、key 生命周期怎么管、失败后前端要不要降级展示、缓存结果是否包含敏感字段——这些往往比技术选型更花时间。
