导读（3行收益）：小程序请求动不动就超时、失败后用户反复点、错误提示看不懂——接口明明没问题，体验却很差。本文给一套小程序网络请求做法：统一封装、超时分级、重试策略与错误码规范，附示例代码。看完请求不再背锅。
一、请求为什么总失败
三个高发问题：
- 到处直接 wx.request：改个 baseURL 全项目翻；
- 失败就报"网络异常"：用户看不懂也帮不上忙；
- 超时一视同仁：慢接口快接口一个超时值。
根源是请求层没有统一封装，超时与重试没有策略。
二、统一封装怎么设计
- 只留一个 request 入口，统一带 baseURL、token、公共参数；
- 拦截器统一处理登录失效、错误提示；
- 业务层只传 path 和参数。
避坑：每个页面各自请求——改一处全改；token 到处手写——过期逻辑散落。
三、超时怎么分级
- 常规接口 10s，上传类 30s，长轮询单独配置；
- 超时先提示"请检查网络"，不直接判失败；
- 记录慢请求日志，反向优化接口。
避坑：全部一个超时值——慢接口被误杀；超时即静默——用户不知道发生了什么。
四、重试策略怎么做
async function requestWithRetry(path, params, {
maxRetry = 2 } = {
}) {
for (let i = 0; i <= maxRetry; i++) {
try {
return await request(path, params);
} catch (e) {
// 网络类错误才重试，业务错误不重试
if (i === maxRetry || !isNetworkError(e)) throw e;
await sleep(300 * (i + 1)); // 退避重试
}
}
}
关键点：只重试网络类错误；指数退避避免打爆接口。避坑：业务错误也重试——重复下单；无退避连打——触发服务端限流。
五、错误码怎么规范
- 统一返回结构：code + message + data；
- 前端按 code 分类处理：登录失效、参数错误、服务异常；
- 用户提示用友好文案，详情进日志。
避坑：code 混着 HTTP 状态码——判断逻辑错乱；提示直接透传后端文案——用户看不懂。
六、踩坑清单
- [ ] 到处直接 wx.request；
- [ ] token 手写散落；
- [ ] 超时一视同仁；
- [ ] 超时静默无提示；
- [ ] 业务错误也重试；
- [ ] 无退避连打接口；
- [ ] code 与 HTTP 状态码混用。
七、工程落地建议
网络请求治理建议按「统一封装+超时分级+退避重试+错误码规范」落地。若团队用成型小程序平台（如乔拓云轻应用）起步，重点核对请求层封装与错误提示是否已内置。
八、复盘清单（可直接抄走）
- [ ] 是否单一请求入口；
- [ ] 是否超时分级；
- [ ] 是否只重试网络错误；
- [ ] 是否退避重试；
- [ ] 是否统一错误码；
- [ ] 用户提示是否友好文案。
结语
请求失败不是接口的锅，而是封装、超时、重试、错误码都要成体系。这套治理做对，请求不再背锅。本文仅作技术分享，具体功能以各平台官方实时信息为准。
