idempotentx —— 幂等键(防重复提交)
写操作(POST / PUT / PATCH / DELETE)重复请求不重复执行业务逻辑。 客户端在
Idempotency-Key头里带一个 key,同 key 在 TTL 内重放直接返首次结果。⚠️ Windows 上没有官方 Redis —— 本包没有 Redis 就整个 no-op(幂等保护直接失效), 开发机上要它就装 Memurai(Redis 协议兼容, 装成 Windows 服务,默认
127.0.0.1:6379、无密码)。 Developer 版仅供开发/测试,不许上生产。 详见 快速开始。
功能
idempotentx 提供两把 key的幂等管理,而不是一个状态机:
idem:res:<key> 结果(TTL 24h)—— 业务跑完才有,内容是 {state, http_status, body}
idem:lock:<key> 锁 (TTL 30s)—— 有人在跑,跑完就删
为什么要分两个:锁要短(30s,免得业务卡住把 key 锁死),结果要长(24h,免得用户 重试时业务又跑一遍)。一个 key 做不到"两套 TTL"。
核心接口:
| 接口 | 作用 |
|---|---|
idempotentx.New(rdb, lockTTL, resultTTL) |
造一个独立实例(不碰全局) |
idempotentx.Init(rdb, lockTTL, resultTTL) |
装全局,只调一次 |
idempotentx.M() |
取全局 manager(未 Init 返 nil) |
Manager.AcquireOrGet(ctx, idemKey) |
抢锁 / 命中结果 / ErrInFlight |
Manager.Save(ctx, idemKey, httpStatus, body) |
业务完成后写结果 |
Manager.Release(ctx, idemKey) |
业务异常时释放锁 |
Manager.String() |
调试用 |
"正在跑"不是第三种状态
结果 key 里只有 StateDone 和 StateFailed。"正在跑"这个状态活在
锁 key 的存在性里(idem:lock:<k> 存在 = 有人在跑)。旧版本那个
StateRunning 常量已被删掉 —— 留着它是有害的:会让人写出
"结果里 State==running 就当未命中"这种错代码,而结果 key 里压根不会出现 running。
它不解决什么
- 不做分布式锁(锁只保证"同一个 key 同时只有一个请求在跑",不保证跨 key 的顺序)
- 不做业务事务回滚(它只重放响应,不撤销已写入的数据)
- 不保证客户端会带 key(见下文「注意事项」第 10 条)
配置
yaml 侧
该包无 yaml 配置。
锁 TTL / 结果 TTL 在 cmd/server/main.go 里硬编码:
idempotentx.Init(repository.GetRedis(), 30*time.Second, 24*time.Hour)
New() 在参数 ≤0 时兜底成 DefaultLockTTL(30s)/ DefaultResultTTL(24h)。
代码侧
| 常量 | 值 | 说明 |
|---|---|---|
idempotentx.DefaultLockTTL |
30 * time.Second |
锁 TTL |
idempotentx.DefaultResultTTL |
24 * time.Hour |
结果缓存 TTL |
跨域调用时 Idempotency-Key 必须出现在 cors.allow_headers 里(配置模板已经
放行了)。
使用方法
装配(main 里一次)
idempotentx.Init(repository.GetRedis(), 30*time.Second, 24*time.Hour)
挂中间件(router 里)
h.Use(middleware.Idempotency())
中间件自己读 Idempotency-Key 头、按 method 过滤、抢锁、重放、写结果。
直接用 Manager(不挂中间件时)
m := idempotentx.New(rdb, 30*time.Second, 24*time.Hour)
acquired, cached, err := m.AcquireOrGet(ctx, idemKey)
switch {
case err == idempotentx.ErrInFlight:
// 有另一个请求正在跑 → 409
case !acquired && cached != nil:
// 命中:cached.State / cached.HTTPStatus / cached.Body 原样重放
case acquired:
// 首次:跑业务,跑完
m.Save(ctx, idemKey, status, body)
}
Result 的形状:
type Result struct {
State State `json:"state"` // StateDone / StateFailed
HTTPStatus int `json:"http_status"` // 原始响应状态(200/201/...)
Body []byte `json:"body"` // 原始响应 body(含 code/message/data/request_id)
WrittenAt time.Time `json:"written_at"`
}
Body 存的是原始响应字节,所以重放时客户端拿到的和第一次完全一样。
完整可运行示例见 examples/idempotentx/main.go。
注意事项
- ⚠️ Redis 没配 ⇒ 中间件整个 no-op,不是报错。
Init(nil, ...)只打一条 WARN (idempotentx: rdb is nil, manager disabled);AcquireOrGet里m.rdb == nil直接放行。⇒ 生产忘了配 Redis ⇒ 所有写操作都没有幂等保护,症状只是日志里 一行 WARN。 - ⚠️ Redis 运行期故障也是放行(fail-open)。
Get出错、SetNX出错,都返acquired=true。⇒ Redis 抖动期间写操作全部失去幂等保护,没有错误码、没有 5xx。 (取舍的理由是"挡住所有写操作比不幂等更糟";但代价是这段时间里重复提交会真的重复执行。) - ⚠️ 同 key 并发 ⇒ 409,不是排队。第二个请求拿到
ErrInFlight,中间件返 HTTP 409 +{"code":40900,...}。客户端必须自己退避重试;当成成功处理会丢写。 - ⚠️ 409 的响应体是手写的,不走统一信封。中间件直接
c.Response.SetBody(...)塞一段字面量 JSON(code40900 +message+data: null), 没有timestamp/trace_id字段(response.Fail才有)。前端按统一信封解析 时要能容忍缺字段。命中重放的路径走的是另一条(c.Response.SetBody(cached.Body)), 那份 body 是首次响应的原始字节,信封是全的 —— 两条路径的 body 形状不一样。 - ⚠️ 重放响应带一个
Idempotent-Replay: true头,客户端可以据此区分 "这次是重放"。 - ⚠️ 业务失败(4xx/5xx)也缓存。
Save里httpStatus >= 400会把 state 置成StateFailed,但照样写进结果 key(TTL 24h)。⇒ 客户端拿同一个 key 重试, 拿回同一个错误,业务不会重跑。 - ⚠️ "业务压根没跑成"的响应不缓存。判据在
internal/api/middleware/idempotency.go的cacheableResult:c.IsAborted()或状态码 ∈ {401, 403, 413, 429} ⇒ 不缓存, 并且释放锁。⚠️ 5xx 不在拒绝之列 —— handler 抛的 500、超时的 504 都缓存 (业务可能已经写了数据 ⇒ 宁可少跑一次,不能重跑)。这条边界不能动。 - ⚠️ panic 不缓存,但锁会被释放。中间件用
defer调mgr.Release;不释放的话 这个 key 被锁 30s,客户端拿同一个 key 重试只会拿到 409 —— 而实际上没有任何请求在跑。 - ⚠️ 空 key 直接放行。否则所有人共用
idem:lock:一把锁,而Save/Release对空 key 直接 return ⇒ 那把锁永远不会被释放,之后每个空 key 的请求都 409 直到 TTL 到期。 - ⚠️ 键空间必须是单射。旧实现是
idem:<k>(结果)与idem:<k>:lock(锁),两个 命名空间重叠:客户端 key"foo:lock"的结果 key 正好是客户端 key"foo"的 锁 key ⇒ 两个互不相干的请求互相把对方的幂等状态搞坏,且没有任何报错。 现在用idem:res:/idem:lock:两个前缀分开,任何客户端 key 都撞不上。 - ⚠️ 前端每个写请求自动生成一个全新的 Idempotency-Key。
web/src/api/client.ts的请求拦截器对 POST/PUT/PATCH/DELETE 自动注入genIdempotencyKey()(UUID v4)。 ⇒ 用户双击提交 = 两个请求 = 两个 key = 后端幂等不生效。幂等只在"同一个 key 被重放"时有效;调用方要防双击,得自己把 key 固定下来传进去(拦截器会保留调用方 已设的值 —— M101 修过"大小写不同就被覆盖"的老 bug)。 - ⚠️ 中间件不挂在全局时
M()可能返 nil。idempotentx.M()未Init返 nil, 中间件判到 nil 直接放行(不是报错)。