技术文章

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

微信小程序 / 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 重试要带幂等键,否则一次用户操作可能被执行两次。
  • 服务端超时应当短于客户端等待上限,否则客户端先断开,日志里只剩一条“未知失败”。

上线前核对#

  • 代码仓库与运行日志里搜不到密钥;错误响应不回传上游原始报文。
  • 可访问的上游域名以列举方式配置,不使用通配。
  • 缓存键是否含用户维度、缓存时长是否可接受,需按具体业务确认。
  • 第三方的配额、计费方式与限流阈值:待核实,按实际合同与官方文档填写。

本文只讨论结构性问题。各平台当前对域名白名单、跨域与配额的具体规定存在差异,需以对应官方文档为准;这些细节本次未做核验,也不据此推断最新情况。

作者:沐小悠

本文约 4 分钟读完 · 关键词:微信小程序调用第三方API、H5 跨域、BFF 代理、API 密钥管理、超时与重试

更多文章 GET 示例接口

「」标签下的其他文章