技术文章

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

微信小程序与 H5 调用第三方 API:两端差异、服务端出口与错误分类

一句话回答

小程序与 H5 调用第三方 API 的约束不同:小程序受宿主网络能力与域名白名单约束,H5 受浏览器同源策略与 CORS 约束。共同做法是把第三方调用收进自建服务端出口,两端只保留薄适配层,并统一超时、错误分类与响应校验。域名数量、超时上限、并发限制等平台具体数值本次未核验,应以官方文档为准。

小程序和 H5 调用第三方 API,卡点通常不在“怎么发请求”,而在两端所处的网络环境不一样:小程序里的请求由宿主发起,受域名白名单和宿主网络能力约束;H5 里的请求由浏览器发起,受同源策略与 CORS(跨域资源共享)约束。所以正确的姿势不是把一份代码复制两遍,而是让两端都只调用自家服务端的一个薄接口,由服务端去对接第三方 API。

需要先说明边界:本次写作没有可引用的正文材料,也没有实际运行任何示例。文中涉及的平台具体数值(合法域名数量、超时上限、并发限制、是否要求备案等)待核实,请以对应平台官方文档为准;下面的代码均为未执行的示例,只示意结构,不作为可运行保证。

为什么两端不能共用同一套调用代码#

  • 请求发起方不同。小程序端的请求经过宿主转发,没有浏览器那种同源策略,但需要在后台配置可访问的域名;H5 端由浏览器直接发出,跨域时浏览器会先发预检请求(OPTIONS),服务端不返回相应响应头就会被拦下。
  • 凭证处理不同。H5 依赖 Cookie 时,需要前端设置 credentials、服务端返回对应的 CORS 响应头,且此时允许的来源不能写成通配符;小程序端不按浏览器的 Cookie 模型工作,鉴权更适合显式的请求头令牌。
  • 可篡改性相同。小程序包可以被解包,H5 的 JS 对用户完全可见。两端都不能放第三方 API 密钥——这一点与站内此前关于密钥泄露的文章是同一个结论。

把第三方调用收进服务端出口#

推荐的结构是:小程序 / H5 → 自建接口(BFF,为前端聚合数据的中间层)→ 第三方 API。这样做换来四件事:

  1. 密钥只存在服务端,前端拿不到。
  2. 小程序后台只需配置自家域名,第三方域名变更不影响前端发版。
  3. 超时、重试、缓存、限流在一个地方统一,不必两端各写一遍。
  4. 第三方返回的字段变化,在服务端做一次映射,前端契约保持稳定。

代价是多一跳网络与服务端运维成本。如果第三方接口本身允许公开调用且无密钥,直连也可以,但仍建议保留服务端出口用于限流和缓存。

小程序侧:封装一层,而不是散落调用#

宿主提供的请求方法本身是回调式 API,建议包成 Promise,并把“网络失败”和“HTTP 非 2xx”分开,后续错误处理才有依据。

// 未执行示例:仅示意封装结构,BASE_URL 为占位
const BASE_URL = 'https://api.example.com';

function request(path, options = {}) {
  return new Promise((resolve, reject) => {
    wx.request({
      url: BASE_URL + path,
      method: options.method || 'GET',
      data: options.data,
      timeout: 10000, // 占位值,实际上限以平台文档为准
      header: { 'content-type': 'application/json' },
      success(res) {
        if (res.statusCode >= 200 && res.statusCode < 300) {
          resolve(res.data);
        } else {
          reject(Object.assign(new Error('HTTP ' + res.statusCode), {
            kind: 'http',
            status: res.statusCode
          }));
        }
      },
      fail(err) {
        reject(Object.assign(new Error(err.errMsg || 'network error'), {
          kind: 'network'
        }));
      }
    });
  });
}

H5 侧:超时要能真正中断请求#

浏览器端常见错误是只写了 Promise.race 超时,请求本身还在跑。用 AbortController 才能真正取消。

// 未执行示例:仅示意结构,API_BASE 为占位
const API_BASE = 'https://api.example.com';

async function request(path, { method = 'GET', body, timeout = 10000 } = {}) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), timeout);
  try {
    const res = await fetch(API_BASE + path, {
      method,
      headers: { 'content-type': 'application/json' },
      body: body ? JSON.stringify(body) : undefined,
      signal: controller.signal,
      credentials: 'include' // 仅当确实需要携带 Cookie 时开启
    });
    if (!res.ok) {
      throw Object.assign(new Error('HTTP ' + res.status), {
        kind: 'http',
        status: res.status
      });
    }
    return await res.json();
  } finally {
    clearTimeout(timer);
  }
}

上面开启 credentials: 'include' 后,服务端必须返回允许凭证的响应头,且允许来源不能是通配符,否则浏览器会直接拒绝——这是 CORS 的通用规则,具体配法依你的服务端框架而定。

错误分类与响应校验#

两端封装后,错误应至少分成四类,处理策略不同:

类别典型来源是否可重试
network断网、DNS 失败、请求被中断可,需退避
timeout超过自设超时视接口幂等性而定
http4xx / 5xx4xx 一般不重试;5xx 有限重试
businessHTTP 200 但业务码表示失败不可自动重试

“HTTP 200 但业务失败”是第三方接口的常见形态,必须显式判断业务码,不能只看状态码。此外,JSON 解析成功也不代表结构正确,建议对关键字段做一次存在性与类型校验,失败时按 business 或单独一类处理,而不是让 undefined 漏到页面渲染层。

重试要有限度:只对幂等请求(查询类)自动重试,写操作交由用户确认或由服务端用幂等键保证唯一性。

本次无法确认的部分#

各平台对可配置域名数量、单次请求超时上限、并发请求数、上传体积的具体限制,本次没有材料支撑,不予列出,请查阅对应官方文档。同样,文中的 timeout: 10000 只是示例占位值,不代表任何平台的默认值或上限制。

作者:沐小悠

本文约 9 分钟读完 · 关键词:微信小程序调用第三方 API、H5 跨域 CORS、服务端代理 BFF、请求封装、超时与错误分类

更多文章 GET 示例接口

「」标签下的其他文章