技术文章

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

小程序与 H5 调用第三方 API:先决定谁发起,再谈怎么发

一句话回答

客户端直连第三方 API 的可行性取决于两端各自的约束:小程序受后台配置的 request 合法域名限制,H5 受浏览器同源策略与对方 CORS 响应头限制。更稳的做法是把第三方调用收敛到服务端出口,客户端只下发业务参数;密钥、超时、重试与错误归一都在服务端完成。调用失败应分层处理,HTTP 200 不等于业务成功。文中平台规则的具体判定与数值需以官方文档核对,本次未联网验证。

核心要点 TL;DR
  • 直连方案要同时在小程序域名配置和对方 CORS 两头成立,缺一不可。
  • 密钥不放在小程序包或前端代码里,两者都能被读出。
  • 把网络失败、HTTP 状态、业务码、响应结构分开处理,避免把 200 当成功。

结论先行:讨论“调用姿势”之前,先回答一个问题——这次请求该由谁发起。微信小程序和 H5 都能发出 HTTPS 请求,但两者能不能直达第三方 API,取决于各自的平台约束;只要涉及密钥、需要重试与对账、或对方不支持跨域,就应该走服务端出口,客户端只负责提交业务参数。

先判断这次调用该由谁发起#

可以用三个问题做初筛,任何一个答案为“是”,服务端出口都更合适:

  • 请求需要携带密钥吗?小程序包可被解包分析,H5 的前端代码对用户可见,长期密钥放在客户端等于公开。
  • 对方接口支持浏览器跨域吗?如果不返回相应的 CORS 响应头,H5 直连会在预检阶段失败;小程序不走浏览器同源策略,但另有域名配置这道门。
  • 需要统一重试、限流、日志或计费口径吗?这些逻辑放在客户端无法收敛,也无法防止被绕过。

三问都不触发时,客户端直连可以接受,例如调用公开的、无需凭证的查询接口。

两端各自的硬约束#

小程序侧:网络请求使用 wx.request,请求域名需在小程序管理后台配置为合法域名,通常要求 HTTPS。开发者工具里的调试开关不等于线上可用——真机与线上环境仍按后台配置校验。域名数量上限、审核要求与具体校验规则以微信官方文档为准,本文未联网核验。

H5 侧:受浏览器同源策略约束,跨域请求是否放行由对方服务端的 CORS 响应头决定,预检请求(OPTIONS)也可能被拦截。这一机制属于浏览器与 Fetch 标准的通用行为,具体细节可对照 MDN 或标准文本核对。

两者不能互相替代:小程序能直连,不代表同一套前端代码放到 H5 也能跑通。

客户端只做三件事#

把第三方调用收进服务端后,客户端代码会明显变薄:拼参数、设超时、分错误。下面两段均为未执行的示例,只示意结构,不代表任何真实端点或返回。

// 未执行示例:小程序端,占位域名,不带任何密钥
const API_BASE = 'https://api.example.com';

function callApi(path, data) {
  return new Promise((resolve, reject) => {
    wx.request({
      url: API_BASE + path,
      method: 'POST',
      data,
      timeout: 8000, // 具体取值按业务与平台限制自定
      header: { 'content-type': 'application/json' },
      success(res) {
        if (res.statusCode >= 200 && res.statusCode < 300) resolve(res.data);
        else reject({ kind: 'http', status: res.statusCode });
      },
      fail(err) { reject({ kind: 'network', err }); }
    });
  });
}
// 未执行示例:服务端出口,密钥只从环境变量读取
app.post('/api/proxy', async (req, res) => {
  try {
    const upstream = await fetch('https://third-party.example.com/v1/query', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer ' + process.env.UPSTREAM_KEY, // 占位:YOUR_KEY
        'content-type': 'application/json'
      },
      body: JSON.stringify(req.body),
      signal: AbortSignal.timeout(8000) // 需运行时支持,未核实你的环境
    });
    const body = await upstream.json();
    // 按契约判断业务码,而不是只看 HTTP 200
    res.status(upstream.ok && body.code === 0 ? 200 : 502).json(body);
  } catch (e) {
    res.status(504).json({ error: 'upstream_unavailable' });
  }
});

失败要分层,别把 200 当成功#

下表是按处理方式划分的建议,不是平台规定:

层次典型表现建议处理
传输层DNS、TLS、连接超时仅对幂等请求有限重试,其余提示网络异常
HTTP 状态401 / 403 / 429 / 5xx凭证与权限类不重试;限流类读取对方给出的重试提示
业务码HTTP 200 但响应体内 code 非成功值按对方契约映射,不计为成功
响应结构字段缺失、类型变化校验后再进入业务逻辑,异常时记录原始响应

上线前值得核对的项目#

  1. 请求域名是否已在后台配置,线上真机走一遍,而不只在开发者工具里自测。
  2. 客户端代码与打包产物中是否残留任何密钥。
  3. 超时值是否小于调用链上一层的超时,避免雪崩。
  4. 错误分类是否覆盖上面四层,日志里能否区分“没发出去”“发出去了失败”“成功了但业务失败”。
  5. 对方接口的限流口径、配额与计费方式,以对方文档为准——本次材料未提供,待核实。

把这几项定清楚,两端的差异就退化成配置问题,而不是上线后才暴露的故障。

作者:沐小悠

本文约 7 分钟读完 · 关键词:微信小程序 wx.request、H5 CORS、第三方 API 调用、服务端代理、BFF

更多文章 GET 示例接口

「」标签下的其他文章