摘要：簡(jiǎn)要說(shuō)明前面我寫了一篇方法封裝及文件設(shè)計(jì)文檔，主要用來(lái)說(shuō)明我們?cè)陧?xiàng)目中通常會(huì)對(duì)的方法進(jìn)行進(jìn)一步的封裝處理，便于我們?cè)跇I(yè)務(wù)代碼中使用。這篇文檔我們主要對(duì)封裝的方法進(jìn)行一個(gè)簡(jiǎn)要說(shuō)明。

前面我寫了一篇《jquery ajax 方法封裝及 api 文件設(shè)計(jì)》文檔，主要用來(lái)說(shuō)明我們?cè)陧?xiàng)目中通常會(huì)對(duì) jquery 的 ajax 方法進(jìn)行進(jìn)一步的封裝處理，便于我們?cè)跇I(yè)務(wù)代碼中使用。從那篇文檔中我們可以了解到如何封裝ajax方法、如何設(shè)計(jì) API 文件，以及如何在業(yè)務(wù)代碼中調(diào)用 API 接口。

這篇文檔我們主要對(duì)封裝的 ajax 方法進(jìn)行一個(gè)簡(jiǎn)要說(shuō)明。這里的封裝主要是將 $.ajax() 返回的 jqXHR 對(duì)象，通過(guò)調(diào)用 jQuery.Deferred() 方法創(chuàng)建成一個(gè)可鏈?zhǔn)秸{(diào)用的工具對(duì)象（其實(shí) jqXHR 本身就是 Deferred 對(duì)象，本來(lái)就可以進(jìn)行鏈?zhǔn)秸{(diào)用，后面會(huì)對(duì)此進(jìn)行說(shuō)明）。這樣我們就可以使用下面這種形式進(jìn)行鏈?zhǔn)秸{(diào)用：

// 鏈?zhǔn)秸{(diào)用
absService.getAbsListData(conditionObj)
  .done(function (result) {
    var data = ts.handleData(result);
    ts.render(data, columnChange);
  })
  .fail(function (err, jqXHR) {
    Util.hideLoading("#abs-all-container");
  });

同時(shí)，通過(guò)一些處理，也允許調(diào)用者使用如下形式進(jìn)行調(diào)用：

// 傳入成功回調(diào)、失敗回調(diào)
absService.getAbsListData(conditionObj, function (result) {
    var data = ts.handleData(result);
    ts.render(data, columnChange);
  }, function (err, jqXHR) {
    Util.hideLoading("#abs-all-container");
  });

實(shí)際上，從 jQuery 1.5 開始，$.ajax() 返回的 jqXHR 對(duì)象就已經(jīng)實(shí)現(xiàn)了 Promise 接口, 使它擁有了 Promise 的所有屬性，方法和行為。也就是說(shuō) $.ajax() 返回的 jqXHR 對(duì)象本身就可以使用如下形式的調(diào)用：

$.ajax(options)
  .done(function (result, textStatus, jqXHR) {
    if (requestId === requestIdentifier[serviceName]) {
      ajaxRequest.ajax.handleResponse(result, $dfd, jqXHR, userOptions, serviceName, requestId);
      }
  })
  .fail(function (jqXHR, textStatus, errorThrown) {
    if (requestId === requestIdentifier[serviceName]) {
      //jqXHR.status
      $dfd.reject.apply(this, arguments);
      userOptions.error.apply(this, arguments);
    }
  });

既然已經(jīng)可以使用這種方式使用 jqXHR對(duì)象，那為什么不直接將 jqXHR對(duì)象返回，然后在業(yè)務(wù)代碼中直接使用 jqXHR.done() 和 jqXHR.fail() 方法呢？為什么還要進(jìn)一步將其包裝成一個(gè)新的 Deferred 對(duì)象呢？

答：是為了在成功和失敗回調(diào)調(diào)用之前做一些統(tǒng)一的處理，比如對(duì)接口返回的數(shù)據(jù)進(jìn)行判斷、對(duì)返回的 JSON 字符串進(jìn)行解析、在請(qǐng)求失敗時(shí)輸出方法名和錯(cuò)誤信息等，我們把這些每次接口調(diào)用都會(huì)進(jìn)行的操作進(jìn)行統(tǒng)一處理，實(shí)現(xiàn)代碼復(fù)用，這樣業(yè)務(wù)代碼中就只需要關(guān)注拿到數(shù)據(jù)后的處理邏輯即可。

這些統(tǒng)一進(jìn)行的操作，我們放在 $.ajax().done() 和 $.ajax().fail() 方法中去執(zhí)行，然后將 $.ajax() 返回的 jqXHR對(duì)象包裝成新的 Deferred 對(duì)象，這樣就可以在業(yè)務(wù)代碼中通過(guò)鏈?zhǔn)秸{(diào)用做進(jìn)一步的處理，比如刷新表格內(nèi)容、更新頁(yè)面動(dòng)態(tài)等等。

/**
 * 封裝 jquery ajax 
 * 例如:
 * ajaxRequest.ajax.triggerService(
 *   "apiCommand", [命令數(shù)據(jù)] )
 *   .then(successCallback, failureCallback);
 * );
 */
var JSON2 = require("LibsDir/json2");
var URL = "../AjaxHandler.aspx?r=";

// 用來(lái)記錄每次請(qǐng)求的唯一標(biāo)識(shí), 鍵值對(duì)形式, 形如:
// var requestIdentifier = {
//   SearchABSList: "b80a3876-9bca-40d1-b2cd-0daa799591e7",
//   SetABSUserColumns: "cafe3f01-2ee2-41f0-aeca-d630429f89f4",
// };
var requestIdentifier = {};

// 唯一標(biāo)識(shí)生成方法
function generateGUID() {
  var d = new Date().getTime();
  if (typeof performance !== "undefined" && typeof performance.now === "function") {
    d += performance.now();
  }
  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, function (c) {
    var r = (d + Math.random() * 16) % 16 | 0;
    d = Math.floor(d / 16);
    return (c === "x" ? r : (r & 0x3 | 0x8)).toString(16);
  });
}


// 模塊主體
var ajaxRequest = ajaxRequest || {};
(function ($) {
  if (!$) {
    throw "jquery獲取失敗!";
  }

  ajaxRequest.json = JSON2;

  /**
   * 觸發(fā)請(qǐng)求, 返回包裝成 Deferred 對(duì)象的 jqXHR
   * @param    {object}    userOptions   參數(shù)對(duì)象(包含方法名、參數(shù)對(duì)象、成功回調(diào)、失敗回調(diào))
   * @param    {string}    serviceName   方法名
   * @param    {string}    requestId     請(qǐng)求的唯一標(biāo)識(shí)
   * @returns  object
   */
  ajaxRequest.ajax = function (userOptions, serviceName, requestId) {
    userOptions = userOptions || {};

    // 將參數(shù)對(duì)象與ajax的默認(rèn)項(xiàng)組成一個(gè)新的對(duì)象, 作為 jquery ajax 方法的配置項(xiàng)
    var options = $.extend({}, ajaxRequest.ajax.defaultOpts, userOptions);

    // 將 jquery ajax 方法默認(rèn)的 success 回調(diào)和 error 回調(diào)置為 undefined
    // .done()方法取代了的過(guò)時(shí)的jqXHR.success()方法
    // .fail()方法取代了的過(guò)時(shí)的.error()方法
    options.success = undefined;
    options.error = undefined;

    // 將 jqXHR 包裝成新的 Deferred 對(duì)象返回
    // jQuery.Deferred([beforeStart]) 一個(gè)工廠函數(shù), 這個(gè)函數(shù)返回一個(gè)鏈?zhǔn)綄?shí)用對(duì)象
    // beforeStart - 一個(gè)構(gòu)造函數(shù)返回之前調(diào)用的函數(shù)
    return $.Deferred(function ($dfd) {
      $.ajax(options)
        .done(function (result, textStatus, jqXHR) {
          if (requestId === requestIdentifier[serviceName]) {
            // 比對(duì)請(qǐng)求id, 保證返回結(jié)果的正確性 (重復(fù)請(qǐng)求有可能會(huì)帶來(lái)返回結(jié)果不可靠的問(wèn)題)
            ajaxRequest.ajax.handleResponse(result, $dfd, jqXHR, userOptions, serviceName, requestId);
          }
        })
        .fail(function (jqXHR, textStatus, errorThrown) {
          if (requestId === requestIdentifier[serviceName]) {
            // jqXHR.status
            $dfd.reject.apply(this, arguments);
            userOptions.error.apply(this, arguments);
          }
        });
    });
  };

  $.extend(ajaxRequest.ajax, {
    // $.ajax() 的默認(rèn)設(shè)置
    defaultOpts: {
      // url: "../AjaxSecureHandler.aspx,
      dataType: "json",
      type: "POST",
      contentType: "application/x-www-form-urlencoded; charset=UTF-8"
    },

    // 在業(yè)務(wù)代碼的回調(diào)執(zhí)行之前, 做一些統(tǒng)一處理, 實(shí)現(xiàn)代碼復(fù)用
    // $dfd.resolve() 和 $dfd.reject() 的執(zhí)行, 會(huì)使得使用 .then()/.done() 中的回調(diào)方法得到執(zhí)行
    // userOptions.success() 和 userOptions.error() 是調(diào)用用戶以參數(shù)形式傳入的成功回調(diào)函數(shù)和失敗回調(diào)函數(shù)
    // 一般來(lái)說(shuō), 上述兩種方式只會(huì)有一個(gè)真正起到作用, 這取決于用戶調(diào)用的方式: 
    // 如果是使用 $.ajax().done().fail() 這種方式調(diào)用, 那么 $dfd.resolve()/$dfd.reject() 會(huì)起到作用
    // 此時(shí) userOptions.success/userOptions.error 都是 undefined, 自然不會(huì)得到執(zhí)行, 反之亦然
    handleResponse: function (result, $dfd, jqXHR, userOptions, serviceName, requestId) {
      if (!result) {
        $dfd && $dfd.reject(jqXHR, "error response format!");
        userOptions.error(jqXHR, "error response format!");
        return;
      }

      // 服務(wù)器已經(jīng)錯(cuò)誤
      if (result.ErrorCode != "200") {
        $dfd && $dfd.reject(jqXHR, result.ErrorMessage);
        userOptions.error(jqXHR, result);
        return;
      }

      if (result.Data) {
        // 將大于2^53的數(shù)字(16位以上)包裹雙引號(hào), 避免溢出
        var jsonStr = result.Data.replace(/(:s*)(d{16,})(s*,|s*})/g, "$1"$2"$3");
        var resultData = ajaxRequest.json.parse(jsonStr);

        // $dfd.resolve() 執(zhí)行之后, 業(yè)務(wù)代碼中的回調(diào)會(huì)執(zhí)行, 即.then()/.done()方法會(huì)得到執(zhí)行
        $dfd.resolve(resultData);
        // 如果是使用傳統(tǒng)的傳入成功回調(diào)函數(shù)的形式進(jìn)行調(diào)用的, 那么在此處調(diào)用用戶設(shè)定的成功回調(diào)
        userOptions.success && userOptions.success(resultData);
      } else {
        $dfd.resolve();
        userOptions.success && userOptions.success();
      }
    },

    /**
     * 構(gòu)建請(qǐng)求參數(shù)對(duì)象
     * @param    {string}    serviceName   方法名
     * @param    {object}    input         傳入的參數(shù)對(duì)象
     * @param    {function}  userSuccess   成功回調(diào)
     * @param    {function}  userError     失敗回調(diào)
     * @param    {object}    ajaxParams    其他參數(shù)
     * @returns  object
     */
    buildServiceRequest: function (serviceName, input, userSuccess, userError, ajaxParams) {
      // 這里是根據(jù)后臺(tái)要求構(gòu)建的
      var requestData = {
        MethodAlias: serviceName, // 方法名
        Parameter: input // 傳遞的參數(shù)
      };

      var request = $.extend({}, ajaxParams, {
        // 這里要對(duì)傳遞的 JSON 字符串參數(shù)數(shù)據(jù)使用 escape 方法進(jìn)行編碼
        // "data=" 是根據(jù)項(xiàng)目約定增加的，與 contentType 相對(duì)應(yīng)
        data: "data=" + escape(ajaxRequest.json.stringify(requestData)),
        success: userSuccess,
        error: function (jqXHR, textStatus, errorThrown) {
          // 這里是在請(qǐng)求出錯(cuò)的時(shí)候做一個(gè)統(tǒng)一處理, 輸出方法名和錯(cuò)誤對(duì)象
          console.log(serviceName, jqXHR);
          if (userError && (typeof userError === "function")) {
            userError(jqXHR, textStatus, errorThrown);
          }
        }
      });

      return request;
    },

    // 構(gòu)建參數(shù)對(duì)象, 生成唯一標(biāo)識(shí), 觸發(fā)請(qǐng)求
    triggerService: function (serviceName, input, success, error, ajaxParams) {
      // 構(gòu)建參數(shù)對(duì)象
      var request = ajaxRequest.ajax.buildServiceRequest(serviceName, input, success, error, ajaxParams);

      // 生成此次 ajax 請(qǐng)求唯一標(biāo)識(shí)
      var requestId = requestIdentifier[serviceName] = generateGUID();
      request.url = URL + requestId;

      // 觸發(fā)請(qǐng)求
      return ajaxRequest.ajax(request, serviceName, requestId);
    }
  });

})(jQuery);

module.exports = ajaxRequest;