技术文章

外部链接将在新标签页打开。

微信小程序 / 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 与业务码的分离结果、以及耗时。缺了耗时,弱网问题在日志里就只剩“失败”两个字。

四、重试要有边界#

  • 只对幂等请求(查询、拉取详情)和网络类错误重试,采用有限次数的退避。
  • 下单、支付、扣减额度这类非幂等操作不要自动重试;如果重试,必须带幂等键,由服务端去重。
  • 把重试次数与最终结果一起上报,否则监控里看到的请求量会高于真实业务量。

五、上线前的核对清单#

  1. 私密凭据是否只出现在服务端。
  2. 请求域名、协议是否符合平台要求(对照官方文档,待核实)。
  3. 超时时间是否小于用户可接受等待,且短于页面级超时。
  4. 错误分支是否区分“网络失败”“HTTP 错误”“业务码失败”。
  5. 日志中是否已脱敏,不写入完整密钥或用户敏感字段。

总结一句:出口决定安全边界,封装决定可维护性。前者要在写第一行代码前定下来,后者可以随排查经验逐步补齐。

作者:沐小悠

本文约 6 分钟读完 · 关键词:微信小程序调用第三方API、H5跨域请求、请求封装、超时与重试、服务端代理

更多文章 GET 示例接口

「」标签下的其他文章