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 期望返回 JSONsuccess: 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 中没有匹配的状态码，才会走 erroralert('未知错误:', 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 → 按剧本分支处理不同结局