admin-ui/docs/API-ERROR-HANDLING.md

API 错误处理规范

本文档定义了项目中 API 请求的错误处理标准，确保错误提示的一致性和用户体验。

📋 目录

• 核心原则
• 全局拦截器机制
• API 层规范
• 页面层规范
• 完整示例
• 常见问题

---

核心原则

✅ 避免重复提示

• 全局拦截器已经处理了大部分错误提示
• 页面层不应再显示固定的错误提示
• 只在需要自定义错误处理时使用 errorMode: 'page'

✅ 优先使用后端 message

• 全局拦截器会自动提取后端返回的 message 字段
• 页面层使用 getApiErrorMessage 工具函数提取错误信息
• 避免写死前端错误文案

✅ 业务逻辑与错误提示分离

• catch 块只处理必要的业务逻辑（数据清空、状态重置等）
• 错误提示交给全局拦截器或使用 getApiErrorMessage

---

全局拦截器机制

位置

src/utils/request.ts

错误处理流程

// 响应拦截器
service.interceptors.response.use(
  (response) => {
    const res = response.data;
    const code = res.code;
    
    // 业务成功
    if (code === 200 || code === 0) {
      return res;
    }
    
    // 业务失败
    const errorMode = response.config.requestOptions?.errorMode || 'global';
    
    if (errorMode === 'global') {
      // 全局模式：自动显示后端 message
      ElMessage.error(res.message || res.msg || '操作失败');
    }
    
    // 抛出错误供页面 catch
    return Promise.reject(new Error(res.message || res.msg));
  },
  (error) => {
    // 网络错误、超时等
    ElMessage.error('网络请求失败，请稍后重试');
    return Promise.reject(error);
  }
);

错误模式

模式	说明	使用场景
global（默认）	全局拦截器自动显示错误	大部分接口（推荐）
page	页面自己处理错误	需要自定义错误处理时

---

API 层规范

1. 默认配置（推荐 95% 的场景）

// src/api/xxx/index.ts

/**
 * 获取列表
 * 使用默认配置，全局拦截器自动处理错误
 */
export function getList(params: ListParams) {
  return request({
    url: '/api/xxx/list',
    method: 'get',
    params
  });
}

/**
 * 创建数据
 * 使用默认配置
 */
export function createItem(data: CreateParams) {
  return request({
    url: '/api/xxx/create',
    method: 'post',
    data
  });
}

/**
 * 更新数据
 * 使用默认配置
 */
export function updateItem(data: UpdateParams) {
  return request({
    url: '/api/xxx/update',
    method: 'put',
    data
  });
}

/**
 * 删除数据
 * 使用默认配置
 */
export function deleteItem(id: string) {
  return request({
    url: `/api/xxx/delete/${id}`,
    method: 'delete'
  });
}

2. 页面自定义错误处理（特殊场景）

// src/api/xxx/index.ts

/**
 * 批量导入
 * 需要页面自定义错误处理（显示详细的导入结果）
 */
export function batchImport(data: ImportParams) {
  return request({
    url: '/api/xxx/import',
    method: 'post',
    data,
    requestOptions: { 
      errorMode: 'page' // 页面自己处理错误
    }
  });
}

/**
 * 复杂表单提交
 * 需要根据不同错误类型做不同处理
 */
export function submitComplexForm(data: FormData) {
  return request({
    url: '/api/xxx/submit',
    method: 'post',
    data,
    requestOptions: { 
      errorMode: 'page' 
    }
  });
}

3. 何时使用 errorMode: 'page'？

仅在以下情况使用：

• ✅ 需要根据不同错误码做不同处理
• ✅ 需要自定义错误提示格式
• ✅ 需要在错误后执行特殊业务逻辑
• ✅ 需要显示详细的错误信息（如批量操作结果）

---

页面层规范

1. 默认场景 - 全局错误处理

// ✅ 推荐写法
const getList = async () => {
  loading.value = true;
  try {
    const res = await listApi(params);
    tableData.value = res.data?.list || [];
    total.value = res.data?.total || 0;
  } catch (error) {
    // 错误已由全局拦截器处理
    // 这里只处理必要的业务逻辑
    tableData.value = [];
    total.value = 0;
  } finally {
    loading.value = false;
  }
};

// ✅ 简单场景可以不写 catch
const deleteItem = async (id: string) => {
  try {
    await deleteApi(id);
    ElMessage.success('删除成功');
    getList(); // 刷新列表
  } catch (error) {
    // 错误已由全局拦截器处理
  }
};

// ✅ 更简洁的写法（如果不需要处理错误）
const deleteItem = async (id: string) => {
  await deleteApi(id);
  ElMessage.success('删除成功');
  getList();
};

2. 页面自定义错误处理

import { getApiErrorMessage } from '/@/utils/request';

// ⚠️ 仅在 API 设置了 errorMode: 'page' 时使用
const saveData = async () => {
  loading.value = true;
  try {
    await saveApi(formData);
    ElMessage.success('保存成功');
    closeDialog();
  } catch (error) {
    // 使用 getApiErrorMessage 提取后端错误信息
    ElMessage.error(getApiErrorMessage(error, '保存失败'));
  } finally {
    loading.value = false;
  }
};

// 根据不同错误做不同处理
const deleteItem = async (id: string) => {
  try {
    await deleteApi(id);
    ElMessage.success('删除成功');
    getList();
  } catch (error) {
    const msg = getApiErrorMessage(error, '删除失败');
    
    // 根据错误信息做不同处理
    if (msg.includes('被引用')) {
      ElMessage.warning('该数据已被其他数据引用，无法删除');
      showRelatedData(id);
    } else if (msg.includes('权限')) {
      ElMessage.error('您没有删除权限');
    } else {
      ElMessage.error(msg);
    }
  }
};

// 批量操作显示详细结果
const batchImport = async (file: File) => {
  try {
    const res = await importApi(file);
    ElMessage.success(`导入成功 ${res.data.successCount} 条，失败 ${res.data.failCount} 条`);
    if (res.data.failCount > 0) {
      showFailDetails(res.data.failList);
    }
  } catch (error) {
    ElMessage.error(getApiErrorMessage(error, '导入失败'));
  }
};

3. getApiErrorMessage 工具函数

/**
 * 从错误对象中提取错误信息
 * @param error - 错误对象
 * @param fallback - 默认错误信息
 * @returns 错误信息字符串
 */
export function getApiErrorMessage(error: any, fallback: string = '操作失败'): string {
  // 优先从 response.data 中获取
  if (error?.response?.data?.message) {
    return error.response.data.message;
  }
  if (error?.response?.data?.msg) {
    return error.response.data.msg;
  }
  
  // 从 Error.message 中获取
  if (error?.message && error.message !== 'Network Error') {
    return error.message;
  }
  
  // 返回默认值
  return fallback;
}

使用示例：

import { getApiErrorMessage } from '/@/utils/request';

try {
  await someApi();
} catch (error) {
  // 使用后端返回的 message，如果没有则显示 '操作失败'
  ElMessage.error(getApiErrorMessage(error, '操作失败'));
}

---

完整示例

示例 1：标准 CRUD 操作

// ==================== API 层 ====================
// src/api/user/index.ts

export function getUserList(params: ListParams) {
  return request({
    url: '/api/user/list',
    method: 'get',
    params
  });
}

export function createUser(data: UserForm) {
  return request({
    url: '/api/user/create',
    method: 'post',
    data
  });
}

export function updateUser(data: UserForm) {
  return request({
    url: '/api/user/update',
    method: 'put',
    data
  });
}

export function deleteUser(id: string) {
  return request({
    url: `/api/user/delete/${id}`,
    method: 'delete'
  });
}

// ==================== 页面层 ====================
// src/views/user/index.vue

import { getUserList, createUser, updateUser, deleteUser } from '/@/api/user';

// 获取列表
const getList = async () => {
  loading.value = true;
  try {
    const res = await getUserList(queryParams);
    tableData.value = res.data?.list || [];
    total.value = res.data?.total || 0;
  } catch (error) {
    // 错误已由全局拦截器处理
    tableData.value = [];
    total.value = 0;
  } finally {
    loading.value = false;
  }
};

// 新增/编辑
const onSubmit = async () => {
  try {
    await formRef.value?.validate();
    
    if (isEdit.value) {
      await updateUser(formData);
      ElMessage.success('修改成功');
    } else {
      await createUser(formData);
      ElMessage.success('添加成功');
    }
    
    dialogVisible.value = false;
    getList();
  } catch (error) {
    // 错误已由全局拦截器处理
  }
};

// 删除
const onDelete = async (row: User) => {
  try {
    await ElMessageBox.confirm(`确定要删除用户"${row.name}"吗？`, '提示', {
      type: 'warning'
    });
    
    await deleteUser(row.id);
    ElMessage.success('删除成功');
    getList();
  } catch (error) {
    if (error === 'cancel') {
      // 用户取消操作
      return;
    }
    // 错误已由全局拦截器处理
  }
};

示例 2：需要自定义错误处理

// ==================== API 层 ====================
// src/api/model/index.ts

export function listModel(params: ListParams) {
  return request({
    url: '/api/model/list',
    method: 'get',
    params,
    requestOptions: { errorMode: 'page' } // 页面自己处理错误
  });
}

export function createModel(data: ModelForm) {
  return request({
    url: '/api/model/create',
    method: 'post',
    data,
    requestOptions: { errorMode: 'page' }
  });
}

// ==================== 页面层 ====================
// src/views/model/index.vue

import { getApiErrorMessage } from '/@/utils/request';
import { listModel, createModel } from '/@/api/model';

// 获取列表
const getList = async () => {
  loading.value = true;
  try {
    const res = await listModel(queryParams);
    tableData.value = res.data?.list || [];
    total.value = res.data?.total || 0;
  } catch (error) {
    // 使用 getApiErrorMessage 提取后端错误
    ElMessage.error(getApiErrorMessage(error, '获取列表失败'));
    tableData.value = [];
    total.value = 0;
  } finally {
    loading.value = false;
  }
};

// 创建
const onCreate = async () => {
  try {
    await createModel(formData);
    ElMessage.success('创建成功');
    dialogVisible.value = false;
    getList();
  } catch (error) {
    // 使用 getApiErrorMessage 提取后端错误
    ElMessage.error(getApiErrorMessage(error, '创建失败'));
  }
};

---

常见问题

Q1: 什么时候使用 errorMode: 'page'？

A: 仅在以下情况使用：

• 需要根据不同错误码做不同处理
• 需要自定义错误提示格式
• 需要在错误后执行特殊业务逻辑
• 需要显示详细的错误信息

大部分情况（95%）使用默认的全局错误处理即可。

---

Q2: 为什么不能在页面写固定的错误提示？

A: 因为全局拦截器已经显示了错误，页面再显示会导致重复提示：

// ❌ 错误写法 - 会重复提示
try {
  await getList();
} catch (error) {
  ElMessage.error('获取列表失败'); // 全局拦截器已经显示过了
}

// ✅ 正确写法
try {
  await getList();
} catch (error) {
  // 错误已由全局拦截器处理
  tableData.value = [];
}

---

Q3: 如何显示后端返回的错误信息？

A: 有两种方式：

1. 使用默认全局处理（推荐）

// API 层不设置 errorMode
export function getList() {
  return request({ url: '/api/list', method: 'get' });
}

// 页面层不写错误提示
try {
  await getList();
} catch (error) {
  // 全局拦截器会自动显示后端的 message
}

2. 使用 getApiErrorMessage

// API 层设置 errorMode: 'page'
export function getList() {
  return request({ 
    url: '/api/list', 
    method: 'get',
    requestOptions: { errorMode: 'page' }
  });
}

// 页面层使用 getApiErrorMessage
import { getApiErrorMessage } from '/@/utils/request';

try {
  await getList();
} catch (error) {
  ElMessage.error(getApiErrorMessage(error, '获取列表失败'));
}

---

Q4: catch 块应该写什么？

A: 根据场景决定：

// 场景 1：只需要清空数据
try {
  const res = await getList();
  tableData.value = res.data?.list || [];
} catch (error) {
  // 错误已由全局拦截器处理
  tableData.value = [];
}

// 场景 2：需要重置状态
try {
  await uploadFile(file);
} catch (error) {
  // 错误已由全局拦截器处理
  resetUploadState();
  fileList.value = [];
}

// 场景 3：不需要任何处理
try {
  await deleteItem(id);
  ElMessage.success('删除成功');
  getList();
} catch (error) {
  // 错误已由全局拦截器处理
}

// 场景 4：需要自定义错误处理（API 设置了 errorMode: 'page'）
try {
  await saveData();
  ElMessage.success('保存成功');
} catch (error) {
  ElMessage.error(getApiErrorMessage(error, '保存失败'));
}

---

Q5: 如何处理用户取消操作？

A: 使用 if (error === 'cancel') 判断：

const onDelete = async (row: any) => {
  try {
    await ElMessageBox.confirm('确定要删除吗？', '提示', {
      type: 'warning'
    });
    
    await deleteApi(row.id);
    ElMessage.success('删除成功');
    getList();
  } catch (error) {
    if (error === 'cancel') {
      // 用户取消操作，不显示错误
      return;
    }
    // 其他错误已由全局拦截器处理
  }
};

---

Q6: 如何处理表单验证失败？

A: 表单验证失败不会进入 catch，无需特殊处理：

const onSubmit = async () => {
  try {
    // 表单验证失败会直接 return，不会进入 catch
    await formRef.value?.validate();
    
    await saveApi(formData);
    ElMessage.success('保存成功');
  } catch (error) {
    // 这里只会捕获 API 请求错误
    // 错误已由全局拦截器处理
  }
};

---

快速检查清单

写新接口时，检查以下几点：

• API 层：是否需要设置 errorMode: 'page'？

  • 大部分情况不需要
  • 只在需要自定义错误处理时设置

• 页面层：catch 块是否正确？

  • ✅ 只处理业务逻辑（数据清空、状态重置）
  • ❌ 不写固定的 ElMessage.error('xxx失败')
  • ✅ 如果 API 设置了 errorMode: 'page'，使用 getApiErrorMessage

• 是否避免了重复提示？

  • ✅ 全局拦截器 OR 页面 getApiErrorMessage
  • ❌ 全局拦截器 + 页面固定提示

---

工具函数导入

// 导入错误提取工具
import { getApiErrorMessage } from '/@/utils/request';

// 使用示例
try {
  await someApi();
} catch (error) {
  ElMessage.error(getApiErrorMessage(error, '操作失败'));
}

---

总结

核心规则

1. 默认使用全局错误处理（95% 的场景）

   • API 层不设置 errorMode
   • 页面层 catch 不写固定错误提示

2. 特殊场景使用页面自定义处理（5% 的场景）

   • API 层设置 errorMode: 'page'
   • 页面层使用 getApiErrorMessage

3. 避免重复提示

   • 全局拦截器已经处理了错误
   • 页面不要再显示固定错误

记住这个公式

全局错误处理（默认） = 不设置 errorMode + catch 不写错误提示
页面自定义处理（特殊） = errorMode: 'page' + getApiErrorMessage

---

文档版本： v1.0
最后更新： 2026-05-11
维护者： 开发团队