核销是写操作,一次成功就改变了券状态和钱。所以它比查询接口更需要幂等保护,而实际上大多数接入方都没做。

一、重复请求从哪来

来源机制频率
超时重试请求已生效但响应超时,客户端重发高
用户重复点击服务员看到没反应又点一次高
网络重试网关/SDK 对失败请求自动重试中
消息重投异步队列至少一次投递语义中
补单脚本定时任务重跑失败任务低但危险

二、四种方案对比

方案做法适用与局限
业务唯一键用订单号+券序号作唯一索引,重复插入直接冲突最简单可靠,前提是业务侧有稳定唯一键
幂等表单独存请求键与结果,重放时直接返回首次结果通用,需自行维护与清理
状态机前置校验操作前先查券状态,已核销则不再调用有效但有窗口期:查询与写入之间仍可能重复
接口原生幂等平台支持幂等键参数最理想,但依赖平台能力,不一定有

实际生产中通常是组合:幂等表做入口拦截,状态机做二次校验,业务唯一键兜底数据一致性。

三、幂等键怎么设计

幂等键要满足两个条件:同一次业务操作永远算出同一个键,不同的业务操作一定算出不同的键。

  • 推荐组成:门店ID + 券码 + 操作类型 + 业务时间戳(精确到秒或到单)
  • 不要在键里放自增ID、随机数、当前时间 —— 那样每次都不同,等于没做
  • 操作类型要区分:核销、撤销、查询是不同的操作,不能共用一个键
  • 券码若脱敏存储,键里要用原文,否则不同券可能撞键

四、超时之后该做什么

这是最需要明确规则的地方:

  1. 超时后不要立即重试核销
  2. 先调用查询券状态的接口,看这笔是否已核销
  3. 已核销 → 按成功处理,补记本地流水,不再发起核销
  4. 未核销 → 可以重试,仍带同一幂等键
  5. 查询本身也超时 → 进入待确认队列,由定时任务再查,不要凭猜测下结论

「待确认」这个状态必须有。没有它,系统只能二选一:当成成功(可能漏核)或当成失败(可能重复核)。

五、撤销也要幂等

撤销是反向写操作,重复撤销的后果和重复核销类似 —— 可能报错,也可能在宽松实现的系统里造成账目错乱。

  • 撤销同样用幂等键,键里含「撤销」这个操作类型
  • 撤销前先查状态:已撤销的不再调用
  • 撤销失败要区分「券状态不允许撤销」和「临时错误」,前者不要重试
  • 撤销成功后本地流水要同步标记,否则对账会多出一笔

六、日志与可观测

幂等做得好不好,事后只能靠日志判断。至少记录:

  • 幂等键、请求ID、是否命中幂等(命中时说明是重放)
  • 首次请求与重放请求的时间差
  • 每次请求的实际结果(成功/失败/超时/待确认)
  • 最终状态,以及是由哪一次请求确定的

有了「是否命中幂等」这个字段,才能统计出真实的重复率,也才能证明幂等确实在起作用。

常见问题

平台接口本身支持幂等吗?

部分接口支持传入外部单号,部分不支持。接入时应确认,不能假设。不支持的接口必须自己在上层做幂等。

幂等记录要保留多久?

至少覆盖「可能重试的最长窗口」。建议保留 7 天以上,与对账周期对齐,便于事后追溯。