技术文章

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

微信小程序 / H5 调用第三方 API 的正确姿势:密钥留在服务端,差异留在适配层

一句话回答

小程序与 H5 发起请求的路径不同:小程序走客户端原生网络,H5 走浏览器并受同源策略与 CORS 约束;但两者都运行在用户设备上,都不能安全持有第三方密钥。可行做法是让前端只调用自己的业务后端,由接入层统一完成鉴权、超时、重试、限流与错误归一化,再转发到第三方 API。本文给出这一结构的边界条件与一个未执行的示例骨架;涉及平台域名白名单、并发与超时上限的具体规则,本文未引用官方文档,数值待核实。

核心要点 TL;DR
  • 密钥、签名与第三方凭据只应存在于服务端,小程序代码包与浏览器存储都不安全。
  • 小程序不经过浏览器同源策略,但通常需要预先配置请求域名;H5 受 CORS 与预检约束,两者不能共用一套前端请求代码而不
  • 重试只对幂等请求开放;超时应分层设置,接入层超时短于上游超时才有意义。

结论先说:小程序和 H5 调用第三方 API 的差别,主要在“请求从哪条路径发出”;而两者共同的约束是——前端代码跑在用户设备上,不能安全持有第三方密钥。因此可复用的做法是:前端只调用自己的业务后端,由这一层接入层完成鉴权、超时、重试、限流与错误归一化,再由它转发到第三方 API。下文说明这套结构的边界和一个未执行的示例骨架。

先分清两条请求路径#

小程序通过 wx.request 一类的客户端接口发起请求,不经过浏览器的同源策略,因此不会产生 CORS 预检;但它通常需要在平台侧预先配置可请求的域名,具体规则、协议要求与数量上限,本文未引用官方文档,待核实。H5 则由浏览器发起,受同源策略约束,跨域请求需要上游返回相应的 CORS 响应头,非简单请求还会先发预检。

两条路径的差异只影响“怎么发出去”,不影响“谁持有凭据”。小程序代码包可以被解包查看,浏览器里的 localStorage、全局变量、URL 参数同样可被读取或记录,所以把第三方 secret 放进任何一端都不是合适做法。

密钥该放在什么位置#

  • 放在服务端环境变量或密钥管理服务中,不进入代码仓库,也不进入前端构建产物。
  • 不放在 URL 查询串里:URL 容易进入访问日志、代理日志与 Referer。
  • 不依赖“反编译成本高”作为防护手段;这属于推断性风险,不是可控边界。
  • 如需给前端发凭据,发的是你自己签发的短期令牌,而不是第三方密钥。

接入层要承担哪些职责#

关注点前端直连时的问题放在接入层怎么做
鉴权密钥必然暴露给客户端服务端持有凭据并完成签名
超时各端各自设置,无法统一按层设置,接入层超时短于上游超时
重试客户端重试易造成放大仅对幂等请求重试,设次数上限
限流与配额无法在设备侧统一按用户或业务方维度统一计数
错误归一化上游错误码泄漏到 UI映射为稳定的内部错误码
日志凭据容易被完整打印脱敏后再记录

示例:最小转发骨架#

以下为未执行的示例,仅示意结构,不针对任何真实上游,路径与字段均为占位。适用环境为 Node.js 运行时,未实际运行。

// 未执行示例:占位结构,不可直接用于生产
import http from "node:http";

const UPSTREAM = "https://api.example.com/v1/items"; // 占位域名
const KEY = process.env.THIRD_PARTY_KEY || "YOUR_KEY"; // 占位密钥

http.createServer(async (req, res) => {
  if (req.method !== "GET") return res.writeHead(405).end();
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 3000); // 接入层超时
  try {
    const upstream = await fetch(UPSTREAM, {
      headers: { Authorization: `Bearer ${KEY}` },
      signal: controller.signal,
    });
    const body = await upstream.text();
    res.writeHead(upstream.status, { "content-type": "application/json" });
    res.end(body);
  } catch (err) {
    res.writeHead(502, { "content-type": "application/json" });
    res.end(JSON.stringify({ code: "UPSTREAM_UNAVAILABLE" }));
  } finally {
    clearTimeout(timer);
  }
}).listen(8080);

重试与超时的边界#

建议而非规则:只对幂等请求重试,写操作要么不重试,要么携带幂等键;超时按层递进设置,客户端超时应长于接入层超时,接入层超时应长于上游典型响应时间,否则重试会在上游仍在处理时叠加。并发与超时的具体数值取决于平台与上游,本文不给出未经核验的数字。

前端适配差异清单#

  • 小程序:统一封装请求方法,集中处理域名配置、错误码与登录态失效;取消请求与页面切换要成对处理。
  • H5:确认上游或代理是否返回正确 CORS 头;不要用 JSONP 绕过跨域;预检失败时优先查响应头而不是改前端写法。
  • 两端共用同一套内部错误码,界面文案与网络实现解耦。

什么情况下可以考虑直连#

若接口是公开只读、无需任何密钥、上游明确支持跨域,且没有敏感性要求,可以让前端直接请求以省一跳。即便如此,也建议保留超时与降级路径,并把域名配置视为部署项而非代码项。涉及计费、写入或用户数据时,不适合直连。关于各平台当前的域名配置与并发限制,本文没有可核验的官方来源,待核实。

常见问题(FAQ)

小程序里能直接调用第三方 API 吗?
技术上小程序可以发起网络请求,不受浏览器同源策略限制;但是否可调用取决于第三方接口是否需要密钥、平台是否要求预先配置请求域名。需要密钥的接口不应由小程序端直接调用。
H5 遇到跨域就加一个代理,是不是就够了?
代理只解决了同源策略这一层。若代理把密钥写进前端可见的请求参数,或不做限流与错误归一化,问题只是被挪到了另一个位置。

作者:沐小悠

本文约 6 分钟读完 · 关键词:微信小程序调用第三方API、H5跨域 CORS、wx.request、BFF 接入层、API 密钥安全

更多文章 GET 示例接口

「」标签下的其他文章