微信小程序 / H5 调用第三方 API 的正确姿势:密钥放在哪里、跨域怎么处理
一句话回答
建议小程序与 H5 都通过自建 BFF 代理第三方 API,避免密钥进入客户端,同时把跨域、限流和错误处理集中到服务端;文中给出未执行的最小代理示意,并说明超时、重试与幂等的边界。
核心要点 TL;DR
- 前端直连第三方 API 会让密钥暴露,还要同时处理跨域和平台域名限制,成本高于加一层后端。
- 推荐链路是客户端 → 自建 BFF → 第三方,BFF 负责注入密钥、限制出网域名、统一归一化错误。
- 重试前先区分错误类型,POST 重试需要幂等键。
简短回答:把第三方 API 的调用放在你自己的服务端,小程序和 H5 只调用自己的后端。前端直连会把密钥带进客户端,还要在客户端同时解决跨域与平台域名限制,通常不划算。
为什么不建议前端直连#
小程序代码包可以被解包查看,H5 的请求在浏览器开发者工具里完全可见。因此,写在前端的密钥应当按“已泄露”处理;这是从“客户端环境不可信”推导出的判断,不是某次测试结论。另外,H5 受同源策略约束;第三方接口若没有返回允许跨域的响应头,浏览器会直接拦截请求,改前端代码解决不了。
推荐链路:客户端 → 自建 BFF → 第三方#
BFF(Backend for Frontend,面向前端的后端)是一层只服务自己客户端的轻量服务。它承担四件事:注入密钥、限制可访问的上游域名、限流与配额控制、把第三方返回的错误格式统一转换为你自己的错误码。
小程序端一般还需要配置服务器域名白名单并启用 HTTPS;具体规则与当前限制以微信官方文档为准,本次未核验。H5 端不需要平台域名配置,但后端要明确允许哪些来源跨域,不要用通配符放开全部站点。
示例:一个最小代理(未执行)#
下面的代码只用于说明结构,未在本机运行;域名为占位,密钥从环境变量读取。
const express = require('express');
const app = express();
app.get('/api/quote', async (req, res) => {
const r = await fetch('https://api.example.com/v1/quote', {
headers: { Authorization: `Bearer ${process.env.UPSTREAM_KEY}` },
signal: AbortSignal.timeout(3000)
});
if (!r.ok) return res.status(502).json({ code: 'UPSTREAM_ERROR' });
res.json(await r.json());
});
这里有两个要点:密钥只出现在服务端环境变量里,不回传给客户端;超时设在上游请求上,而不是只依赖客户端主动取消。
超时、重试与幂等#
- 先分类再重试:网络超时、429、5xx 可以考虑重试;参数错误、鉴权失败这类 4xx 重试通常无意义。
- POST 重试要带幂等键,否则一次用户操作可能被执行两次。
- 服务端超时应当短于客户端等待上限,否则客户端先断开,日志里只剩一条“未知失败”。
上线前核对#
- 代码仓库与运行日志里搜不到密钥;错误响应不回传上游原始报文。
- 可访问的上游域名以列举方式配置,不使用通配。
- 缓存键是否含用户维度、缓存时长是否可接受,需按具体业务确认。
- 第三方的配额、计费方式与限流阈值:待核实,按实际合同与官方文档填写。
本文只讨论结构性问题。各平台当前对域名白名单、跨域与配额的具体规定存在差异,需以对应官方文档为准;这些细节本次未做核验,也不据此推断最新情况。