sync.Map + 请求指纹可实现轻量级幂等控制，核心是用客户端唯一标识（如idempotency-key）作key缓存结果；适用于小流量/单机场景，但需自行处理过期清理。
用 sync.Map + 请求指纹做轻量级幂等控制
接口幂等不是靠“加个开关”就能解决的，核心是识别“同一请求”，并拦截二次执行。对写操作（如创建订单、扣库存），最常用也最可控的方式是：客户端带唯一标识（比如 idempotency-key），服务端用它当 key 缓存执行结果。
别直接上 Redis——小流量或单机部署时，sync.Map 足够快且无外部依赖。但要注意它不支持过期，必须自己配定时清理或按需淘汰。
-
sync.Map适合 QPS - 指纹建议拼接：
method + path + client_id + idempotency-key，避免不同接口 key 冲突 - 缓存值不是布尔，而是结构体：
{status: "success"/"failed", result: json.RawMessage, timestamp: time.Time}，方便下游直接返回结果 - 写入前先
Load，命中就跳过业务逻辑；写入后必须Store，不能只靠条件判断
Redis 实现分布式幂等必须设 TTL
用 Redis 做幂等，本质是把「请求指纹是否存在」变成原子操作。但很多人漏掉关键点：没设过期时间，导致 key 永久残留，缓存被撑爆，甚至误判历史请求为重复。
正确姿势是用 SET key value EX seconds NX —— 这条命令同时完成「不存在才写入」和「自动过期」，比先 EXISTS 再 SET 安全得多。
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- TTL 时间要大于接口最长响应时间（比如超时设 30s，TTL 至少 45s），否则可能刚写入就过期，失去幂等性
- value 不要用空字符串，建议存客户端时间戳或 trace_id，便于排查
- 不要用
INCR或GETSET，它们无法保证「首次写入才成功」的语义 - 如果用 Go-Redis 客户端，直接调
SetNX(ctx, key, value, ttl)，别手写命令拼接
数据库唯一约束是最硬的兜底手段
所有中间层的幂等控制都可能失效：缓存击穿、网络重传、客户端绕过 header。最终防线永远是数据库——在业务逻辑里加唯一索引，让重复插入直接报错。
例如订单表，除主键外，必须对 user_id + idempotency_key 建联合唯一索引。这样即使上游漏判，DB 层也会拦住第二条记录。
- 错误信息通常是
ERROR: duplicate key value violates unique constraint，Go 里用pgx.ErrCodeUniqueViolation或 MySQL 的errno 1062精准识别 - 不要 catch 所有 error 后静默返回 success，必须区分是“真失败”还是“已存在”，后者才可视为幂等成功
- 索引字段别选太宽的列（比如全量 request body），会拖慢写性能；用客户端生成的短 key 最稳妥
HTTP 方法和状态码要配合幂等语义
很多人只管后端逻辑，却忽略 HTTP 层信号混乱：POST 接口重复提交返回 200，前端以为成功了，其实数据只有一份；或者用 PUT 更新时没校验版本，覆盖了别人修改。
真正的幂等不仅防重复，还要让调用方能安全重试。这意味着：对幂等接口，必须返回可重试的状态码（如 200、204），且响应体带明确标识（如 idempotent: true header 或 result: "cached" 字段）。
- GET/PUT/DELETE 天然幂等，但 PUT 必须配合乐观锁（
if-match: etag）或版本号字段，否则只是“表面幂等” - POST 非幂等，但加了
Idempotency-Key后，第二次请求应返回 200 或 409（Conflict），不能返回 500 或 201 - 别在中间件里统一拦截 POST 并改状态码——要根据业务是否真正执行来决定返回什么，否则掩盖问题
最难的从来不是“怎么存 key”，而是怎么定义“同一请求”。客户端时间戳、用户设备 ID、签名方式……这些都会影响指纹稳定性。上线前务必用真实重试链路压测，看缓存命中率和 DB 唯一冲突率是否符合预期。
