技术文章

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

第三方 API 不该由客户端直连:小程序与 H5 的统一出口设计

一句话回答

小程序与 H5 调用第三方 API 的正确做法,是把调用链拆成客户端、自家服务端出口、上游三段:密钥与签名只留在服务端,平台差异只影响客户端这一小段,服务端对外提供统一的外层结构与错误码映射。本次没有可核验的素材,平台级配置细节与端点行为均需以官方文档为准。

先说结论:这件事的正确做法,是在客户端和第三方 API 之间加一层自家服务端出口,端上只跟自家后端说话;它并不是写一个“能发请求的函数”。在小程序和 H5 里,真正需要区别对待的只有最靠近用户的那一小段,密钥、签名、重试和错误码映射都应该落在服务端。本文讨论的是结构边界,具体的平台配置项与上游接口行为,本次材料没有覆盖,需以官方文档核实。

为什么先设统一出口#

判断依据是部署常识:H5 的脚本对用户可见,小程序包也可被解包查看,任何写进客户端的密钥都应视为已经泄露。一旦泄露,轮换成本、配额被消耗的损失都由你自己承担,且难以定位来源。

统一出口还带来一个维护上的好处:域名、超时、重试策略、错误码映射只在服务端一处维护。如果让每个页面各自直连上游,上游改一次字段,就要改很多地方。

平台差异只影响客户端层#

  • H5:请求由浏览器发出,跨域能否放行取决于目标服务端返回的 CORS 响应头。第三方 API 一般不会为你的页面域名放行,这一点在动手写代码前就应确认。
  • 小程序:请求能力、可请求域名的配置方式、是否支持自定义请求头、上传下载接口的差异,都由平台规则约束。本次材料未提供文档,这些细节待核实,不要凭记忆写死。

由此得到一个可操作的推论:不要为了兼容第三方而在客户端堆一层“平台适配”。把差异收在服务端出口的一侧,客户端只保留一种调用方式。

服务端出口的最小契约#

  1. 输入:只接收业务参数,不接收密钥,也不接收上游地址。
  2. 输出:统一外层,例如 { code, message, data };上游错误码映射成自家码,不要把上游原始错误体透传给客户端,它可能包含内部信息。
  3. 超时与重试:为上游设置明确超时;仅在幂等请求上重试,非幂等写操作要带幂等键。
  4. 日志:记录 requestId、耗时、上游状态码;不记录密钥与完整个人数据。

客户端只做三件事#

  • 携带自家会话凭证,而不是上游密钥;
  • 校验外层结构,缺失字段按失败处理;
  • 区分可重试与不可重试:网络类失败可提示重试,参数类失败重试没有意义。

一个结构示例(未执行)#

下面的代码未实际运行,仅示意服务端出口的形状,地址与密钥均为占位。运行环境假设为 Node.js 18+ 并使用原生 fetch,该假设本身需自行核实。

// 未执行示例:占位地址与占位密钥,不含真实端点
export async function callUpstream(params) {
  const url = "https://api.example.com/v1/items"; // 占位
  const res = await fetch(url, {
    method: "POST",
    headers: {
      "content-type": "application/json",
      authorization: `Bearer ${process.env.UPSTREAM_KEY}` // YOUR_KEY 由环境变量注入
    },
    body: JSON.stringify(params),
    signal: AbortSignal.timeout(5000)
  });

  if (!res.ok) {
    // 这里应映射为自家错误码,而不是透传上游文案
    return { code: "UPSTREAM_ERROR", message: "上游调用失败", data: null };
  }
  return { code: "OK", message: "", data: await res.json() };
}

什么情况下可以考虑不经过服务端#

范围很窄:公开只读、不要求密钥、没有按账号配额的接口。即便如此,也要考虑速率限制与缓存,并且要确认平台是否允许该类域名——这一条待核实。

判断标准很简单:如果这个调用失败或密钥泄露会直接影响账号或费用,它就不该从端上发出。

上线前的检查项#

  • 在客户端产物里搜索密钥字段,确认搜不到;
  • 错误码映射表存在,且客户端对未知码有兜底;
  • 上游接口变更或不可用时,有可回滚的开关;
  • 平台侧域名、权限配置与官方文档核对过,而不是照抄旧文。

以上是结构层面的建议,不构成对任何具体平台配置或上游接口行为的结论;涉及版本、配额、可用性的信息,本次材料均未提供。

作者:沐小悠

本文约 5 分钟读完 · 关键词:微信小程序 调用第三方 API、H5 跨域、API 密钥安全、BFF 统一出口、错误码映射

更多文章 GET 示例接口

「」标签下的其他文章