Go 接口防重复提交：用 Idempotency-Key 处理按钮连点和网络重试

用户提交订单的时候手滑多点了两下，前端按钮明明已经置灰，服务端后台还是收到了两次重复请求；移动网络抽风跳了几秒，客户端自动发起重试，日志里又冒出来同一个业务单号。Go接口要防住这类重复提交，不能只靠前端按钮禁用做表面功夫，更稳妥的方案是在服务端约定好接收一个稳定的 Idempotency-Key，把「这一次业务尝试」单独标记记录下来，后续带相同标识的请求直接返回第一次的处理结果，或者明确告知客户端当前任务还在处理中。

为什么按钮禁用挡不住重复提交

不少团队第一次碰到重复下单问题，第一反应都是让前端在提交请求之后立刻把按钮置灰。这个操作本身确实有价值，能减少普通用户的误触，页面状态也会更直观。但它完全挡不住页面刷新导致的重发、App弱网下的自动重试、浏览器后退之后再次提交、第三方支付平台的回调重投，更拦不住懂技术的用户直接绕过页面调用接口。

服务端真正要解决的核心问题，是怎么识别出「同一件用户发起的业务动作」。一次「创建订单」的用户操作，完全可能对应好几个HTTP请求；只要这些请求都带着同一个专属的业务键，Go接口就能快速判断：这是全新的第一次请求、已经处理过的重复请求，还是上一次发过来还没跑完处理流程的请求。

Idempotency-Key 的交互约定

这套方案的核心不是给所有请求全加全局锁，而是客户端和服务端提前约好一套通用的身份标识规则。用户点下「提交订单」按钮的瞬间，客户端生成一个随机字符串放到请求头里；哪怕后面请求超时需要自动重试，也继续带上这个值。要是用户重新编辑了购物车、改了收货地址之后再次点提交，那就是全新的业务动作，这时候得生成一个新的Key。

这里千万不要把 Idempotency-Key 当成用户身份标识来用，也不要做成可以预测的自增编号。它本质上只是一次提交动作的临时票据，随机生成、短期有效，唯一作用就是防重复提交。

Go 接口怎么落地幂等状态

最精简的可用版本可以先抽象出一个统一的存储接口。生产环境一般存在MySQL、PostgreSQL或者Redis里，核心要求只有一个：「抢占同一个Key的处理权」这一步必须是原子性的。谁先成功抢到键，谁就有权限跑后续的业务逻辑；后面到的所有请求都只能直接读取已经存在的状态记录。

type IdempotencyStore interface {
    Reserve(ctx context.Context, key string, hash string, ttl time.Duration) (Record, bool, error)
    MarkSucceeded(ctx context.Context, key string, response []byte) error
    MarkFailed(ctx context.Context, key string, message string) error
}

type Record struct {
    Key          string
    RequestHash  string
    Status       string
    ResponseBody []byte
}

Reserve 同时返回两个信息：当前Key对应的幂等记录详情，以及这次请求是不是成功抢到了处理权。抢到处理权的请求就可以继续往下走创建订单的业务逻辑；没抢到的请求，直接拿已有的状态记录判断该返回什么内容就行。这样业务代码里就不会到处散落零散的「提前查下有没有重复订单」的判断逻辑，所有幂等相关的处理都统一收敛在入口层。

func CreateOrder(store IdempotencyStore, svc OrderService) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        ctx := r.Context()
        key := r.Header.Get("Idempotency-Key")
        if key == "" {
            http.Error(w, "missing Idempotency-Key", http.StatusBadRequest)
            return
        }

        body, err := io.ReadAll(r.Body)
        if err != nil {
            http.Error(w, "read body failed", http.StatusBadRequest)
            return
        }
        hash := hashRequest(body)

        rec, owner, err := store.Reserve(ctx, key, hash, 30*time.Minute)
        if err != nil {
            http.Error(w, "reserve key failed", http.StatusInternalServerError)
            return
        }
        if !owner {
            replyExisting(w, rec, hash)
            return
        }

        resp, err := svc.Create(ctx, body)
        if err != nil {
            _ = store.MarkFailed(ctx, key, err.Error())
            http.Error(w, "create order failed", http.StatusInternalServerError)
            return
        }

        _ = store.MarkSucceeded(ctx, key, resp)
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(http.StatusCreated)
        _, _ = w.Write(resp)
    }
}

这段代码有个很实用的细节：请求体读完之后先算一遍内容指纹。如果重复请求带着同一个Idempotency-Key，却偷偷把商品、金额、收货地址这类核心参数改了，服务端不能假装没看见直接走逻辑，这时候应该直接返回参数冲突的提示。

响应缓存和处理中状态怎么返回

写幂等接口最容易踩坑的地方，就是识别到重复请求之后，只会生硬返回一句「请勿重复提交」。这种处理对用户体验非常差：要是第一次请求其实已经下单成功了，只是网络丢包导致响应没传到客户端，用户拿不到订单号，大概率还是会忍不住反复点提交按钮。

更稳妥的做法是把第一次请求成功返回的完整响应完整缓存下来。后续碰到同一个Key、同一个请求指纹的请求进来，直接把这份缓存的响应原封不动返回，同时带上 Idempotent-Replayed: true 这类特殊的响应头，方便后续排查链路日志。

func replyExisting(w http.ResponseWriter, rec Record, currentHash string) {
    if rec.RequestHash != currentHash {
        http.Error(w, "same key with different request body", http.StatusConflict)
        return
    }

    switch rec.Status {
    case "succeeded":
        w.Header().Set("Content-Type", "application/json")
        w.Header().Set("Idempotent-Replayed", "true")
        w.WriteHeader(http.StatusOK)
        _, _ = w.Write(rec.ResponseBody)
    case "processing":
        http.Error(w, "request is still processing", http.StatusConflict)
    default:
        http.Error(w, "previous request failed, please retry with a new key", http.StatusConflict)
    }
}

如果业务逻辑本身耗时很短，处理中状态可能只会持续几十毫秒就结束；要是创建订单的链路后面还要走库存扣减、优惠券校验、支付预占这类多步操作，处理中状态出现的概率就会高很多。这里不建议让后到的重复请求长时间阻塞等结果，接口层可以直接返回冲突状态，让前端展示「正在提交，请稍候再试」的提示就足够。

上线前要检查哪些边界

幂等防重复的逻辑不是加个请求头就完事，真正容易出问题的全是边缘场景。上线前建议至少过一遍下面的校验清单：

• 同一个 Idempotency-Key、同一个请求体连续提交两次，第二次是不是能直接返回第一次生成的订单结果。
• 同一个 Idempotency-Key、但请求体核心参数被修改后提交，是不是能返回 409 提示，而不是偷偷生成第二个重复订单。
• 第一次请求服务端已经处理成功，但客户端那边超时断开了，后续重试能不能正常拿到已经生成的订单号。
• 业务逻辑执行失败之后，能不能支持用户换一个全新的Idempotency-Key重试，旧的失效Key有没有明确标记失败状态。
• 幂等记录过期之后，新提交的正常请求会不会被误判成重复请求拦截。
• 全链路日志里能不能通过 Idempotency-Key 把第一次请求和后续所有的重试请求串起来，方便排障。

生产环境更推荐先把这套逻辑部署到少数高风险接口上，比如创建订单、提交活动报名、发起支付、领取权益这类场景。普通查询类接口没必要硬套这套流程，平白增加存储压力和代码复杂度。

常见问题

Idempotency-Key 应该放请求头还是放请求体？

更推荐放在请求头里。它描述的是这次提交动作的身份标识，不属于业务订单本身的字段；放在请求头里，也方便网关、日志链路和中间件统一做解析处理，不用提前解析整个请求体。

只用数据库唯一索引能不能防重复提交？

唯一索引能兜住一部分重复写入的场景，但它只能粗暴告诉你「第二次写入失败了」。完整的幂等状态表还能存储第一次的响应结果、处理中状态、请求参数指纹这些信息，给用户的反馈会更友好完整。

Idempotency-Key 过期时间设多久合适？

跟着业务的重试窗口走就行。普通下单接口从15到30分钟开始配置就够用；支付、外部回调这类链路更长的场景，要结合第三方平台的重投策略和订单的整体生命周期一起定。

前端还需要禁用按钮吗？

当然需要。前端禁用按钮负责减少用户误点、做直观的状态提示；服务端幂等逻辑做最后兜底。两者是互补关系，完全不能互相替代。

小结

Go接口防重复提交的核心思路，是把每一次用户发起的业务动作，变成可识别、可复用、可追踪的独立状态记录。前端按钮禁用可以帮用户少犯误点的错，服务端还要靠 Idempotency-Key、请求指纹、状态表和响应缓存，兜住网络重试、第三方重复回调、请求异常断开这类极端场景。先从创建订单这类高风险接口落地跑通流程，再慢慢抽象成通用中间件，会比一开始全站强制推这套方案更稳妥。