idempotency-golisted

# Go 幂等性处理专家 使用 Go 实现幂等性处理：$ARGUMENTS --- ## 1. 幂等性基础 ### 天然幂等 vs 需要保护 | 操作 | 天然幂等 | 说明 | |------|---------|------| | GET /users/123 | Y | 读取操作 | | PUT /users/123 | Y | 全量替换 | | DELETE /users/123 | Y | 删除操作 | | POST /orders | N | 需要幂等保护 | | POST /payments | N | 需要幂等保护 | | PATCH /users/123 | N | 增量更新可能不幂等 | --- ## 2. 幂等键设计 - **客户端生成**：HTTP Header `Idempotency-Key`，推荐 UUID v4 或 ULID - **服务端生成**：`GenerateIdempotencyKey(userID, operation, payload)` - 基��业务字段 SHA256 哈希 - **业务字段生成**：`IdempotencyKey()` 方法，含时间窗口（如每天可重复） --- ## 3. 存储策略 ### Redis 存储（推荐用于简单场景） - `IdempotencyRecord{Status, Response, StatusCode, Error, CreatedAt, ExpiresAt}` - `TryAcquire(ctx, key)` - SET NX 原子获取处理权，返回 (record, acquired, error) - `Complete(ctx, key, statusCode, response)` - 标记完成 - `Fail(ctx, key, err)` - 标记失败 - `Release(ctx, key)` - 释放处理权（异常情况） ### PostgreSQL 存储（推荐用于事务场景） - DDL：`idempotency_keys` 表，`INSERT ON CONFLICT DO NOTHING` 实现原子获取 - `CompleteInTx(ctx, tx, key, statusCode, response)` - 在同一事务中完成 --- ## 4. 中间件实现 - `IdempotencyMiddleware.Wrap(next)` - HTTP 中间件 - 仅对非幂等方法（POST/PATCH）启用 - 无 Idempotency-Key 则正常处理 - processing 状态返回 409 Conflict + Retry-After - completed 状态返回缓存响应 + `X-Idempotency-Replayed: true` - failed 状态返回错误，允许重试 - `responseWriter` 捕获状态码和响应体 --- ## 5. 业务层幂等 ### 订单创建流程 1. 获取/生成幂等键 2. `TryAcquire` 获取处理权 3. 未获取 -> `handleExistingOrder`（按 status 返回） 4. 获取 -> 开启事务 -> 创建订单 -> `CompleteInTx`（同事务）-> Commit 5. 失败 -> Rollback + `Fail` --- ## 6. 消息幂等 - **Kafka 消费者**：幂等键 = `kaf