微信小程序 / H5 调用第三方 API 的正确姿势:先定请求出口,再写失败分支
一句话回答
调用第三方 API 前要先确定请求从哪一层发出:私密密钥不能进客户端,需由自有服务端代理;H5 还受浏览器同源策略和对方 CORS 响应约束。客户端侧应把超时、状态码与业务码判断、错误上下文写进同一层封装,并只对幂等请求重试。平台侧的域名白名单、协议与登录态规则本次无官方文档可核,接入前需对照官方文档确认。
调用第三方 API 的“正确姿势”可以拆成两个可回答的问题:请求从哪一层发出,以及失败时客户端凭什么判断。前者决定密钥与配额暴露在哪里,后者决定上线后能否定位问题。下面按这两条线展开。涉及各平台的具体配置项与限制,本次没有官方文档可供核对,接入前请以官方文档为准。
一、先定请求出口,再谈写法#
| 形态 | 密钥在哪 | 适用场景 | 代价 |
|---|---|---|---|
| 客户端直连第三方 | 客户端 | 接口不需要私密凭据、且对方允许浏览器或小程序直接访问 | 任何放进客户端的值都可被提取 |
| 自有服务端代理 | 服务端 | 接口需要私密 key、按 key 计费或限流 | 多一跳,需要自己承担转发层的可用性 |
| 服务端代理 + 缓存/队列 | 服务端 | 第三方限流严格、响应可复用 | 引入一致性问题和额外组件 |
这里的判断依据是凭据的性质,而不是代码好不好写。推断:如果第三方按 key 计费或按 key 限流,那么把 key 放进客户端,等于把额度控制权交给任何能打开开发者工具的人。这类接口应默认走服务端代理。
二、客户端直连前,先确认三类平台限制#
- 域名与协议:小程序侧一般要求把请求域名配置在平台后台并使用 HTTPS,具体规则、生效时间与是否需要备案,以微信官方文档为准(本次未核实)。
- 跨域:H5 受浏览器同源策略约束,第三方是否返回允许跨域的响应头不由你决定。如果对方不返回,浏览器侧无法绕过,只能改为经自有服务端转发。
- 登录态与 Cookie:需要用户态或 Cookie 的接口,在 H5 与小程序里的携带方式不同,按各自平台文档核实。
三、把“能判断成功与否”写进同一层封装#
下面的示例仅示意结构,未执行;域名为占位,不能当作真实端点。小程序侧对应 wx.request,分层思路相同。
// 未执行的示例:结构示意,域名为占位
const API_BASE = 'https://api.example.com'; // 占位,非真实端点
async function callApi(path, { method = 'GET', body, timeout = 8000 } = {}) {
const started = Date.now();
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeout);
try {
const res = await fetch(API_BASE + path, {
method,
headers: { 'Content-Type': 'application/json' }, // 私密密钥不放这里
body: body ? JSON.stringify(body) : undefined,
signal: controller.signal,
});
const data = await res.json().catch(() => null);
return {
ok: res.ok && data?.code === 0, // 状态码与业务码分开判断
status: res.status,
data,
ms: Date.now() - started,
};
} catch (err) {
return { ok: false, status: 0, error: err.name, ms: Date.now() - started };
} finally {
clearTimeout(timer);
}
}
建议至少保留三样东西:超时、status 与业务码的分离结果、以及耗时。缺了耗时,弱网问题在日志里就只剩“失败”两个字。
四、重试要有边界#
- 只对幂等请求(查询、拉取详情)和网络类错误重试,采用有限次数的退避。
- 下单、支付、扣减额度这类非幂等操作不要自动重试;如果重试,必须带幂等键,由服务端去重。
- 把重试次数与最终结果一起上报,否则监控里看到的请求量会高于真实业务量。
五、上线前的核对清单#
- 私密凭据是否只出现在服务端。
- 请求域名、协议是否符合平台要求(对照官方文档,待核实)。
- 超时时间是否小于用户可接受等待,且短于页面级超时。
- 错误分支是否区分“网络失败”“HTTP 错误”“业务码失败”。
- 日志中是否已脱敏,不写入完整密钥或用户敏感字段。
总结一句:出口决定安全边界,封装决定可维护性。前者要在写第一行代码前定下来,后者可以随排查经验逐步补齐。