微信小程序与 H5 调用第三方 API:密钥放在哪一层,请求就在哪一层发
小程序与 H5 调第三方 API 的共同难点不在于能不能发出请求,而在于把密钥、域名限制和超时重试放到正确的一层。只要对第三方 API 的调用需要长期密钥,就应由后端或云函数代发,客户端只调用自己的接口;跨域只影响 H5 浏览器侧,小程序侧受域名白名单约束,两者不能互相替代。错误形状、超时和重试应在代理层统一,具体平台的配置项和第三方配额需以官方文档核验。
- 需要长期密钥的第三方调用应收敛到后端或云函数,客户端只持有自己的会话凭证。
- 跨域(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);
能确认与不能确认的边界#
本文能确认的是架构层面的取舍:密钥收敛到服务端、跨域与域名白名单是两套机制、超时与重试放在代理层统一。不能确认的是具体平台当前的配置项名称、审核规则、限额数值以及任何第三方的可用性与价格——这些需查阅对应官方文档,本文未联网核验,也无法替读者判断某个接口是否仍然可用。
落地时的最小检查顺序:先确定发起位置,再确定客户端凭据形式,然后配置域名与跨域,最后补超时、错误形状与日志。顺序反了,通常会在联调阶段反复回到第一步。