$.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→ 按剧本分支处理不同结局