技术文章

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

微信小程序 / H5 调用第三方 API:密钥、代理层与适配层怎么分工

一句话回答

小程序和 H5 都不应持有第三方 API 密钥,应把调用收敛到自家服务端代理层;两端在请求方式、超时、跨域与域名白名单上的差异,统一放到一层薄适配层处理,再向业务代码暴露归一化的响应与错误语义。文中给出了未执行的示例骨架,并列出需以官方文档核实的事项。

最简短的答案是:密钥不要出现在小程序包或 H5 页面里,第三方调用走自家服务端代理;小程序与 H5 的请求差异留在薄薄一层适配层,不要把差异渗进业务代码。下面分别说明这么做的原因、分层边界,以及哪些细节需要你回官方文档核实。

为什么不能在前端直连第三方#

小程序代码包可以被解包查看,H5 的 JavaScript 会完整下发到浏览器,任何写在客户端的 API Key 都等同于公开。因此即使第三方接口本身允许浏览器直接请求,只要它需要密钥或计费额度,就应该由服务端持有凭证并代为转发。

此外,两端都存在请求限制:H5 受同源策略约束,跨域请求需要对方返回正确的 CORS 响应头;小程序端的网络请求通常受请求域名白名单约束,具体配置入口、审核口径与限制条件以微信官方文档为准(本文未核实具体版本与细则,待核实)。

三层分工:代理层、适配层、业务层#

  • 服务端代理层:唯一持有密钥的地方。负责鉴权、参数校验、超时控制、限流与日志脱敏,把第三方的响应裁剪成自家契约。
  • 适配层:运行在客户端,只处理平台差异——请求 API、超时、存储、错误对象形态。它不关心业务字段含义。
  • 业务层:只消费归一化后的结果,不出现 wx. 或 fetch 之类环境相关调用。

需要提前确认的一点:第三方服务的条款是否允许你这样代理转发、是否对出口 IP 或调用频次有额外要求——这属于待核实项,不能默认为允许。

适配层示例(未执行)

以下代码仅示意结构,未实际执行,域名与凭证均为占位:

// 未执行的示例|占位域名 example.com,凭证来自服务端环境变量
const transport = {
  // 小程序环境:始终请求自家后端,不直连第三方
  weapp: (path, body) => new Promise((resolve, reject) => {
    wx.request({
      url: `/api/proxy${path}`,
      method: 'POST',
      data: body,
      timeout: 8000,
      success: (r) => (r.statusCode === 200 ? resolve(r.data) : reject(r.data)),
      fail: reject,
    });
  }),

  // H5 环境:同源请求,避免额外跨域配置
  h5: async (path, body) => {
    const r = await fetch(`/api/proxy${path}`, {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(8000),
    });
    if (r.ok) return r.json();
    throw await r.json().catch(() => ({}));
  },
};

注意 H5 侧写成相对路径 /api/proxy,是为了让请求与页面同源,把跨域问题留给服务端之间的调用,而不是留给浏览器。

把响应和错误先归一化#

第三方返回的字段名、错误码体系各不相同,若直接透传给业务层,换个供应商就要改遍调用点。建议代理层输出固定信封,例如 { ok, code, message, data },并约定三类可区分的情况:

  1. 调用方错误(参数不合法):不要重试。
  2. 上游错误(第三方超时、限流、5xx):可有限次退避重试,但对非幂等接口需先确认语义。
  3. 鉴权/额度错误:应告警而非重试,否则会放大计费或触发风控。

哪些状态码算可重试、重试几次、超时设多少,取决于具体第三方的文档与你的 SLA 要求,本文不给出统一数值。

落地前建议确认的边界#

  • 第三方的服务条款、配额与价格:待核实,不同版本差异可能很大。
  • 小程序请求域名白名单的具体要求与审核规则:以官方文档为准。
  • 代理层日志是否记录了不该记录的字段(凭证、用户标识):建议默认脱敏。
  • 密钥轮换路径:密钥只在服务端,轮换才不会牵动客户端发版。

一句话收束:密钥归服务端,平台差异归适配层,语义归一化归代理层,业务代码只认自家契约。

作者:沐小悠

本文约 5 分钟读完 · 关键词:微信小程序、H5、第三方 API、服务端代理、适配层

更多文章 GET 示例接口

「」标签下的其他文章