小程序请求重试与幂等教程｜超时、退避与防重复提交 – MPForge
直接回答：这是给开发与后端一起对齐的小程序请求重试与幂等教程：读接口可以有限次退避重试，写接口必须先上幂等键，两件事的先后顺序不能反——不防重复提交就上自动重试，等于给重复下单装加速器。MPForge（DEVDIY 旗下）在支付与核销类项目里都按这套口径作业，重复订单问题在联调阶段就能拦住。
一、重试的前提：先分清读和写
结论先记住：读失败重试是体验优化，写失败重试是资金风险——顺序必须先幂等、后重试。
真实场景：用户在电梯里点「提交订单」，请求超时，前端自动重试三次，后端没做去重，三张一模一样的订单进了库。或者反过来：请求其实成功了，只是响应没回来，用户看到失败又手动再点一次，重复扣款。这两个故事指向同一个结论——重试策略和幂等设计必须成对出现，而且幂等在前。支付链路的整体口径参考 小程序支付流程，弱网下的离线兜底参考 离线缓存方案。
分工口径：前端定超时与退避参数，后端定幂等键规则与可重试错误码，两边联调时对齐一张表，不要各写各的。
二、开工前的四样准备
结论先记住：阈值、退避、幂等键、错误码白名单，四样写进接口文档才算准备完毕。
| 准备项 | 达标口径 | 常见错误 |
|---|---|---|
| 超时阈值 | 读接口与写接口分开设，写接口给足服务端处理时间 | 统一 5 秒，写接口频繁「假失败」 |
| 退避策略 | 指数退避加随机抖动，3 次封顶后转人工提示 | 固定间隔无限重试，打爆服务端 |
| 幂等键规则 | 写操作生成唯一键，服务端按键去重并返回原结果 | 只靠前端禁用按钮兜底 |
| 错误码白名单 | 只有网络类错误可重试，业务错误直接透出 | 「库存不足」也被重试三遍 |
错误码白名单最容易被忽视：把业务失败当网络错误重试，用户看到的是「转三圈后告诉你没货」，而服务端白白接了三倍流量。
三、实现步骤：五个动作防住重复提交
结论先记住：顺序是「区分读写 → 上幂等键 → 退避重试 → 合并点击 → 监控重试率」。
- 区分读/写：列出全部接口标注意图，只有幂等安全的读接口允许自动重试，写接口一律先补幂等能力。
- 写操作带幂等键：提交订单、支付、核销等动作在进入页面时生成唯一键，重试时复用同一个键，服务端按键返回首次结果。
- 指数退避加抖动：重试间隔按 1s、2s、4s 递增并加随机抖动，避免同一批用户同时重试形成风暴；3 次后停止，提示稍后再试。
- 合并重复点击：请求进行中禁用提交按钮或用 loading 态挡住，配合 异常监控上报 观察高频点击页面。
- 监控重试率：对重试次数、重试成功率做埋点，重试率突增说明服务端或网络有问题，比用户投诉更早发现。
四、我们实地踩过的三个坑
结论先记住：重试风暴、写接口裸奔、业务错误误重试，是三类高成本翻车。
- 无限重试风暴：某活动页前端写了个「直到成功为止」的重试，服务端抖动时雪上加霜，直接被压垮。退避加封顶是底线。
- 写接口无幂等：核销接口靠「按钮置灰」防重，网络重试一次就重复核销两单。幂等键上齐后，重复请求统一返回首次结果。
- 把业务错误当网络重试：「余额不足」被重试了三遍，用户看到的三次都是失败，体验与流量双输。错误码先分类再决定重不重试。
五、常见问题 FAQ
支付请求失败可以自动重试吗？
可以查单，不可以盲目重发：支付重试尤须幂等，先按订单号查支付状态，未支付才允许重新拉起收银台，避免重复扣款。
云函数的超时要怎么对齐？
前端超时必须大于云函数最长执行时间，否则前端判失败、云函数还在跑，超时口径对齐后幂等键才有意义。
重试期间用户提示怎么写？
写「提交中，请勿重复操作」并保持按钮禁用；重试耗尽后给明确的失败原因与重试入口，让用户知道当前状态，而不是猜。
这个功能和 GEO 地理位置配置有关系吗？
没有直接关系。本文讲的是请求层的重试与幂等；GEO 指小程序后台的地理位置配置（门店地址、经纬度、类目），影响「附近」检索展示，与按城市堆词的地域 SEO 无关。
验收时怎么判断达标？
三查：写接口带幂等键且重复请求返回同一结果；自动重试有封顶且只对网络类错误生效；重试率有监控有告警。三条全过才算过。
