萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 資料庫 >> 資料庫綜合

jQuery Ajax 全域事件與錯誤處理:從 ajaxStart/Stop 到 fail/always 的完整鏈路

前言

jQuery Ajax 提供**全域事件**與**局部 Promise 鏈**雙重錯誤處理機制。理解兩者關係、執行順序與最佳實踐,能構建健壯的前後端交互體驗。本文以載入圖片片段為例,完整演示全域監控、錯誤攔截、載入狀態管理。

一、全域 Ajax 事件:應用級橫切關注點

事件觸發時機典型用途
ajaxStart首個 Ajax 請求發送,且無其他進行中請求顯示全域 Loading 遮罩、禁用提交按鈕
ajaxSend每個請求發送前 (beforeSend)注入 CSRF Token、統一 Header、請求日誌
ajaxSuccess請求成功 (HTTP 2xx)統一成功提示、埋點上報
ajaxError請求失敗 (HTTP 非 2xx / timeout / abort)統一錯誤提示、重試邏輯、Sentry 上報
ajaxComplete請求完成 (成功/失敗皆觸發)隱藏 Loading、恢復按鈕、清理狀態
ajaxStop所有 Ajax 請求完成 (佇列為空)隱藏全域 Loading、解除頁面鎖定

綁定方式:必須掛載在 document 或 body

$(document)
    .ajaxStart(function() { $('#global-loading').show(); })
    .ajaxStop(function() { $('#global-loading').hide(); })
    .ajaxError(function(event, jqXHR, settings, thrownError) {
        // jqXHR: jqXHR 物件, settings: 原始設定, thrownError: 錯誤訊息
        if (jqXHR.status === 401) location.href = '/login';
        else if (jqXHR.status === 0) toast('網路異常,請檢查連線');
        else toast('請求失敗: ' + (thrownError || jqXHR.status));
    });

二、局部 Promise 鏈:請求級精細控制

1. .load() 簡便方法

// 載入片段 HTML
$('#btn-load').click(function() {
    $('#content').load('fragment.html', function(response, status, xhr) {
        if (status === 'error') {
            $('#content').html('
載入失敗: ' + xhr.status + '
'); } }); });

2. $.get / $.post / $.ajax + Promise 鏈 (推薦)

$('#btn-api').click(function() {
    var $btn = $(this).prop('disabled', true);
    var $spinner = $('').insertAfter($btn);

    $.get('/api/data')
        .done(function(data) { render(data); })
        .fail(function(jqXHR, textStatus, errorThrown) {
            toast('API 錯誤: ' + (errorThrown || textStatus));
        })
        .always(function() {
            $btn.prop('disabled', false);
            $spinner.remove();
        });
});

3. 進階 $.ajax 完整選項

$.ajax({
    url: '/api/complex',
    method: 'POST',
    data: JSON.stringify(payload),
    contentType: 'application/json',
    dataType: 'json',
    timeout: 10000,           // 10 秒超時
    cache: false,
    headers: { 'X-CSRF-Token': token },
    beforeSend: function(xhr) { xhr.setRequestHeader('X-Request-ID', uuid()); },
    // 全域事件仍會觸發,若需關閉:
    // global: false
})
.then(
    function success(data, textStatus, jqXHR) { /* ... */ },
    function fail(jqXHR, textStatus, errorThrown) { /* ... */ }
);

三、執行順序與傳播關係


// 單一請求發送時序
1. ajaxStart (全域,僅首個請求)
2. beforeSend (局部選項)
3. ajaxSend (全域)
4. --- 網路傳輸 ---
5. success 回調 / done (局部)
6. ajaxSuccess (全域)
7. complete 回調 / always (局部)
8. ajaxComplete (全域)
9. ajaxStop (全域,佇列空時)

關鍵點:global: false 可阻止該請求觸發全域事件 (適用於輪詢/心跳/靜默同步)。

四、錯誤處理最佳實踐

層級策略代碼模式
網路/HTTP 錯誤全域 ajaxError 統一處理 401/403/500/0導向登入、重試、Toast 提示
業務邏輯錯誤HTTP 200 但 data.code !== 0,在 .done() 內處理顯示後端返回錯誤訊息、引導用戶操作
超時/中斷timeout 選項 + textStatus==='timeout'自動重試 (指數退避) 或提示用戶
驗證錯誤422 Unprocessable Entity,回傳欄位錯誤詳情解析 jqXHR.responseJSON.errors 綁定至表單

五、現代化替代:Fetch API + 統一攔截器

// 封裝統一錯誤處理的 fetch wrapper
async function api(url, options = {}) {
    const res = await fetch(url, { credentials: 'include', ...options });
    if (res.status === 401) { location.href = '/login'; throw new Error('Unauthorized'); }
    if (!res.ok) { const err = await res.json().catch(() => ({})); throw new Error(err.message || res.statusText); }
    return res.json();
}

// 使用
try {
    const data = await api('/api/data');
    render(data);
} catch (e) { toast(e.message); }

結語

jQuery Ajax 全域事件處理**橫切關注點** (Loading、認證、日誌),局部 Promise 鏈處理**業務邏輯** (渲染、表單驗證、狀態更新)。兩層分工明確,配合 global: false 靈活控制。新專案建議遷移至 fetch + async/await + 統一攔截器,獲得更標準、更易測試的非同步架構。

copyright © 萬盛學電腦網 all rights reserved