技术文章

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

小程序与 H5 调用第三方 API 的正确姿势:把差异关进封装层,把错误当成契约

一句话回答

小程序与 H5 调用第三方 API 的三个关键点:长期密钥只留在服务端,客户端使用短期凭证;两端差异收敛到一层 transport 封装;域名白名单、超时与错误分类需在上线前按契约验证。平台具体配置项与限制本次无可核验材料,需查官方文档。

可以浓缩成三句话:长期密钥留在服务端,客户端只拿短期凭证;小程序与 H5 的差异收敛在一层请求封装里,而不是散进业务代码;域名白名单、超时和错误分类在开发阶段就按契约验证,而不是上线后再补。以下是建议做法。涉及微信平台具体配置路径、数量上限与请求行为的细节,本次没有可核验的官方正文,均标注为待核实。

一、先判断这个 API 该由谁调用#

第三方 API 大致分两类,处理方式不同:

  • 服务端调用:提供方给的是长期 API Key 或 Secret,请求应由小程序或 H5 所在的后端发出,客户端只调自己的业务接口。
  • 客户端直连:只在提供方明确支持公开客户端(如带来源限制的公开接口、OAuth 授权码流程)时才适用,且不能携带长期密钥。

小程序包和 H5 的 JavaScript 都会下发到用户设备,把 Secret 写进前端等于公开。这是通用判断,不是针对某个平台的漏洞结论。

二、两端的差异在哪#

能力微信小程序H5
请求域名需在平台侧配置合法域名,具体入口与数量上限待核实无平台级白名单,受浏览器同源策略与 CORS 约束
跨域不涉及浏览器 CORS第三方域名需返回正确的 CORS 响应头
会话传递网络请求不依赖浏览器 Cookie 机制,通常靠请求头传递(概括,具体以官方文档为准)浏览器按同源与 SameSite 规则自动携带 Cookie
运行环境受平台基础库版本影响,待核实受浏览器版本影响

三、把差异关进一个适配层#

定义一个 transport 接口,业务代码只依赖它,平台差异在各自的实现里处理。

// 未执行示例:仅示意结构,不针对任何真实端点
export function createClient({ transport, baseURL, getToken }) {
  async function request(path, { method = 'GET', body, timeout = 8000 } = {}) {
    const token = await getToken(); // 短期凭证,由自己的后端签发
    const res = await transport({
      url: baseURL + path,
      method,
      headers: {
        'content-type': 'application/json',
        ...(token ? { authorization: 'Bearer ' + token } : {}),
      },
      body: body === undefined ? undefined : JSON.stringify(body),
      timeout,
    });
    if (!res.ok) throw new ApiError(res.status, await res.text());
    return res.json();
  }
  return { request };
}

两个 transport 实现的关键差别:小程序侧由 wx.request 发起并依赖已配置的合法域名;浏览器侧由 fetch 发起,跨域是否成立取决于对方响应头。封装层要统一返回结构,让上层不必写两套解析。

四、错误和超时也是契约#

  • 至少区分四类:网络或超时失败、HTTP 状态码、业务错误码、响应解析失败。四类的提示文案与重试策略不应混用。
  • 只对幂等请求做有限重试,并设总时长上限;写操作靠幂等键,而不是靠重试碰运气。
  • 业务侧超时应小于平台或网关的限制,具体数值待核实。

五、上线前的验证清单#

  1. 用一条最小可复现请求打通链路,记录请求头、状态码与响应体结构。
  2. 确认生产域名已进白名单,且与测试环境分离。
  3. 断网、慢网、5xx 三种情况各验证一次提示与重试行为。
  4. 在构建产物中搜索密钥关键词,确认 Secret 未被打包。
  5. 验证凭证过期后的刷新路径,以及刷新失败时的降级表现。

平台侧的具体限制建议直接查阅官方文档对应章节,不要用二手总结替代。本文的代码与清单是结构建议,未在真实环境中执行。

作者:沐小悠

本文约 5 分钟读完 · 关键词:微信小程序、H5、第三方 API、请求封装、域名白名单

更多文章 GET 示例接口

「」标签下的其他文章