插件 jQuery.mockjax 中文API文档

🌙
手机阅读
本文目录结构

插件 jQuery.mockjax 中文API文档

源码 & 下载

适用场景

插件特点

jQuery Mockjax插件提供了一个简单且极其灵活的界面,用于模拟或模拟ajax请求和响应

基本文档

API方法

Mockjax只包含几种方法,每种方法都列在下面。您将在下面的部分中找到大量示例,但如果您正在寻找特定选项,请查看此列表:

  • Number $.mockjax(/* Object */ options)
    • 为匹配的请求设置mockjax处理程序
    • 返回该处理程序的索引,可用于清除各个处理程序
    • options:[Object]定义用于模拟请求的设置
      • url:[String | RegExp]指定应模拟数据的请求的url。如果它是一个字符串并包含任何星号(),则通过转换为正则表达式将它们视为通配符。任何将被替换.+。如果您遇到此快捷方式的问题,请切换到使用完整的正则表达式而不是字符串和星号组合
      • data:[Object| Function ] 除了URL,匹配参数
      • type:[String]指定要匹配的HTTP方法,通常是GET或POST。不区分大小写的,所以get和post也行
      • headers:[Object]密钥将被模拟为服务器为请求返回的附加标头(注意:这不用于匹配请求标头!)
      • status:[Number]一个整数,指定有效的服务器响应代码。这模拟了服务器响应代码
      • statusText:[String]指定有效的服务器响应代码说明。这模拟了服务器响应代码描述
      • responseTime:[Number]一个整数,指定模拟的网络和服务器延迟(以毫秒为单位)。默认是500。将此设置为0最小化模拟延迟
      • isTimeout:[Boolean]确定模拟是否会强制请求超时
      • contentType:[String]指定响应的内容类型
      • response:[Function]接受请求设置并允许在每次请求时动态设置响应设置(包括响应正文)的功能(请参阅下面的示例)
      • responseText:[String]为请求指定模拟文本或模拟对象文字
      • responseXML:[String]指定请求的模拟XML
      • proxy:[String]指定文件的路径,从该文件返回请求的内容
      • lastModified:[String]一个日期字符串,指定请求的模拟上次修改时间。这用于$.ajax确定自上次请求以来所请求的数据是否是新的
      • etag:[String]指定引用所请求数据的特定版本的唯一标识符。这用于$.ajax确定自上次请求以来所请求的数据是否是新的。(见HTTP_ETag)
      • onAfterSuccess:[Function]在调用success方法后调用的回调,这对于在调用完成后检查条件很有用
      • onAfterError:[Function]调用错误方法后将调用的回调,这对于在调用完成后检查条件很有用
      • onAfterComplete:[Function]类似于onAfterSuccess,但将在调用完整方法后执行
  • Object $.mockjax.handler(/* Number */ id)
    • 使用提供的函数返回处理程序的模拟请求设置id。这里要小心,你正在访问插件的内部工作,对这个对象的任何更改都可能很糟糕。
  • Array $.mockjax.handlers()
    • 返回模拟处理程序的数组。注意:清除处理程序时,不会修改此数组,清除的处理程序位置只需设置为null。因此,阵列长度仅在添加新模拟时才会更改。在这里要小心,你正在访问插件的内部工作,对数组的任何更改都可能非常糟糕。
  • void $.mockjax.clear([/* Number */ id])
    • 如果id提供了,则清除具有该ID的处理程序(即,匹配它的请求将不再这样做,处理程序被完全删除)
    • 如果未id提供,则清除所有处理程序,将Mockjax重置为其初始状态
  • Array<Object> $.mockjax.mockedAjaxCalls()
    • 返回所有模拟的ajax调用的数组,每个条目都是传递给$.mockjax()函数的请求设置对象
    • 如果 $.mockjaxSettings.retainAjaxCalls设置为false,则它将始终为空
  • Array<Object> $.mockjax.unfiredHandlers()
    • 返回尚未使用的所有模拟处理程序设置的数组。换句话说,如果处理程序已用于$.ajax()调用,则它不会出现在此数组中
  • Array<Object> $.mockjax.unmockedAjaxCalls()
    • 返回所有未模拟的Ajax调用的数组。该数组包含传入的设置对象$.ajax({...})
    • 如果$.mockjaxSettings.retainAjaxCalls设置为false,则它将始终为空
  • void $.mockjax.clearRetainedAjaxCalls()
    • 清空返回的阵列$.mockjax.mockedAjaxCalls$.mockjax.unmockedAjaxCalls

概述:你的第一个模拟

我们的第一个例子是针对一个幸运应用程序的简单REST服务,其中REST端点/restful/fortune返回以下JSON消息:

{
    "status": "success",
    "fortune" : "Are you a turtle?"
}

为了将财富投入到我们的页面中,我们将使用以下HTML和jQuery代码:

<!DOCTYPE html>
<html>
  <head>
    <title>Fortune App</title>
    <script src="http://code.jquery.com/jquery-1.11.1.min.js"></script>
  </head>
<body>
  <div id="fortune"></div>
</body>
</html>
$.getJSON("/restful/fortune", function(response) {
  if ( response.status == "success") {
    $("#fortune").html( "Your fortune is: " + response.fortune );
  } else {
    $("#fortune").html( "Things do not look good, no fortune was told" );
  }
});

此时如果我们要运行此代码,它将失败,因为尚未实现REST服务。这就是Mockjax插件的好处开始得到回报的地方。使用Mockjax的第一步是通过添加常规脚本标记来包含插件:

<head>
  ...
  <script src="vendor/jquery.mockjax.js"></script>
</head>

一旦包含了这些内容,您就可以开始拦截Ajax请求并模拟响应。所以让我们通过包含以下代码来模拟服务:

$.mockjax({
  url: "/restful/fortune",
  responseText: {
    status: "success",
    fortune: "Are you a mock turtle?"
  }
});

定义内联的JSON字符串需要一个JSON.stringify()方法可用。对于某些浏览器,您可能需要包含 json2.js,它包含在lib文件夹中。但是,您也可以在responseText 属性中简单地提供已经字符串化的JSON版本。

如果您计划模拟xml响应,则可能还必须包含 jquery.xmldom.js,也可以在lib文件夹中找到。

Mockjax深度

此时Mockjax所做的是$.ajax()用一个透明地检查所请求的URL的包装器替换该方法。如果URL与定义的URL匹配$.mockjax(),则它会拦截请求并XMLHttpRequest在执行jQuery.ajax()处理程序之前设置模拟对象 。否则,请求将返回到本机$.ajax()方法以进行正常执行。这个实现细节的一个好处是通过模拟XMLHttpRequest对象,插件继续使用jQuery的本机ajax处理,因此不需要实现自定义Ajax工作流。

在编写模拟响应的代码时,生成代码不需要修改这一事实具有很大的价值。模拟可以透明地插入。通过构建框架包含插件和模拟定义,这可以轻松集成到大多数框架中。通过侦听查询字符串标志并注入插件和定义,也可以在运行时包含它。

现在让我们看一下定义插件提供的模拟的各种方法。以下部分概述了Mockjax的灵活性并创建了响应。

可用于模拟的数据类型 jQuery是能够处理和分析Text,HTML,JSON,JSONP, Script和XML数据格式和Mockjax能够嘲笑任何这些格式。有两点需要注意:取决于你如何模拟JSON, JSONP你可能需要 为方法包含json2.jsJSON.stringify()(通常只包括旧浏览器)。此外,如果您模拟XML内联,则需要包含将xmlDOM XML字符串转换为DOM对象的插件。但是,如果您使用下面概述的代理方法,那么在任何情况下都不需要包含JSON或XMLDOM插件。

详细的请求和响应定义

定义匹配请求

模拟请求时,您需要做的第一件事是定义拦截和模拟的URL端点。与上面的示例一样,这可以是一个简单的字符串:

$.mockjax({
  url: "/url/to/rest-service"
});

或包含*一个通配符:

$.mockjax({
  // Matches /data/quote, /data/tweet etc.
  url: "/data/*"
});

或完整的正则表达式:

$.mockjax({
  // Matches /data/quote, /data/tweet but not /data/quotes
  url: /^\/data\/(quote|tweet)$/i
});

除了url之外,您还可以匹配数据选项:

$.mockjax({
  url:  "/rest",
  data: { action: "foo" }
});

该数据选择可能是一个自定义的匹配函数返回true的false 数据是否预期或不:

$.mockjax({
  url: "/rest",
  data: function( data ) {
    return deepEqual( data, expected );
  }
});

数据函数是断言的推荐位置。返回true并让选择的测试框架完成剩下的工作:

$.mockjax({
  url: "/rest",
  data: function ( json ) {
    assert.deepEqual( JSON.parse(json), expected ); // QUnit example.
    return true;
  }
});

要捕获URL参数,请使用URL的捕获正则表达式和urlParams数组来指示通常将捕获的参数的名称:

$.mockjax({
  // matches /author/{any number here}/isbn/{any number with dashes here}
  // for example: "/author/1234/isbn/1234-5678-9012-0"
  url: /^\/author\/([\d]+)\/isbn\/([\d\-]+)$/,
  // names of matching params
  urlParams: ["authorID", "isbnNumber"],
  response: function (settings) {
    var authorID = settings.urlParams.authorID;
    var isbnNumber = settings.urlParams.isbnNumber;
    // etc...
  }
});

定义多个请求

从版本2.2开始,允许一次定义多个请求。 $.mockjax([…])返回处理程序索引的数组。可以通过索引重置处理程序。阅读删除Mockjax处理程序的更多内容。

var handlers = $.mockjax([
  {url: '/rest', responseText: 'one'},
  {url: '/rest', responseText: 'two'}
]);

$.mockjax.clear(handlers[0]);

定义响应

第二步是定义响应的类型和内容。您将要处理的两个主要属性是responseText或 responseXML。这些属性镜像XMLHttpRequest 在实时响应期间设置的本机对象属性。指定响应有三种不同的模式:内联,代理和回调。

内联响应

一个简单的文本响应是:

$.mockjax({
  url: "/restful/api",
  responseText: "A text response from the server"
});

一个简单的JSON响应是:

$.mockjax({
  url: "/restful/api",
  // You may need to include the [json2.js](https://raw.github.com/douglascrockford/JSON-js/master/json2.js) library for older browsers
  responseText: { "foo": "bar" }
});

另请注意,JSON响应实际上只是一个文本响应,jQuery将为您解析为JSON(并将JSON对象返回给success和complete 回调)。

一个简单的XML响应是:

$.mockjax({
  url: "/restful/api",
  // Need to include the xmlDOM plugin to have this translated into a DOM object
  responseXML: "<document><quote>Hello world!</quote></document>"
});

正如您所看到的,如果您有大量数据被嘲笑,这将变得难以处理。这样就把我们带到了下一个模式:代理。

Proxy

在下面的示例中,Mockjax插件将拦截请求 /restful/api并将其重定向到/mocks/data.json:

$.mockjax({
  url: "/restful/api",
  proxy: "/mocks/data.json"
});

该/mocks/data.json文件可以包含您想要的任何有效JSON内容,并允许您将该模拟数据保存在自己的文件中以实现可维护性。

注意:如果您使用poxy测试代码,最好为测试运行实际的Web服务器。只需test/index.html从文件系统加载可能导致代理文件无法正确加载。我们建议使用像http-servernpm模块这样的东西。

Callback

在最后的响应模式,我们可以定义在一个回调函数 response性质,并将它设置responseText或responseXML根据需要:

$.mockjax({
  url: "/restful/api",
  response: function(settings) {
    // Investigate the `settings` to determine the response...

    this.responseText = "Hello world!";
  }
});

此回调的默认版本是同步的。如果为回调函数提供这两个参数,则可以使用异步代码设置动态响应。

$.mockjax({
  url: '/restful/api',
  response: function(settings, done) {
    var self = this;
    someAsyncMethod(function(data){
      self.responseText = data;
      done();
    });
  }
});

请注意,回调给出了$.mockjax({…}) 与jQuery或您的应用程序定义的任何Ajax设置合并的方法提供的设置。这允许您在设置响应正文(或标题)之前彻底调查请求。

先进的模拟技术

在这一点上,我们已经了解了Mockjax的一系列基本模拟技术,现在将解压缩插件中包含的一些其他功能。

模拟响应时间和延迟

模拟模拟的网络和服务器延迟就像responseTime在模拟定义中添加属性一样简单:

$.mockjax({
  url: "/restful/api",
  // Simulate a network latency of 750ms
  responseTime: 750,
  responseText: "A text response from the server"
});

您还可以使用间隔responseTime来随机化延迟:

$.mockjax({
  url: "/restful/api",
  // Use a random value between 250ms and 750ms
  responseTime: [250, 750],
  responseText: "A text response from the server"
});

模拟HTTP响应状态

通过简单地添加status属性,也可以模拟200以外的响应状态(默认为Mockjax)。

$.mockjax({
  url: "/restful/api",
  // Server 500 error occurred
  status: 500,
  responseText: "A text response from the server"
});

能够提供一系列可能的响应状态(从中随机选择给定请求的响应):

// Randomly fail
$.mockjax({
  url: "/restful/api",
  status: [200,400,500]
});

// Randomly fail (with a preference towards success)
$.mockjax({
  url: "/restful/api",
  status: [200,400,200,500,200]
});

这些强制错误状态代码将被处理,就像服务器返回错误一样:error回调将使用正确的参数执行。

设置 Content-Type

您可以设置内容类型以与模拟响应关联,在​​下面的示例中,我们将设置JSON内容类型。

$.mockjax({
  url: "/restful/api",
  contentType: "application/json",
  responseText: {
    hello: "World!"
  }
});

设置其他HTTP响应标头

可以通过在头对象文字中设置密钥来提供其他HTTP响应头:

$.mockjax({
  url: "/restful/api",
  contentType: "application/json",
  responseText: {
    hello: "World!"
  },
  headers: {
    etag: "xyz123"
  }
});

动态生成模拟定义

在某些情况下,所有REST调用都基于URL架构。Mockjax可以指定一个回复函数,该函数可以处理$.ajax请求设置。然后,回调函数可以返回false以允许本地处理请求,或者返回具有相关Mockjax参数集的对象文字。下面是一个重写所有Ajax请求以代理静态模拟的示例:

$.mockjax(function(settings) {

// settings.url might be: "/restful/<service>" such as "/restful/user"

    var service = settings.url.match(/\/restful\/(.*)$/);
    if ( service ) {
        return {
            proxy: "/mocks/" + service[1] + ".json"
        };
    }
    // If you get here, there was no url match
    return;
});

访问请求标头

在某些情况下,您可能需要访问请求标头以确定匹配或响应主体。为此,您需要指定一个处理$.ajax请求设置的回调函数:

$.mockjax(function( requestSettings ) {
  // Here is our manual URL matching...
  if ( requestSettings.url === "/restful/user" ) {
    // We have a match, so we return a response callback...
    return {
      response: function( origSettings ) {

      	// now we check the request headers, which may be set directly
      	// on the xhr object through an ajaxSetup() call or otherwise:

      	if ( requestSettings.headers["Authentication"] === "some-token" ) {
      	  this.responseText = { user: { id: 13 } };
      	} else {
  		  this.status = 403;
  		  this.responseText = "You are not authorized";
        }
      }
    };
  }
  // If you get here, there was no url match
  return;
});

强制模拟服务器超时

由于Mockjax的实现方式,它利用了jQuery对请求的内部超时处理。但是,如果您想强制请求超时,可以通过将isTimeout 属性设置为true来执行此操作:

$.mockjax({
  url: '/restful/api',
  responseTime: 1000,
  isTimeout: true
});

动态生成模拟响应

通过在response参数上实现回调函数,还可以在每个请求时动态生成响应文本:

$.mockjax({
  url: "/restful/webservice",
  dataType: "json",
  response: function(settings) {
    this.responseText = {
      randomText: "random " + Math.random()
    };
  }
});

数据类型

上面的许多例子都嘲笑了一个json回应。你也可以模仿xml:

$.mockjax({
  url: "/some/xml",
  dataType: "xml",
  responseXML: "<document><say>Hello world XML</say></document>"
});

(不要忘记,你可能也需要xmlDOM图书馆!)

而且html:

$.mockjax({
  url: "/some/webservice",
  dataType: "html",
  responseText: "<div>Hello there</div>"
});

请求完成后执行操作

如果您需要在呼叫完成后执行某些操作,则可以使用其中一个onAfter{Xxxxx}选项。例如,要在请求完成时(成功或不成功)触发方法:

$.mockjax({
  url: "/api/end/point",
  onAfterComplete: function() {
    // do any required cleanup
  }
});

全局定义Mockjax设置

也可以通过覆盖$.mockjaxSettings对象来定义所有Mockjax请求的全局默认值。默认情况下,设置如下:

{
  log:             null,  // DEPRECATED, use $.mockjaxSettings.logger instead
  logger:          window.console,
  logging:         2,
  logLevelMethods: ['error', 'warn', 'info', 'log', 'debug'],
  namespace:       null,
  status:          200,
  statusText:      "OK",
  responseTime:    500,
  isTimeout:       false,
  throwUnmocked:   false,
  retainAjaxCalls: true,
  contentType:     "text/plain",
  response:        "",
  responseText:    "",
  responseXML:     "",
  proxy:           "",
  proxyType:       "GET",
  lastModified:    null,
  etag:            "",
  headers: {
    etag: "IJF@H#@923uf8023hFO@I#H#",
    "content-type" : "text/plain"
  }
}

要覆盖特定设置(如默认设置)content-type,您将执行以下操作:

$.mockjaxSettings.contentType = "application/json";

设置全局URL命名空间

命名空间选项$.mockjaxSettings允许您将前缀应用于所有模拟的URL,例如/api/v1。

$.mockjaxSettings.namespace = "/api/v1";

然后以下模拟将匹配 /api/v1/rest

$.mockjax({
    url: "/rest"
})

全局命名空间选项也可以在特定的模拟上覆盖。

$.mockjax({
    url: "/rest-2",
    namespace: null
})

请注意,名称空间前缀不适用于代理。

全球定义匹配顺序

默认情况下,Mockjax按注册顺序匹配请求(mockjax认为在最后注册的处理程序之前首先注册的处理程序)。要扭转此行为:

$.mockjaxSettings.matchInRegistrationOrder = false;

设置matchInRegistrationOrder以false使您可以覆盖以前定义的处理程序。假设你有:

$.mockjax({
    url: "/rest",
    responseText: "hello"
});
$.mockjax({
    url: "/rest",
    responseText: "byebye"
});

默认行为是Mockjax返回"hello",但是matchInRegistrationOrder 设置为false,Mockjax将返回"byebye"。

此行为允许您在最初设置后覆盖旧处理程序。

删除Mockjax处理程序

如果您需要重置已添加的Mockjax处理程序,只需调用即可 $.mockjax.clear()。这不会重置$.mockjaxSettings!

$.mockjax.clear();

您还可以使用其ID清除单个模拟处理程序:

var id = $.mockjax({
   ...
});

$.mockjax.clear(id);

杂项信息

jQuery版本支持

我们努力确保Mockjax在jQuery的所有次要(和主要)版本的最远补丁版本上进行测试,从1.5.2开始一直到3.x. 换句话说,我们不测试1.6.1,而是测试1.6.4(1.6.x线上最远的补丁版本)。/test目录中的QUnit测试包括指向标题中测试的每个jQuery版本的链接。

浏览器测试

我们使用BrowserStack的强大开源协作,在平台上使用虚拟机在真实浏览器中测试Mockjax。我们在下面主要浏览器的当前版本以及指定的Internet Explorer的特定版本上运行所有测试。

  • Edge
  • Firefox
  • Chrome
  • Safari
  • Internet Explorer 9-11

在将代码合并到master之前,每个PR将使用TravisCI运行这些测试以进行持续集成,以确保我们不会引入回归。

以其他方式使用Mockjax

您可以将Mockjax用作Node模块,使用require.js,或使用Browserify ……并且可能还有其他方式。我们对上述每种方法都进行了测试。

当使用Mockjax作为Node模块(包括Browserify)时,必须为模块提供jQuery库和awindow。以下是使用模块作为“浏览器化”模块的示例:

var jquery =  require(' jquery ');
var mockjax =  require(' jquery-mockjax ')(jquery,window);
//请注意,我们希望
在浏览器中对此文件进行浏览并//使用后,才能定义`window` 。如果不是Mockjax会有问题!

var jquery = require('jquery');
var mockjax = require('jquery-mockjax')(jquery, window);
// Note that we expect `window` to be defined once this file is browserified and
// used in a browser. If it isn't Mockjax will have a problem!

mockjax({
    url: '/resource',
    responseText: 'content'
});

function getResource(cb) {
    jquery.ajax({
        url: '/resource',
        success: cb,
        error: cb
    });
}

记录

Mockjax将各种信息记录到浏览器中的console(on window)或Node中的stdout中。您可以自定义日志记录的各个方面以满足您的需求。默认情况下,仅显示“错误”,“警告”或“信息”消息,但调试日志中可能会提供详细信息。以下是您可能需要做的一些常见事情,以获得更好的日志记录信息。

显示不同级别的日志消息

$.mockjaxSettings.logging = 4;  // very verbose debug messages
$.mockjaxSettings.logging = 3;  // verbose log messages
$.mockjaxSettings.logging = 2;  // informational messages
$.mockjaxSettings.logging = 1;  // warning messages
$.mockjaxSettings.logging = 0;  // only critical error messages

(请注意,每个级别启用该级别加上任何较低的数字…因此设置日志记录2也会启用警告和错误。)

实现自定义记录器

如果您不想使用该console对象,则可以使用该logger设置传入您自己的日志记录实现。请注意,您必须记录器或者实现debug,log,info,warn,和error方法,或者你也必须提供什么样的方式映射到5级(0〜4)。

$.mockjaxSettings.logger = {
  debug: function() { ... },
  log: function() { ... },
  // ...
};

您的记录器方法可以接收任何数量的注销参数,可以是字符串或对象,类似于window.console对象方法的工作方式。

如果您有一个使用不同方法名称的记录器,请在此数组中指定它们:

$.mockjaxSettings.logLevelMethods = ['critical', 'bad', 'stuff', 'log', 'verbose'];

请注意,此数组(索引0)中的第一个条目将是错误,而最后一个条目将是详细输出。超出索引的任何内容4都将被忽略。

那个古老的log环境怎么样?

这是一个未记录的功能,您可以log使用$.mockjaxSettings它来提供方法 ,但不再在内部使用。这个未记录的选项现在已被弃用,虽然它可以工作,但是所有级别的日志消息都将被发送给它。

如果你不知道我们在谈论什么……好!别担心。实现自己的记录器的正确方法是通过 $.mockjaxSettings.logger

AXIHE / 精选资源

浏览全部教程

面试题

学习网站

前端培训
自己甄别

前端书籍

关于朱安邦

我叫 朱安邦,阿西河的站长,在杭州。

以前是一名平面设计师,后来开始接接触前端开发,主要研究前端技术中的JS方向。

业余时间我喜欢分享和交流自己的技术,欢迎大家关注我的 Bilibili

关注我: Github / 知乎

于2021年离开前端领域,目前重心放在研究区块链上面了

我叫朱安邦,阿西河的站长

目前在杭州从事区块链周边的开发工作,机械专业,以前从事平面设计工作。

2014年底脱产在老家自学6个月的前端技术,自学期间几乎从未出过家门,最终找到了满意的前端工作。更多>

于2021年离开前端领域,目前从事区块链方面工作了