在软件开发过程中,对于各类 API 的调试工作至关重要。API调试是验证和测试应用程序接口的有效性和正确性的关键步骤。传统的API调试方法通常依赖于独立的工具或桌面应用程序,限制了调试过程的灵活性和效率。

为推动API调试向更便捷、高效的方向发展,越来越多的开发人员开始寻求在纯Web端完成各类API调试的解决方案。纯Web端的API调试具有许多优势,包括无需安装额外软件、跨平台支持、便于团队协作等。本文将以开源项目 AREX 为例为大家介绍如何在 Web 端实现对各类 API 的调试功能。

关于 AREX

AREX (http://arextest.com/)是一款开源的基于真实请求与数据的自动化回归测试平台,利用 Java Agent 技术与比对技术,通过流量录制回放能力实现快速有效的回归测试。同时提供了接口测试、接口比对测试等丰富的自动化测试功能。

难点一:跨域限制

要想在纯 Web 端实现各类 API 的调试工作,首先要解决的难题是处理浏览器的跨域限制。

什么是跨域

浏览器跨域问题是指在 Web 开发中,当使用 JavaScript 代码从一个域名的网页访问另一个域名的资源时会遇到的限制。浏览器实施了一种安全策略,称为同源策略(Same-Origin Policy), 用于保护用户信息的安全。同源策略要求网页中的 JavaScript 只能访问与其来源(协议、域名和端口号)相同的资源,而对于不同域名的资源访问会受到限制。

由于浏览器存在跨域限制,我们不能在浏览器端随心所欲地发送 HTTP 请求,这是浏览器的安全策略决定的。

解决方案

经调研,突破此限制的方法有两种:分别是 **Chrome** 插件代理服务端代理,以下是两种方法的比较。

         Chrome 插件代理                  服务端代理            
访问本地可以                                    不可以                    
速度    无请求时间损耗                          整个流程速度受代理接口影响
实际请求已知 Origin 源会被修改为 Chrome 插件的源完全一样                  

权衡下来 AREX 选择了 Chrome 插件代理的方法,其原理是利用了 Chrome 插件中 background 可以发送跨域请求的能力,我们将浏览器端拦截到的请求通过 window.postmassage 与 Chrome 插件的 background 进行通信(其中通信还需要 Chrome 插件的 content-script作为数据桥梁)。

具体实现如下:

  • 在页面脚本中
  1. 生成一个随机的字符串,并将其转换为字符串形式,存储在 \`tid\` 变量中。
  2. 使用 window.postMessage() 方法发送一条消息到其他扩展程序,消息包括一个类型为 AREX_EXTENSION_REQUEST 的标识、tid、以及 params 参数。
  3. 添加一个 message 事件监听器 receiveMessage,用于接收其他扩展程序发送的消息。

4. 在 receiveMessage 函数中,检查接收到的消息是否为类型为 AREX_EXTENSION_RES,并且 tid 与之前发送的消息的 tid 相匹配。如果匹配成功,则移除事件监听器。

  • 在内容脚本中
  1. 添加一个 message 事件监听器,用于接收来自页面脚本或其他扩展程序发送的消息。
  2. 在事件监听器中,检查接收到的消息是否为类型为 AREX_EXTENSION_REQUEST,如果是,则使用 chrome.runtime.sendMessage() 方法将消息发送给后台脚本。
  3. 在接收到来自后台脚本的响应后,使用 window.postMessage() 方法将响应消息发送回页面脚本或其他扩展程序。
  • 在后台脚本中
  1. 使用 chrome.runtime.onMessage.addListener() 方法添加一个监听器,用于接收来自内容脚本或其他扩展程序发送的消息。
  2. 在监听器中可以处理接收到的消息,并根据需要作出响应。
// arex
const tid = String(Math.random());
window.postMessage(
  {
    type: '__AREX_EXTENSION_REQUEST__',
    tid: tid,
    payload: params,
  },
  '*',
);
window.addEventListener('message', receiveMessage);
function receiveMessage(ev: any) {
  if (ev.data.type === '__AREX_EXTENSION_RES__' && ev.data.tid == tid) {
    window.removeEventListener('message', receiveMessage, false);
  }
}
// content-script.js
window.addEventListener("message", (ev) => {
  if (ev.data.type === "__AREX_EXTENSION_REQUEST__"){
    chrome.runtime.sendMessage(ev.data, res => {
      //   与background通信
      window.postMessage(
        {
          type: "__AREX_EXTENSION_RES__",
          res,
          tid:ev.data.tid
        },
        "*"
      )
    })
  }
})
// background.js
chrome.runtime.onMessage.addListener((req, sender, sendResponse) => {

})

难点二:API 调试

上述已经解决了跨域问题,接下来就是如何实现 API 调试的功能。

解决方案

Postman 是业内成熟的 API 调试工具,我们站在了 Postman 这位巨人的肩膀上,在 AREX 中引入了 Postman 的 JavaScript 沙盒,使用它的沙盒运行前置脚本、后置脚本以及断言来调试 API。

以下是 AREX 请求的流程图:

当点击发送请求的时候,会将表单中的数据汇聚到一起,数据结构为:

export interface Request {
  id: string;
  name: string;
  method: string;
  endpoint: string;
  params: {key:string,value:string}[];
  headers: {key:string,value:string}[];
  preRequestScript: string;
  testScript: string;
  body: {contentType:string,body:string};
}

这是 AREX 的数据结构,我们会将其转换成 Postman 的数据结构。之后调用 PostmanRuntime.Runner() 方法,将转换好了的 Postman 数据结构和当前所选的环境变量传入,Runner 会执行 preRequestScripttestScript 脚本。preRequestScript 发生在请求之前,可以在其中穿插请求以及对请求参数、环境变量进行操作,testScript 发生在请求之后,可以对 response 返回数据进行断言操作,并且脚本中也可以通过 console.log 输出数据,在控制台进行调试。

var runner = new runtime.Runner(); // runtime = require('postman-runtime');

// 一个标准的postman集合对象
var collection = new sdk.Collection();

runner.run(collection, {}, function (err, run) {
    run.start({
      assertion:function (){}, //断言
      prerequest:function (){}, // 预请求勾子
      test:function (){}, //测试勾子
      response:function (){} //返回勾子
    });
});

在 Postman 沙盒中也存在跨域问题,由于 Postman 沙盒的集成度非常高,为了确保与 PostmanRuntime 的同步以及方便性,我们采用了 Ajax 拦截技术。通过在浏览器端拦截 Ajax 请求,我们可以对请求进行修改、添加自定义逻辑或者进行其他处理操作。这样可以实现对请求和响应的全局控制和定制化。

当 Postman 沙盒发送请求时,会携带一个名为 "postman-token" 的请求头。我们拦截到这个 Ajax 请求后,会将请求参数进行拼装,并通过 window.postMessage 发送给浏览器插件。浏览器插件再次构建 fetch 请求,将数据返回给 Postman 沙盒,使其输出最终结果,包括响应(response)、测试结果(testResult)和控制台日志(console.log)。需要注意的是,responseType 必须指定为 arraybuffer。

具体流程如下:

  1. 使用 xspy.onRequest() 方法注册一个请求处理程序。这个处理程序接受两个参数:request 和 sendResponse。request 参数包含请求的相关信息,例如方法、URL、头部、请求体等。sendResponse 是一个回调函数,用于发送响应给请求方。

2. 在处理程序中,通过检查请求的头部中是否存在 postman-token 来判断请求是否来自 Postman。

  • 如果存在该头部,表示请求是通过 Postman 发送的。则使用 AgentAxios 发起一个新的请求,使用原始请求的方法、URL、头部和请求体。AgentAxios 返回一个 agentData 对象,其中包含了响应的状态码、头部和数据等信息。创建一个名为 dummyResponse 的响应对象,包含了与原始请求相关的信息。dummyResponse 的 status 字段为 agentData 的状态码,headers 字段为将 agentData 的头部数组转换为对象格式的结果,ajaxType 字段为字符串 xhr,responseType 字段为字符串 arraybuffer,response 字段为将 agentData 的数据转换为 JSON 字符串并用 Buffer 包装的结果。最后,使用 sendResponse(dummyResponse) 将响应发送给请求方。
  • 如果请求不是来自 Postman,则直接调用 sendResponse(),表示不返回任何响应。
xspy.onRequest(async (request: any, sendResponse: any) => {
  // 判断是否是pm发的
  if (request.headers['postman-token']) {
    const agentData: any = await AgentAxios({
      method: request.method,
      url: request.url,
      headers: request.headers,
      data: request.body,
    });
    const dummyResponse = {
      status: agentData.status,
      headers: agentData.headers.reduce((p: any, c: { key: any; value: any }) => {
        return {
          ...p,
          [c.key]: c.value,
        };
      }, {}),
      ajaxType: 'xhr',
      responseType: 'arraybuffer',
      response: new Buffer(JSON.stringify(agentData.data)),
    };
    sendResponse(dummyResponse);
  } else {
    sendResponse();
  }
});

难点三:二进制对象序列化传递

还有一点值得一提,对于 x-www-form-urlencodedRaw 类型的请求,由于它们都是普通的 JSON 对象,处理起来比较容易。但是对于 form-databinary 类型的请求,需要支持传输二进制文件负载。然而,Chrome 插件的 postMessage 通信方式不支持直接传递二进制对象,导致无法直接处理这两种类型的请求。

解决方案

为了解决这个问题,AREX 采用了 base64 编码技术。在用户选择文件时,AREX 会将二进制文件转换为 base64 字符串,然后进行传输。在 Chrome 插件端,AREX 会将 base64 数据进行解码,并用于构建实际的 fetch 请求。这样可以绕过直接传递二进制对象的限制。

这个流程图描述了将 FormData 中的二进制文件转换为 Base64 字符串,并通过 Chrome 插件代理将其转换回文件并进行进一步处理的过程。

  1. form-data binary(A):表示一个包含二进制文件的 FormData 表单数据。
  2. FileReader(B):使用 FileReader 对象来读取二进制文件。
  3. readAsDataURL base64 string:FileReader 使用 readAsDataURL 方法将二进制文件读取为 Base64 字符串。
  4. Chrome 插件代理(C):Base64 字符串经过读取操作后,传递给 Chrome 插件代理进行进一步处理。
  5. base64 string:表示经过 FileReader 读取二进制文件后得到的 Base64 字符串。
  6. Uint8Array(D):在 Chrome 插件代理中,将 Base64 字符串转换为 Uint8Array。
  7. File(E):使用 Uint8Array 的数据创建一个新的 File 对象。
  8. fetch(F):将新创建的 File 对象通过 fetch 方法或其他方式进行进一步处理,例如上传到服务器或进行其他操作。

代码分析

以下是代码层面的分析:

toBase64 函数接受一个 File 对象作为参数,并返回一个 Promise 对象,该 Promise 对象将解析为表示文件的 Base64 字符串。

在函数内部,创建了一个 FileReader 对象。 通过调用 reader.readAsDataURL(file) 将文件读取为 Data URL。 当读取操作完成时,通过 reader.onload 事件处理程序将读取结果解析为字符串,并使用 resolve 将其传递给 Promise。 如果发生错误,将使用 reject 将错误传递给 Promise。 base64ToFile 函数接受两个参数:dataurl(Base64 字符串)和 filename(文件名),并返回一个 File 对象。

首先,将 dataurl 使用逗号分割成数组 arr,如果分割结果为空,则将其设为包含一个空字符串的数组。 通过正则表达式匹配 arr[0] 中的内容,提取出 MIME 类型,即数据的类型。 使用 atob 将 Base64 字符串解码为二进制字符串 bstr。 创建一个长度为 n 的 Uint8Array 数组 u8arr。 使用循环遍历 bstr,将每个字符的 Unicode 编码放入 u8arr 中。 最后,使用 File 构造函数创建并返回一个新的 File 对象,其中包含了从 u8arr 中读取的文件数据、文件名和 MIME 类型。 导出 base64ToFile 函数,以便在其他地方使用。

// 文件转Base64
const toBase64 = (file: File): Promise<string> =>
  new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.readAsDataURL(file);
    reader.onload = () => resolve(reader.result as string);
    reader.onerror = reject;
  });
// base64转文件
function base64ToFile(dataurl: string, filename: string) {
  const arr = dataurl.split(',') || [''],
    mime = arr[0].match(/:(.*?);/)?.[1],
    bstr = atob(arr[1]);
  let n = bstr.length;
  const u8arr = new Uint8Array(n);
  while (n--) {
    u8arr[n] = bstr.charCodeAt(n);
  }
  return new File([u8arr], filename, { type: mime });
}

export default base64ToFile;
  • AREX 文档:arextest.com/zh-Hans/doc…
  • AREX 官网:arextest.com/
  • AREX GitHub:github.com/arextest
  • AREX 官方 QQ 交流群:656108079

AREX_中文社区
1 声望3 粉丝

AREX 是一个基于真实请求与数据的自动化回归测试平台。通过复制线上真实流量到测试环境进行自动化回归测试,解决回归测试的难题。