微信小程序 / H5 调用第三方 API 的正确姿势:密钥留在服务端
微信小程序与 H5 的代码都运行在用户设备上,任何下发到前端的第三方 API 密钥都应视为已经公开。可行的做法是前端只调用自己的服务端接口,由服务端持有密钥、附加鉴权并调用第三方;H5 还需考虑浏览器同源策略,小程序则需按微信官方规则配置服务器域名。具体配置项与最新限制本次材料未提供,待核实。
微信小程序和 H5 有一个共同点:代码最终运行在用户的设备上。因此“正确姿势”的第一条不是选哪个请求库,而是判断密钥落在哪一侧。凡是打包进前端包、写进页面脚本、存进 localStorage 或小程序 storage 的第三方 API 密钥,都应视为已经公开。可落地的做法是:前端只调用你自己的服务端接口,第三方密钥由服务端持有并附加。
一、先判断密钥是否下发到了客户端#
- H5:浏览器可以查看源码与 Network 面板,前端出现的 key 能被直接复制。
- 小程序:代码包可被解包,本地存储可被读取;变量混淆只是提高阅读成本,不构成保护。
- 服务端:密钥只出现在部署环境变量或密钥管理服务中,可以轮换、可以撤销、可以按调用方限流。
所以判断标准不是“前端做了没有加密”,而是“密钥是否曾经下发到客户端”。把明文换成另一段可被还原的字符串,并不改变它已经离开服务端这一事实。
二、三条调用路径的差别#
| 路径 | 密钥位置 | 浏览器同源策略 | 微信侧约束 | 适用场景 |
|---|---|---|---|---|
| 前端直连第三方 | 客户端 | 受 CORS 约束 | 需符合服务器域名要求 | 公开、无需密钥的接口 |
| 前端 → 自建代理 → 第三方 | 服务端 | 不涉及 | 只约束到代理域名 | 需要密钥或计费的接口 |
| 前端 → 云函数/边缘函数 → 第三方 | 函数运行环境 | 不涉及 | 按平台规则配置 | 无自建服务时的过渡方案 |
H5 直连会受浏览器同源策略约束,第三方需要返回允许来源的 CORS 响应头,否则请求在浏览器侧就会被拦下。小程序不走浏览器的 CORS 机制,但需要按微信官方要求配置服务器域名并使用 HTTPS。具体配置入口、域名类型与数量限制属于会变化的平台规则,本次材料未提供,待核实。
三、代理层需要定下来的几件事#
- 只暴露业务语义路径,例如
/api/weather,不要做成“传什么 URL 就转发什么”的通用通道,否则代理会变成开放转发器。 - 鉴权放在代理层:用户登录态校验在这里做,第三方密钥只用于出站,两者不要混用。
- 定好超时与重试预算:重试只对幂等请求开启,并设置次数上限。
- 统一错误包络:不把第三方原始错误体、请求头和密钥回传给前端。
- 日志脱敏:记录请求 ID 与状态码,不记录完整请求体与鉴权头。
示意代码(未执行)
下面的片段用于说明“密钥只出现在服务端”这一结构,属于伪代码,混合了 Express 风格的路由与响应方法,未实际运行,也不能直接用于生产。运行环境假设为支持全局 fetch 与 AbortController 的 Node.js 版本。
// 未执行的示意代码:前端只请求 /api/weather,由服务端附加密钥
app.get('/api/weather', async (req, res) => {
// 1. 先校验调用方身份,未通过直接返回 401
// 2. 只接受白名单内的参数,避免把任意输入拼进上游请求
const upstream = new URL('https://api.example.com/v1/weather'); // example.com 为占位域名
upstream.searchParams.set('city', String(req.query.city ?? ''));
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 5000); // 超时预算
try {
const r = await fetch(upstream, {
headers: { Authorization: `Bearer ${process.env.THIRD_PARTY_KEY}` }, // 密钥来自环境变量
signal: controller.signal
});
if (!r.ok) {
return res.status(502).json({ error: 'upstream_failed' }); // 不回传上游原始错误
}
return res.status(200).json(await r.json());
} catch (e) {
return res.status(504).json({ error: 'upstream_timeout' });
} finally {
clearTimeout(timer);
}
});
THIRD_PARTY_KEY 是占位名称,示例中的域名与路径均为演示用途,不构成对任何真实接口的调用说明。
四、上线前的核对项#
- 前端包、源码、构建产物中是否还残留密钥字符串;
- 密钥能否在不重新发版的情况下轮换,撤销流程是否演练过;
- 代理层是否限制可转发的目标,是否对单用户设了频率上限;
- 小程序后台配置的服务器域名是否与实际请求域名一致;
- 超时、重试、错误包络是否已经写进接口约定;
- 日志与埋点中是否排除了鉴权头与敏感参数。
五、本文没有覆盖的部分#
不同第三方 API 的鉴权方式差异很大,例如签名计算、OAuth 授权码流程、用 AppID 与 AppSecret 换取临时凭证等,这些都必须以对应服务的官方文档为准。本次没有可用的正文素材,因此不给出具体的参数名、有效期与版本结论,相关细节待核实。同样,微信小程序服务器域名的最新规则、H5 预检请求的具体行为,也应以官方文档和实际环境验证为准,本文只讨论“密钥不下发到前端”这一条稳定边界。