萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 腳本程式專題 >> JavaScript

jQuery Ajax 完整配置指南:參數詳解、最佳實踐與常見坑

$.ajax() 是 jQuery 底層 Ajax 封裝,所有高層方法(.get()、.post()、.load())最終都調用它。本文系統梳理核心參數、現代寫法、錯誤處理、攔截器模式與 TypeScript 類型定義。

核心參數速查表

參數類型默認值說明
urlString當前頁請求地址
type / methodString'GET'HTTP 方法:GET/POST/PUT/DELETE/PATCH
dataObject/String/Arraynull發送數據,對象自動序列化為查詢字符串
dataTypeString智能猜測預期返回類型:json/xml/html/script/text/jsonp
contentTypeString/Boolean'application/x-www-form-urlencoded; charset=UTF-8'發送內容類型,false 時不設置(用於 FormData)
processDataBooleantruetrue 時將 data 轉為查詢字符串,File/FormData 必須 false
asyncBooleantrue異步請求,**強烈建議保持 true**,同步會阻塞主線程
cacheBooleantrue (GET 為 false)GET 請求自動加 _ 參數防緩存
timeoutNumber0 (無超時)毫秒數,超時觸發 error(jqXHR, 'timeout')
headersObject{}額外請求頭,如 {'X-CSRF-Token': 'xxx'}
xhrFieldsObject{}設置底層 XHR 對象屬性,如 withCredentials: true 跨域攜帶 Cookie
beforeSendFunction(jqXHR, settings)無發送前修改 jqXHR,返回 false 可取消請求
successFunction(data, status, jqXHR)無成功回調
errorFunction(jqXHR, status, error)無失敗回調,status: timeout/error/abort/parsererror
completeFunction(jqXHR, status)無無論成敗均執行
statusCodeObject{}HTTP 狀態碼映射處理函數,如 {404: fn, 500: fn}

現代推薦寫法(Promise + async/await)

// 封裝為 Promise
function ajax(options) {
  return new Promise((resolve, reject) => {
    $.ajax({
      ...options,
      success: (data, status, xhr) => resolve({data, status, xhr}),
      error: (xhr, status, err) => reject({xhr, status, err})
    });
  });
}

// 使用
async function fetchUser(id) {
  try {
    const {data} = await ajax({
      url: `/api/users/${id}`,
      method: 'GET',
      dataType: 'json',
      headers: {'Authorization': `Bearer ${getToken()}`}
    });
    return data;
  } catch ({xhr, status, err}) {
    if (status === 'timeout') return showToast('請求超時');
    if (xhr.status === 401) return redirectLogin();
    throw new Error(`請求失敗: ${xhr.status} ${err}`);
  }
}

全局攔截器($.ajaxSetup / ajaxPrefilter / ajaxTransport)

// 1. 統一添加 CSRF Token
$.ajaxPrefilter((options, original, jqXHR) => {
  if (!options.crossDomain) {
    jqXHR.setRequestHeader('X-CSRF-Token', $('meta[name=csrf-token]').attr('content'));
  }
});

// 2. 統一錯誤處理
$(document).ajaxError((e, jqXHR, settings, thrownError) => {
  if (jqXHR.status === 401) {
    // 避免重複彈窗
    if (!window._loginRedirectShown) {
      window._loginRedirectShown = true;
      alert('登錄已過期,請重新登錄');
      location.href = '/login?redirect=' + encodeURIComponent(location.pathname);
    }
  }
});

// 3. 統一 Loading 狀態
$(document).ajaxStart(() => Loading.show());
$(document).ajaxStop(() => Loading.hide());

常見坑點與解決

1. contentType 與 dataType 搞混
contentType = 請求頭 Content-Type(發送格式);dataType = 預期響應解析格式。發送 JSON 時:contentType: 'application/json', data: JSON.stringify(obj), dataType: 'json'。
2. 上傳文件必須 processData: false, contentType: false
const formData = new FormData();
formData.append('file', fileInput.files[0]);
$.ajax({url: '/upload', method: 'POST', data: formData, processData: false, contentType: false});
3. 同步請求 (async: false) 導致頁面卡死
瀏覽器控制台會報警告,**永遠不要用**。改用 Promise/async-await 串行處理。
4. dataType: 'jsonp' 跨域原理
動態創建 <script src="url?callback=jQuery12345">,要求後端返回 jQuery12345({...})。**僅支持 GET**,且有 XSS 風險,現代項目改用 CORS。
5. 參數序列化陷阱
$.param({arr: [1,2]}) 默認生成 arr[]=1&arr[]=2(PHP 風格)。若後端為 Java/Spring 需 arr=1&arr=2,設置 $.ajaxSettings.traditional = true 或單次 traditional: true。

TypeScript 類型增強

// types/jquery.ajax.d.ts
interface JQueryAjaxSettings {
  /** 自定義業務碼處理 */
  businessCodeHandler?: (code: number, msg: string, data: any) => boolean;
}

declare interface JQueryStatic {
  ajax(settings: JQueryAjaxSettings): JQuery.jqXHR & PromiseLike<{data: T, status: string, xhr: JQuery.jqXHR}>;
}

總結

  • 掌握 $.ajax() 全參數,能應對 99% 複雜網絡場景。
  • **封裝 Promise** 是現代化關鍵,配合 async/await 寫出同步風格異步代碼。
  • 用 ajaxPrefilter 實現橫切關注點(Token、簽名、Loading、錯誤統一處理)。
  • 新項目優先考慮 Fetch API + 封裝庫 (ky, ofetch, axios),jQuery Ajax 適合存量維護專案。
copyright © 萬盛學電腦網 all rights reserved