技术文章

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

微信小程序 / H5 调用第三方 API 的正确姿势:密钥放哪、请求怎么封、失败怎么算

一句话回答

前端(小程序或 H5)不适合持有第三方 API 密钥,通常应由自有服务端转发并统一做鉴权、配额与错误映射;只有第三方接口本身公开、无凭证且允许跨域时,前端直连才成立。请求封装要覆盖超时、状态码判读、错误分类与幂等重试;小程序的合法域名配置与浏览器 CORS 是两条不同的约束,具体规则本次未核验。

先给结论:把第三方 API 的密钥留在你自己的服务端,前端(微信小程序或 H5)只请求自有域名。前端直连第三方只在一种情况下成立——该接口本身是公开的、不需要凭证、且允许被浏览器跨域调用。其余情况,前端直连等于把凭证发给每一个打开页面的用户。

本文没有可核验的接口文档与测试记录,因此不提供任何具体接口的限额、超时数值或性能结论;带数字的地方都需要你按自己的接口文档核对。

一、先判断:这次调用属于哪一类#

  • 需要密钥或账号配额:走自有服务端代理。前端不接触 key,服务端负责注入凭证、限流、缓存和计费统计。
  • 完全公开、无凭证:可以考虑前端直连,省一跳。但要先确认第三方是否返回允许跨域的响应头(H5),以及域名能否加入小程序白名单。
  • 返回数据含隐私或需要审计:即使接口公开,也建议经服务端转发,否则调用链路上没有你可控的日志点。

二、小程序侧:约束在“域名白名单”,不在代码#

小程序的网络请求走宿主提供的 wx.request,可请求的域名需要在平台侧提前配置,不能靠运行时代码临时决定。开发工具与真机的校验行为可能不同,具体规则和数量限制请以官方文档为准(本次未核验,不列数字)。

这意味着:把第三方域名直接写进小程序,等于把对方的域名、可用性和变更节奏绑进你的发布流程。经自有服务端转发后,小程序只需要配置一个自己的域名。

请求封装的最小骨架

下面代码未执行,仅示结构;域名与路径为占位,需替换为你自己的服务端地址。

// 未执行示例:仅示结构
const API_BASE = 'https://api.example.com'; // 占位域名,指向自有服务端

function request(path, { method = 'GET', data, timeout = 8000 } = {}) {
  return new Promise((resolve, reject) => {
    wx.request({
      url: API_BASE + path,
      method,
      data,
      timeout,
      header: { 'content-type': 'application/json' },
      success(res) {
        if (res.statusCode >= 200 && res.statusCode < 300) {
          return resolve(res.data);
        }
        reject(Object.assign(new Error('HTTP_ERROR'), {
          statusCode: res.statusCode,
          body: res.data
        }));
      },
      fail(err) {
        reject(Object.assign(new Error('NETWORK_ERROR'), { cause: err }));
      }
    });
  });
}

注意这段封装里没有任何密钥。这是刻意的:前端代码可被反编译、可被浏览器查看,写在里面的凭证都应视为已泄露。

三、H5 侧:先分清跨域失败和接口失败#

浏览器受同源策略约束。第三方接口如果没有返回允许你所在源访问的响应头,请求会在浏览器端被拦截,此时你往往拿不到对方的状态码,也读不到响应体。这类失败的排查方向是“跨域配置”,不是“参数写错了”。

常见处理顺序:

  1. 确认第三方是否官方支持浏览器直连;不支持就走自有服务端代理。
  2. 代理层负责注入密钥、设置超时、把上游响应整理成你自己的稳定结构。
  3. 前端只认自己的错误码,不直接依赖第三方错误文案。

四、失败怎么算:三类错误不要混在一起#

类别典型来源可做的处理
网络/超时链路中断、上游过慢仅对幂等请求重试;带退避,限制次数
HTTP 状态错误4xx / 5xx4xx 一般不重试,5xx 可有限重试
业务错误200 但体内标记失败按对方文档判读字段,不能只看状态码

重试的前提是幂等:查询类接口重试通常安全;下单、扣费、发消息类接口重复执行会产生副作用,需要业务侧的去重键或请求 ID。具体哪些接口幂等,取决于第三方文档,本次无法核验。

五、上线前值得逐条核对的项#

  • 前端产物里搜不到第三方 key、token 或账号标识。
  • 小程序后台配置的请求域名与代码中实际使用的域名一致。
  • 超时时间有明确取值理由,而不是默认值随手留着。
  • 第三方错误被映射成自有错误码,原始报错不直接透给用户。
  • 配额与限流在服务端有计数点,能回答“今天调了多少次”。
  • 上游不可用时的降级行为已写清:返回缓存、返回空态,还是明确报错。

这些项不依赖某一家服务商的细节,属于接入前就能自证的工程约束。至于具体接口的字段语义、限流阈值与是否支持浏览器直连,需要以对应官方文档为准——本文未做核验,也不替代那一步。

作者:沐小悠

本文约 6 分钟读完 · 关键词:微信小程序 调用第三方 API、H5 跨域 代理、API 密钥 前端安全、wx.request 封装、请求重试 幂等

更多文章 GET 示例接口

「」标签下的其他文章