技术文章

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

微信小程序与 H5 调用第三方 API:先收住平台差异,再谈请求写法

一句话回答

小程序与 H5 调用同一个第三方 API,差异主要不在业务逻辑,而在运行环境、域名与跨域约束、错误分类方式。可行做法是把平台差异压到一个可替换的接入层:页面只消费统一结果;传输层按错误类型区分可重试与不可重试;只对幂等请求重试;密钥不进入客户端。平台具体的域名白名单与并发限制以官方文档为准,本文未做核验。

“正确姿势”不是先决定在小程序里写 wx.request、还是在 H5 里写 fetch,而是先把两者的差异收进一层可替换的接入代码。页面组件不该知道密钥从哪来、域名白名单怎么配、超时算多少毫秒;它只应该拿到一个结果:成功的数据,或一个能被分类处理的失败。

这个结论有前提:第三方 API 的端点、鉴权方式和配额规则需要你自己核实。本文不涉及任何具体厂商的实测调用,平台规则也在变化,凡是涉及“必须配置什么才能发请求”的部分,都应以官方文档为准(待核实)。

两种运行环境,差异在三个地方#

运行环境。小程序没有 DOM,也没有浏览器的 XMLHttpRequest,网络请求走平台提供的 API;H5 跑在浏览器里,可以直接用 fetch。这决定了两端不能共用同一份“发请求”的代码,但可以共用同一份“处理结果”的代码。

域名与跨域约束。H5 读取跨域响应时会被同源策略拦截,通常需要服务端返回 CORS 响应头,配置方式随服务端框架而异。小程序一般要求在小程序后台配置请求域名,且对协议有要求;具体清单和审核规则请核对官方文档(待核实)。这意味着同一份接口地址,可能在浏览器里通、在小程序里被拦,或者反过来。

失败形态。两端都会遇到断网、超时、限流和 5xx,但抛出的错误对象结构不同。如果不在接入层归一,错误处理代码会在每个页面里重复一遍。

接入层:把差异压到一个函数后面#

下面是一个结构示意,不是可运行实现,也没有实际执行:域名、超时、错误码字段均为占位。

// 未执行的示例:仅演示分层,https://api.example.com 为占位域名
const BASE = 'https://api.example.com'; // 占位

function createClient(transport) {
  // transport: 平台适配器,签名统一为 ({url, method, body, timeout}) => {status, data}
  return async function request({ path, method = 'GET', body, timeout = 8000 }) {
    try {
      const res = await transport({ url: BASE + path, method, body, timeout });
      if (res.status >= 200 && res.status < 300) return { ok: true, data: res.data };
      if (res.status === 429 || res.status >= 500) {
        return { ok: false, kind: 'retryable', status: res.status };
      }
      return { ok: false, kind: 'business', status: res.status, code: res.data && res.data.code };
    } catch (e) {
      return { ok: false, kind: 'network', error: String(e && e.message) };
    }
  };
}

两端各写一个 transport:小程序侧用平台的请求 API,H5 侧用 fetch。差异被限制在这一个函数里,换平台时上层不用改。

错误分层:哪些该重试,哪些不该#

层次典型表现建议动作
传输层超时、断网、5xx可重试,限制次数并退避
限流429可重试,但先看响应头给出的等待时间
业务层4xx + 错误码一般不重试,转成用户可理解的提示
契约层字段缺失、类型变化记日志并降级,不要静默当成功

第四行最容易被忽略。第三方 API 返回 200 不代表数据可用;接入层应当校验关键字段是否存在,而不是把整个响应对象直接透传给页面。

重试的两个边界#

  • 只对幂等请求重试。GET 通常安全;POST 创建类请求重复发送可能产生多条记录。若要对这类请求重试,需要服务端支持幂等键,是否支持需查对应 API 文档(待核实)。
  • 重试要有上限和退避。无限重试在限流场景下会把问题放大;固定间隔重试在多端同时失败时容易形成同步冲击。

密钥与配额#

具备写权限或计费属性的密钥不应出现在小程序包体或前端脚本里:这两类产物都能被提取。若确实要直连,应当假设该密钥是公开的,并据此配置来源限制与配额;更稳妥的做法是把密钥放在服务端,客户端只调自己的接口。这一点在密钥轮换、最小权限等实践里已经反复出现过,本文不展开。

调试顺序#

  1. 先用命令行或服务端脚本单独验证端点本身,确认请求方法与参数正确。
  2. 再在浏览器或真机上抓取实际发出的报文,对比 URL、请求头和请求体。
  3. 若浏览器通、小程序不通,优先查小程序后台的域名配置,而不是改业务代码。
  4. 若反过来,优先查 CORS 与预检请求(OPTIONS)是否被正确处理。
  5. 最后才看业务错误码。

把这五步写成检查清单,比在多个页面里逐个加 console.log 更省时间。至于超时默认值、并发上限这些具体参数,各平台与各 API 的约束不同,需要按你的实际环境和官方文档确定(待核实)。

作者:沐小悠

本文约 6 分钟读完 · 关键词:微信小程序调用API、H5跨域请求、第三方API接入、请求封装、错误分层

更多文章 GET 示例接口

「」标签下的其他文章