技术文章

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

微信小程序与 H5 调用第三方 API:密钥放在哪一层,请求就在哪一层发

一句话回答

小程序与 H5 调第三方 API 的共同难点不在于能不能发出请求,而在于把密钥、域名限制和超时重试放到正确的一层。只要对第三方 API 的调用需要长期密钥,就应由后端或云函数代发,客户端只调用自己的接口;跨域只影响 H5 浏览器侧,小程序侧受域名白名单约束,两者不能互相替代。错误形状、超时和重试应在代理层统一,具体平台的配置项和第三方配额需以官方文档核验。

核心要点 TL;DR
  • 需要长期密钥的第三方调用应收敛到后端或云函数,客户端只持有自己的会话凭证。
  • 跨域(CORS)与小程序域名白名单是两套机制,一个解决不了另一个的问题。
  • 超时与重试放在代理层统一处理,只对幂等请求重试;具体平台配置与第三方配额待核实。

先给结论:在小程序和 H5 里调用第三方 API,真正决定成败的不是“怎么发请求”,而是“请求从哪一层发出去”。凡是需要长期密钥、需要隐藏供应商、或需要统一限流与计费的调用,都应收到自己的后端或云函数里,客户端只调用自己的接口。跨域、域名白名单、超时与重试,都是这一决定的下游后果。

先决定谁发起:三种位置,各有前提#

客户端直连

适用于公开、无需密钥、或仅使用临时凭证的接口。优点是链路短、少一跳;代价是供应商地址、配额策略和错误细节全部暴露在客户端,后续更换供应商要发版。

后端代理

最常见的选择。密钥只存在于服务端环境变量中,客户端拿到的是自己系统的会话凭证。代理层可以统一做鉴权、限流、缓存、超时和日志,也能在供应商变更时保持客户端接口不变。代价是多一跳网络与服务端容量成本。

云函数中转

本质仍是后端代理,区别在部署与权限模型。适合调用量波动大、不想维护常驻服务的场景。是否适用取决于所选云平台的运行时长、出网策略与计费方式,这些属于具体平台事实,本次未核验,需查对应官方文档。

域名与跨域:两侧的限制不是一回事#

H5 的跨域限制来自浏览器:页面请求另一个源时,服务端必须在响应中给出相应的 CORS(Cross-Origin Resource Sharing,跨源资源共享)头,否则浏览器会拦截读取结果。这属于服务端配置问题,前端改代码解决不了。

小程序侧的请求则受可访问域名配置约束,通常需要在平台侧提前登记。按公开资料的常见说法,未登记的域名不会被放行;具体配置项名称、生效范围与审核要求应以对应官方文档为准,本文未核验。

关键推论:给第三方服务加 CORS 头,不会让小程序侧的域名限制消失;反过来也一样。如果两端都要支持,最省事的做法是让两端都指向自己的同一个代理域名。

密钥与身份:不要把长期密钥交给客户端#

  • 客户端可见的一切(包体、本地存储、网络请求)都应视为可被读取,不放置长期密钥。
  • 若必须直连,优先使用供应商提供的临时凭证或短时效令牌,并约束其权限范围。
  • 代理层用自己的凭证访问第三方,客户端凭证只用于访问代理,两者不要混用。
  • 密钥放环境变量或密钥管理服务,不写进代码仓库;泄露出路与轮换流程需单独设计。

错误、超时与重试:先统一形状#

代理层应把上游结果归一化为稳定形状:区分“客户端参数错误”“上游返回错误”“上游超时”“网络不可达”,不要把上游原始报错直接透传给前端。超时必须有明确上限,重试只对幂等请求做,且要有次数上限与退避。第三方接口的配额、计费与速率上限属于会变化的事实,需以其官方文档为准,本文不作断言。

一个最小转发示例(未执行)#

以下为结构示意,运行环境假定 Node.js 18+(自带 fetch),未实际执行;YOUR_API_KEY 与 api.example.com 均为占位,不是可用的真实服务。

// 未执行示例:仅演示“客户端 -> 代理 -> 第三方”的形状
import express from "express";

const app = express();

app.get("/api/weather", async (req, res) => {
  const ac = new AbortController();
  const timer = setTimeout(() => ac.abort(), 5000); // 明确超时上限
  try {
    const url = "https://api.example.com/v1/weather?city=" +
      encodeURIComponent(String(req.query.city ?? ""));
    const upstream = await fetch(url, {
      headers: {
        Authorization: `Bearer ${process.env.YOUR_API_KEY}`, // 只在服务端读取
        Accept: "application/json",
      },
      signal: ac.signal,
    });
    const body = await upstream.text();
    res.status(upstream.status).type("application/json").send(body);
  } catch (e) {
    // 区分超时与其他网络错误,不把上游细节直接透出
    res.status(504).json({ error: "upstream_unavailable" });
  } finally {
    clearTimeout(timer);
  }
});

app.listen(3000);

能确认与不能确认的边界#

本文能确认的是架构层面的取舍:密钥收敛到服务端、跨域与域名白名单是两套机制、超时与重试放在代理层统一。不能确认的是具体平台当前的配置项名称、审核规则、限额数值以及任何第三方的可用性与价格——这些需查阅对应官方文档,本文未联网核验,也无法替读者判断某个接口是否仍然可用。

落地时的最小检查顺序:先确定发起位置,再确定客户端凭据形式,然后配置域名与跨域,最后补超时、错误形状与日志。顺序反了,通常会在联调阶段反复回到第一步。

作者:沐小悠

本文约 6 分钟读完 · 关键词:微信小程序调用第三方API、H5跨域CORS、API密钥不落客户端、后端代理转发、超时与重试

更多文章 GET 示例接口

「」标签下的其他文章