ajax回调钩子的应用简介

$.ajax() 是 jQuery 中最核心的 AJAX 方法，它提供了丰富的 回调钩子（Callback Options），让你可以在请求的不同阶段插入自定义逻辑。

下面是对 beforeSend、success 等常用参数的全面、详细、带示例的介绍。

✅ $.ajax() 常用回调参数详解

参数名	触发时机	是否异步	典型用途
beforeSend	请求发送前	同步	设置请求头、取消请求
success	请求成功（HTTP 2xx）	异步	处理返回数据、更新页面
error	请求失败（网络错误、4xx/5xx）	异步	错误提示、重试机制
complete	请求完成（无论成功或失败）	异步	隐藏加载动画、清理资源
statusCode	按 HTTP 状态码定制处理	异步	特定状态码处理（如 401 跳登录）

---

1️⃣ beforeSend(xhr, settings)

触发时机

• 在请求发送之前立即调用
• 是最后一个可以修改请求的机会
• 执行是同步的（会阻塞请求发送）

参数

参数	类型	说明
xhr	XMLHttpRequest	原生请求对象，可用于设置请求头
settings	Object	当前请求的配置项（包含 url, type, data 等）

典型用途

• 设置认证头（如 Authorization）
• 添加 CSRF Token
• 条件性取消请求
• 显示加载动画（开始）

✅ 示例代码

$.ajax({
    url: '/api/data',
    type: 'POST',
    data: { name: '张三' },
    beforeSend: function(xhr, settings) {
        // 1. 添加 CSRF Token（Django 项目常见）
        var token = getCookie('csrftoken');
        if (token) {
            xhr.setRequestHeader('X-CSRFToken', token);
        }
        // 2. 添加 JWT 认证头
        var jwt = localStorage.getItem('token');
        if (jwt) {
            xhr.setRequestHeader('Authorization', 'Bearer ' + jwt);
        }
        // 3. 条件性取消请求
        if (settings.type === 'DELETE' && !confirm('确定要删除吗？')) {
            return false; // 返回 false 可取消请求
        }
        // 4. 显示加载动画
        $('#loading').show();
    },
    success: function(data) {
        console.log('成功:', data);
    }
});

⚠️ 注意：beforeSend 中 return false 会取消请求。

---

2️⃣ success(data, textStatus, xhr)

触发时机

• 请求成功且服务器返回有效响应时调用
• HTTP 状态码为 2xx（如 200, 201）
• 执行是异步的

参数

参数	类型	说明
data	Object/String	解析后的响应数据（自动根据 dataType 解析）
textStatus	String	状态描述，通常是 "success"
xhr	XMLHttpRequest	原生请求对象，可读取响应头等

典型用途

• 更新页面内容（DOM 操作）
• 处理 JSON 数据
• 跳转页面
• 隐藏加载动画

✅ 示例代码

$.ajax({
    url: '/api/user',
    type: 'GET',
    dataType: 'json', // 告诉 jQuery 期望返回 JSON
    success: function(data, textStatus, xhr) {
        // data 已自动解析为 JavaScript 对象
        console.log('用户数据:', data);
        console.log('状态:', textStatus); // "success"
        console.log('响应头 ETag:', xhr.getResponseHeader('ETag'));
        // 更新页面
        $('#username').text(data.name);
        $('#email').text(data.email);
        // 跳转
        if (data.isAdmin) {
            window.location.href = '/admin';
        }
    }
});

如果 dataType 是 'json'，jQuery 会自动 JSON.parse()，你拿到的就是 JS 对象。

---

3️⃣ error(xhr, textStatus, errorThrown)

触发时机

• 请求失败时调用
• 包括：
  • 网络错误（无法连接）
  • HTTP 错误（404, 500, 403 等）
  • 超时
  • JSON 解析失败

参数

参数	类型	说明
xhr	XMLHttpRequest	可读取 status、statusText、响应体
textStatus	String	错误类型："timeout"、"error"、"abort"、"parsererror"
errorThrown	String	HTTP 状态文本（如 "Not Found"），仅当有 HTTP 错误时

典型用途

• 显示错误提示
• 日志记录
• 重试机制
• 处理特定错误（如 401 跳登录）

✅ 示例代码

$.ajax({
    url: '/api/data',
    type: 'GET',
    error: function(xhr, textStatus, errorThrown) {
        console.error('AJAX 错误:', textStatus, errorThrown);
        let message = '';
        if (textStatus === 'timeout') {
            message = '请求超时，请检查网络';
        } else if (xhr.status === 404) {
            message = '请求的资源不存在';
        } else if (xhr.status === 401) {
            message = '未登录，即将跳转...';
            setTimeout(() => {
                window.location.href = '/login';
            }, 1000);
        } else if (xhr.status === 500) {
            message = '服务器内部错误';
        } else {
            message = '请求失败：' + errorThrown;
        }
        alert(message);
    }
});

常见 textStatus：

• "timeout"：超时
• "error"：一般网络或服务器错误
• "abort"：请求被取消（如页面跳转）
• "parsererror"：JSON/XML 解析失败

---

4️⃣ complete(xhr, textStatus)

触发时机

• 请求完成后调用，无论成功或失败
• 是“收尾工作”的理想位置
• 总是执行一次

参数

参数	类型	说明
xhr	XMLHttpRequest	请求对象
textStatus	String	最终状态："success"、"notmodified"、"error"、"timeout"、"abort"

典型用途

• 隐藏加载动画
• 清理资源
• 统一日志记录

✅ 示例代码

$.ajax({
    url: '/api/upload',
    type: 'POST',
    beforeSend: function() {
        $('#loading').show(); // 显示加载
    },
    success: function(data) {
        alert('上传成功！');
    },
    error: function() {
        alert('上传失败！');
    },
    complete: function(xhr, textStatus) {
        // 无论成功失败都隐藏加载动画
        $('#loading').hide();
        // 统一日志
        console.log('请求结束，状态:', textStatus);
        console.log('最终状态码:', xhr.status);
    }
});

✅ 这是最佳实践：beforeSend 显示加载，complete 隐藏加载。

---

5️⃣ statusCode（高级用法）

作用

• 按 HTTP 状态码 定制处理函数
• 可以与 error 并存，更精细控制

✅ 示例代码

$.ajax({
    url: '/api/data',
    type: 'GET',
    statusCode: {
        404: function() {
            alert('页面找不到了');
        },
        403: function() {
            alert('权限不足');
        },
        401: function() {
            alert('请先登录');
            window.location.href = '/login';
        },
        500: function() {
            alert('服务器开小差了，请稍后再试');
        },
        200: function(data) {
            // 也可以为 200 写处理（但通常用 success 更好）
            console.log('正常返回:', data);
        }
    },
    error: function(xhr, status) {
        // 如果 statusCode 中没有匹配的状态码，才会走 error
        alert('未知错误:', status);
    }
});

优先级：statusCode > error

---

完整示例：综合使用所有回调

$.ajax({
    url: '/api/profile',
    type: 'PUT',
    data: { name: '李四', age: 25 },
    beforeSend: function(xhr) {
        // 设置认证
        xhr.setRequestHeader('Authorization', 'Bearer ' + getToken());
        // 显示加载
        $('#spinner').show();
    },
    success: function(data) {
        alert('保存成功！');
        $('#profile-form').addClass('saved');
    },
    error: function(xhr, status, err) {
        if (status !== 'abort') { // 排除手动取消
            alert('保存失败: ' + err);
        }
    },
    complete: function() {
        // 隐藏加载
        $('#spinner').hide();
    },
    statusCode: {
        401: function() {
            window.location.href = '/login';
        }
    }
});

---

总结表格

回调	触发条件	是否可取消请求	常见用途
beforeSend	发送前	✅ 可通过 return false 取消	设置头、验证、显示加载
success	成功（2xx）	❌ 不可取消	更新 UI、处理数据
error	失败（网络/4xx/5xx）	❌ 不可取消	错误提示、日志
complete	结束（成功或失败）	❌ 不可取消	隐藏加载、清理
statusCode	按状态码	❌ 不可取消	精细化错误处理

---

一句话终极解释

$.ajax 的回调就像一场舞台剧的流程控制：

• beforeSend → 开幕前准备道具（设置头）
• success → 演出成功，观众鼓掌（更新页面）
• error → 演出失败，主持人救场（报错提示）
• complete → 谢幕，收拾舞台（隐藏加载）
• statusCode → 按剧本分支处理不同结局