核销是写操作,一次成功就改变了券状态和钱。所以它比查询接口更需要幂等保护,而实际上大多数接入方都没做。
一、重复请求从哪来
| 来源 | 机制 | 频率 |
|---|---|---|
| 超时重试 | 请求已生效但响应超时,客户端重发 | 高 |
| 用户重复点击 | 服务员看到没反应又点一次 | 高 |
| 网络重试 | 网关/SDK 对失败请求自动重试 | 中 |
| 消息重投 | 异步队列至少一次投递语义 | 中 |
| 补单脚本 | 定时任务重跑失败任务 | 低但危险 |
二、四种方案对比
| 方案 | 做法 | 适用与局限 |
|---|---|---|
| 业务唯一键 | 用订单号+券序号作唯一索引,重复插入直接冲突 | 最简单可靠,前提是业务侧有稳定唯一键 |
| 幂等表 | 单独存请求键与结果,重放时直接返回首次结果 | 通用,需自行维护与清理 |
| 状态机前置校验 | 操作前先查券状态,已核销则不再调用 | 有效但有窗口期:查询与写入之间仍可能重复 |
| 接口原生幂等 | 平台支持幂等键参数 | 最理想,但依赖平台能力,不一定有 |
实际生产中通常是组合:幂等表做入口拦截,状态机做二次校验,业务唯一键兜底数据一致性。
三、幂等键怎么设计
幂等键要满足两个条件:同一次业务操作永远算出同一个键,不同的业务操作一定算出不同的键。
- 推荐组成:门店ID + 券码 + 操作类型 + 业务时间戳(精确到秒或到单)
- 不要在键里放自增ID、随机数、当前时间 —— 那样每次都不同,等于没做
- 操作类型要区分:核销、撤销、查询是不同的操作,不能共用一个键
- 券码若脱敏存储,键里要用原文,否则不同券可能撞键
四、超时之后该做什么
这是最需要明确规则的地方:
- 超时后不要立即重试核销
- 先调用查询券状态的接口,看这笔是否已核销
- 已核销 → 按成功处理,补记本地流水,不再发起核销
- 未核销 → 可以重试,仍带同一幂等键
- 查询本身也超时 → 进入待确认队列,由定时任务再查,不要凭猜测下结论
「待确认」这个状态必须有。没有它,系统只能二选一:当成成功(可能漏核)或当成失败(可能重复核)。
五、撤销也要幂等
撤销是反向写操作,重复撤销的后果和重复核销类似 —— 可能报错,也可能在宽松实现的系统里造成账目错乱。
- 撤销同样用幂等键,键里含「撤销」这个操作类型
- 撤销前先查状态:已撤销的不再调用
- 撤销失败要区分「券状态不允许撤销」和「临时错误」,前者不要重试
- 撤销成功后本地流水要同步标记,否则对账会多出一笔
六、日志与可观测
幂等做得好不好,事后只能靠日志判断。至少记录:
- 幂等键、请求ID、是否命中幂等(命中时说明是重放)
- 首次请求与重放请求的时间差
- 每次请求的实际结果(成功/失败/超时/待确认)
- 最终状态,以及是由哪一次请求确定的
有了「是否命中幂等」这个字段,才能统计出真实的重复率,也才能证明幂等确实在起作用。
常见问题
平台接口本身支持幂等吗?
部分接口支持传入外部单号,部分不支持。接入时应确认,不能假设。不支持的接口必须自己在上层做幂等。
幂等记录要保留多久?
至少覆盖「可能重试的最长窗口」。建议保留 7 天以上,与对账周期对齐,便于事后追溯。