小程序 wx API Promise 化教程｜错误处理、超时与并发控制规范 – MPForge

一、为什么要统一封装：回调嵌套只是表象

先看清代价：每个项目各自手写 promisify，错误处理的口径就不可能统一，排查线上问题全靠猜。

wx 的回调式 API 用 success/fail/complete 三段表达结果，直接用会层层嵌套；各家自己包一层 Promise 又容易包出差异：有的吞掉 fail 分支、有的把 errMsg 字符串直接当错误抛、有的不设超时。真机上网络抖动是常态，一个没有超时的请求能让整个页面停在 loading。所以封装的目标不是「少写几个缩进」，而是把错误结构、超时、并发、日志四件事变成全项目的统一约定。

二、封装规范：错误、超时、并发三件套

结论先记住：错误对象必须结构化，超时和并发必须有默认值，三件事一个都不能少。规范对照：

三、落地步骤：从包装函数到单测覆盖

按这五步搭封装层，半天能落地一个新项目：

1. 写统一包装函数：接收 wx API 名与参数，返回 Promise；success 走 resolve，fail 转 reject 并带上结构化错误对象，complete 统一收口清理。
2. 加超时机制：用 Promise.race 包一层计时器，默认 10 秒；超时 reject 特定 code，调用方可据此降级或重试，重试口径参考小程序请求重试与超时处理。
3. 加并发队列：上传下载类调用进队列执行，默认并发 3；队列支持优先级，用户主动操作的请求插队。
4. 接日志上报：失败统一上报 api 名、耗时、errMsg，聚合到异常监控平台，参考小程序异常监控与上报说明。
5. 写单测钉行为：对成功、失败、超时、并发四类场景写单测；微信基础库逐步提供原生 Promise 版 API，封装要设计成可平滑替换。

四、验收口径：封装层算不算合格

基础设施的验收标准是「别的同事不需要看实现就能正确用」，按下表核对：

五、避坑清单

封装层最容易被塞进去的三颗雷：

• 别吞 errMsg：errMsg 是排查问题的第一现场，reject 时必须原样保留并上报，别在封装层里就把它丢掉。
• 别给所有 API 同一套超时：支付、上传、登录的合理超时各不相同，按 API 分类给默认值，允许调用处覆盖。
• 别在封装里藏业务逻辑：封装层只管技术口径，业务判断（比如「未登录跳登录页」）放拦截器或调用侧，否则封装会越改越不敢动。
• 别忘了 async/await 的 try/catch：await 后不加 catch，异常会变成未处理拒绝，行为比回调式更隐蔽，代码评审要盯。

六、常见问题 FAQ