技术文章

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

小程序与 H5 调第三方 API:把请求差异收进一层适配

一句话回答

小程序与 H5 调第三方 API 的差异集中在请求发送层:H5 由浏览器发起、受同源策略与 CORS 约束,小程序由宿主发起、受平台配置约束。做法是定义一层 Transport 接口,两端各写一个实现,把认证、错误判定、观测放在接口之上;并注意两端都不会因 4xx/5xx 抛异常,失败必须显式判断 status。

差异几乎都在“请求怎么发出去”这一层:H5 的请求由浏览器发出,跨域是否放行由同源策略和响应头决定;小程序的请求由宿主运行时发出,约束来自平台侧配置。业务代码不该感知这些差别。可行做法是抽一层 Transport 接口,两端各写一个实现,认证、错误判定、观测都放在接口之上。

本文未联网核验,也不含实测;涉及平台具体规则的条目一律标注“待核实”,请以各平台当前文档为准。

一、先确定约束来自哪一侧#

H5 侧,请求由浏览器发出。跨域请求是否放行,取决于服务端响应头与浏览器对同源策略的执行;预检用的 OPTIONS 请求也由浏览器发起,业务代码绕不过去。这是通用 Web 平台行为,细节以 Fetch 标准与目标浏览器实现为准。

H5 侧的另一个易漏点:预检和真实请求是两次独立往返,服务端对 OPTIONS 的响应如果缺少对应许可头,真实请求根本不会发出。

小程序侧,网络能力由宿主提供,不是浏览器发起的 fetch 或 XHR,因此浏览器那套 CORS 机制不直接适用(推断,具体限制以微信开放文档为准)。它换成的是配置型约束:哪些域名可以请求、协议与路径有什么要求。这一类规则会随平台版本变化,待核实。

所以判断“我当前处于哪个容器”的代码,最好只出现在初始化阶段,而不是散落在每个调用点。

二、把一次调用拆成四层#

  • 传输层:真正把字节送出去的代码(fetch、XHR、wx.request)。跨端只替换这一层。
  • 认证层:凭证的取用与刷新。两端对 Cookie 的处理并不一致(待核实),把会话状态寄存在隐式 Cookie 上会放大这种不一致;显式放进 header 更可控。
  • 语义层:把 HTTP 状态码和业务码翻译成领域结果。不要用“有没有抛异常”判断成功。
  • 观测层:trace id、耗时、错误分类。两端字段格式统一,日志才能合并查看。

三、最小接口与两个实现#

下面的代码为未执行的示例,仅示意分层结构,不是可直接运行的完整实现。

// 未执行示例
type Req = {
  method: 'GET' | 'POST';
  url: string;
  headers?: Record<string, string>;
  body?: unknown;
  timeoutMs?: number;
};
type Res<T> = { status: number; data: T };
type Transport = <T>(req: Req) => Promise<Res<T>>;
// 未执行示例
const fetchTransport: Transport = async (req) => {
  const ctrl = new AbortController();
  const timer = setTimeout(() => ctrl.abort(), req.timeoutMs ?? 10000);
  try {
    const r = await fetch(req.url, {
      method: req.method,
      headers: req.headers,
      body: req.body == null ? undefined : JSON.stringify(req.body),
      signal: ctrl.signal,
    });
    return { status: r.status, data: await r.json() };
  } finally {
    clearTimeout(timer);
  }
};
// 未执行示例;wx.request 的参数与回调语义请对照当前文档
const wxTransport: Transport = (req) =>
  new Promise((resolve, reject) => {
    wx.request({
      url: req.url,
      method: req.method,
      header: req.headers,
      data: req.body,
      timeout: req.timeoutMs,
      success: (r) => resolve({ status: r.statusCode, data: r.data }),
      fail: (e) => reject(e),
    });
  });

实现时的三个注意点

  • 两种传输一般都不会因为 4xx / 5xx 抛出异常(以各自文档为准),异常通常只代表网络层失败。因此判断成功必须显式读 status,不能靠 try/catch。
  • 超时不要依赖默认值。在 Transport 内设一个上限,业务层再按接口特性设更短的上限。
  • 取消能力的形态两端不同:H5 侧一般用 AbortController,小程序侧的对应能力待核实。接口里先留出 signal 位置,切换实现时业务代码不用改。

四、两端的边界条件对照#

维度H5小程序
请求由谁发出浏览器宿主运行时
跨域放行由谁决定响应头 + 浏览器同源策略平台侧配置(规则待核实)
凭证携带方式受请求的 credentials 选项影响需按平台文档确认(待核实)
超时默认值由浏览器与网络栈决定以平台文档为准(待核实)
并发上限由浏览器实现决定以平台文档为准(待核实)

五、上线前核对什么#

  1. 两端各跑通一个最小只读接口,先确认链路通,暂不验证业务逻辑。
  2. 再用一个必然失败的路径(错误的凭证或错误路径)确认失败结构在两端一致。
  3. 在小程序真机与移动浏览器各验证一次超时和弱网表现。
  4. 把平台侧配置(域名、白名单一类)写进发布清单。它不在代码库里,最容易在换域名时漏掉。

这些东西无法靠一次封装就一次性解决,但把它们收进同一个接口后,每处改动都只需改一处,边界也更容易核对。

作者:沐小悠

本文约 7 分钟读完 · 关键词:微信小程序调用API、H5跨域、请求适配层、Transport 抽象、第三方API接入

更多文章 GET 示例接口

「」标签下的其他文章