技术文章

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

密钥放哪、失败怎么分:微信小程序 / H5 调用第三方 API 的出口选择

一句话回答

面向小程序与 H5 调用第三方 API 的场景,结论是:需要密钥、计费归属或调用审计的接口不适合从客户端直连,应经自建服务端或云函数中转;跨端差异收敛到统一请求层;失败按网络层、HTTP 层、业务层分类,只对幂等请求重试。文中涉及的小程序域名白名单与浏览器 CORS 具体规则本次未核验,以各自官方文档为准。

核心要点 TL;DR
  • 需要密钥或计费归属的第三方接口,前端只调自己的服务端,不直连。
  • 小程序与 H5 的差异集中在请求层,封装成同一入口后换端只改一处。
  • 重试只给幂等请求;4xx 不重试,429 先看 Retry-After。

小程序和 H5 都能发 HTTP 请求,但两者对“请求从谁的出口发出”的约束不一样。核心结论只有一句:只要第三方接口需要密钥、按调用计费或需要区分用户身份,就不要从客户端直连;把出口放在你能控制的服务端(自有服务器、云函数或云托管均可),前端只调用自己的接口。理由在于密钥在客户端藏不住、调用无法审计,与性能无关。

边界说明:本文未联网检索,也未引用任何官方文档正文。下文涉及的平台机制按通行设计描述,具体条目、入口与版本差异待核实,请以对应官方文档为准。

先判断:这个接口能不能直连#

  • 可以考虑直连:公开、无密钥、不按调用方计费、所有人拿到的内容一致,例如公开的静态资源或公开数据。
  • 不建议直连:地址里带 key/token、按调用量计费、需要绑定用户身份、需要留存调用记录。

两端的约束来源不同:小程序端发起网络请求受平台域名配置约束,未在平台侧配置的域名通常会被拒绝;H5 端受浏览器同源策略约束,跨域读取响应需要目标服务返回相应 CORS 响应头。这两条的具体规则与配置入口待核实,但方向是确定的——客户端不是自由的请求出口。

三种出口拓扑#

拓扑密钥位置可审计性适用
客户端直连第三方客户端(等同于公开)无,只能看前端日志公开、无密钥、不计费
自建服务端 / 云函数中转服务端环境变量可在服务端记录调用方、耗时、状态绝大多数业务接口
中转 + 缓存与限流服务端同上,且能约束总量多端复用同一接口、需控制成本

推断:对一个同时有小程序和 H5 的项目,中转层的收益主要来自“一处限流、一处换密钥、一处改协议”,而非单纯的转发。

把跨端差异收敛到一个请求层#

小程序用 wx.request,浏览器用 fetch,两者在参数命名、错误形态、超时控制上都不一致。建议对外只暴露一个 request(path, options),把差异关在实现里。下面这段是 未执行的示例,仅示结构,域名与路径均为占位:

// 未执行示例:占位域名,仅示意 H5 侧封装
const BASE = 'https://api.example.com'; // 占位

export async function request(path, { method = 'GET', body, timeout = 8000 } = {}) {
  const ctrl = new AbortController();
  const timer = setTimeout(() => ctrl.abort(), timeout);
  try {
    const res = await fetch(BASE + path, {
      method,
      headers: { 'content-type': 'application/json' },
      body: body ? JSON.stringify(body) : undefined,
      signal: ctrl.signal,
    });
    if (!res.ok) throw Object.assign(new Error('http'), { kind: 'http', status: res.status });
    return await res.json();
  } catch (e) {
    throw Object.assign(e, { kind: e.kind ?? 'network' });
  } finally {
    clearTimeout(timer);
  }
}

小程序侧需要另一份实现,对外签名保持一致。AbortController 在小程序运行环境中是否可用,取决于基础库与运行环境,待核实;不可用时改用框架自带的取消能力,不要省略超时。

失败分支:先分类,再决定是否重试#

  • 网络层失败(没连上、超时、被中断):先明确请求是否可能已到达服务端,再决定重试。
  • HTTP 4xx:参数或权限问题,重试通常无效;429 例外,但应先读 Retry-After。
  • HTTP 5xx 与业务错误码:业务错误码要走响应体解析,不能只看状态码。

建议:只对幂等请求自动重试(GET、或带幂等键的写操作),并设总预算(次数上限 + 总耗时上限),避免超时叠加放大流量。前端同时要有提交中状态,防止用户重复点击变成重复写入。

上线前的最小清单#

  1. 客户端请求的域名是否都已在平台侧配置(小程序)或已确认 CORS 策略(H5);具体入口待核实。
  2. 构建产物里搜一遍密钥字段,确认第三方 key 只出现在服务端配置中。
  3. 每个请求都有超时;重试有次数与总时长上限。
  4. 日志记录调用方、状态码、耗时,但不记录密钥与完整响应体。
  5. 换端验证:只改请求层实现,业务代码不动。

如果以上前两条无法确认,先不要上线,因为其余优化都建立在这个前提上。

常见问题(FAQ)

小程序能不能直接调用第三方 API?
技术上能发起请求,但受平台域名配置约束,且密钥会出现在客户端。需要密钥或计费归属的接口建议经服务端中转;具体域名规则待核实。
H5 调用跨域接口一定要服务端配合吗?
浏览器受同源策略限制,跨域读取响应需要目标服务返回相应 CORS 头。对方不提供时,只能由自己的服务端转发。

作者:沐小悠

本文约 6 分钟读完 · 关键词:微信小程序调用第三方API、H5跨域请求、API密钥安全、请求封装、失败重试

更多文章 GET 示例接口

「」标签下的其他文章