jQuery Ajax 提供**全域事件**與**局部 Promise 鏈**雙重錯誤處理機制。理解兩者關係、執行順序與最佳實踐,能構建健壯的前後端交互體驗。本文以載入圖片片段為例,完整演示全域監控、錯誤攔截、載入狀態管理。
| 事件 | 觸發時機 | 典型用途 |
|---|---|---|
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));
});
.load() 簡便方法// 載入片段 HTML
$('#btn-load').click(function() {
$('#content').load('fragment.html', function(response, status, xhr) {
if (status === 'error') {
$('#content').html('載入失敗: ' + xhr.status + '');
}
});
});
$.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();
});
});
$.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 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 + 統一攔截器,獲得更標準、更易測試的非同步架構。