API 请求工具与封装
目录
简介
lmes-web-base 项目中的 API 请求工具层是一个高度封装的 axios 实例，提供了完整的 HTTP 请求解决方案。该工具层不仅负责基础的网络通信，还集成了权限验证、状态管理、错误处理、加载状态等多个高级功能，为整个应用提供了统一且强大的 API 访问能力。
核心特性包括：
- 自动化的 Authorization 头注入
- Content-Type 标准化处理
- 环境适配的 baseURL 配置
- 携带凭据（withCredentials）支持
- 请求拦截器集成权限校验与加载状态管理
- 响应拦截器统一处理各种错误场景
- 支持取消请求（CancelToken）
- 数据预处理与转换机制
- 国际化错误消息支持
项目架构概览
图表来源
核心请求工具分析
axios 实例配置
// baseURL 环境适配
let baseURL = ''
const params = new URLSearchParams(location.search)
baseURL = baseURL || params.get('baseURL') || ''
console.info('[baseURL]', baseURL)
// axios 实例创建
const service = axios.create({
baseURL,
headers: {},
})
核心配置特点：
- 动态 baseURL 适配：支持通过 URL 参数传递 baseURL，实现多环境部署
- 默认配置简化：移除了超时时间等硬编码配置，保持灵活性
- 空 headers 初始化：避免默认值干扰自定义配置
请求头自动化管理
function appendHeaders(headers = {}) {
function withDefaultHeaders(headers: Record<string, any>) {
const token = Session.get('Token')
const defaultHeaders = {
'Content-Type': 'application/json;charset=UTF-8',
'X-Project': Session.get('X-Project'),
'X-Client-Id': localStorage.getItem('clientId'),
get Authorization() {
return token ? `Bearer ${token}` : undefined
},
get environment() {
return window.app.running ? 'runningtime' : undefined
},
get ['Accept-Language']() {
try {
return Language.getLangReqHeader()
} catch (error) {
return undefined
}
},
}
return Object.assign({}, defaultHeaders, headers)
}
return withDefaultHeaders(headers)
}
节来源
拦截器链详解
请求拦截器流程
图表来源
请求拦截器的核心职责：
- 加载状态管理：通过计数器控制全局加载指示器
- 请求头标准化：自动注入必要的认证和项目标识信息
- 数据格式化：确保 JSON 数据正确序列化
- 静默模式支持：允许禁用加载状态和错误提示
响应拦截器处理流程
图表来源
节来源
权限与状态管理集成
权限系统集成
图表来源
存储系统协作
// 本地存储封装
const Local = {
set(key: string, val: any) {
window.localStorage.setItem(key, JSON.stringify(val))
},
get(key: string) {
const value: null | string = window.localStorage.getItem(key) || null
if (!value) return null
return JSON.parse(value)
},
// ... 其他方法
}
// 会话存储封装
const Session = {
set(key: string, val: any) {
window.sessionStorage.setItem(key, JSON.stringify(val))
},
get(key: string) {
const value: null | string = window.sessionStorage.getItem(key)
try {
if (!value) return null
return JSON.parse(value)
} catch (error) {
return value
}
},
// ... 其他方法
}
节来源
错误处理机制
多层次错误处理
-
认证错误处理
- 401/403 状态码自动检测
- 重新登录弹窗机制
- 静默模式下的错误抑制
-
业务错误处理
- 统一错误消息提取
- 国际化错误提示
- 文件下载错误特殊处理
-
网络错误处理
- 超时、断网等网络异常
- 取消请求处理
- 代理接口不存在检测
错误消息国际化
const message =
data?.msg ||
data?.message ||
data?.title ||
data ||
statusText ||
msg ||
'请求出错'
const loginMessage = {
'401': Language._t('登录已失效'),
'403': Language._t('禁止访问'),
}[status]
节来源
性能优化策略
加载状态优化
// 智能加载状态管理
let reqNum: number = 0
let loadingInstance: LoadingInstance
let lastClickTime = Date.now()
const setLoading = (silent: boolean) => {
if (silent) return
reqNum++
if (reqNum === 1) {
loadingInstance = ElLoading.service({
...loadingOptions,
customClass: `${loadingOptions.customClass} ${
Date.now() - lastClickTime < 16 ? 'locked' : ''
}`,
})
}
}
const closeLoading = (silent: boolean) => {
if (silent) return
reqNum--
if (reqNum <= 0) {
reqNum = 0
loadingInstance && loadingInstance.close()
}
}
请求合并与缓存策略
虽然当前实现主要关注单个请求处理，但可以通过以下方式扩展：
- 请求去重：基于 URL 和参数的唯一性判断
- 响应缓存：针对 GET 请求的智能缓存机制
- 批量请求：支持多个请求的并发处理
节来源
使用示例与最佳实践
基础 API 调用
// 项目配置获取
export const getProjectConfig = (name: string) => {
return request.get(`/projectApi/env?name=${name}`)
}
// 组件创建
export const createWidget = (data) => {
return request.post(`/projectApi/create`, data)
}
高级配置使用
// 静默请求（不显示加载状态）
await request.get('/api/status', { silent: true })
// 静默错误（不显示错误提示）
await request.get('/api/check', { unLogError: true })
// 文件上传
export const postImport = (file: FormData) => {
return request({
url: `/api/v1/zc/productsop/uploadsop`,
method: 'post',
contentType: 'multipart/form-data',
headers: { accept: '*/*' },
data: file,
})
}
最佳实践建议
- 合理使用静默模式：对于后台任务或用户体验要求高的场景
- 错误处理策略：根据业务需求选择合适的错误处理方式
- 请求配置复用：通过继承和组合减少重复配置
- 性能监控：利用拦截器记录请求性能指标
节来源
故障排除指南
常见问题诊断
-
认证失败
- 检查 Token 是否有效
- 验证 Authorization 头是否正确注入
- 确认用户会话状态
-
请求超时
- 检查网络连接状态
- 验证服务器响应时间
- 考虑增加超时配置
-
跨域问题
- 确认 CORS 配置
- 检查代理设置
- 验证域名匹配规则
-
加载状态异常
- 检查请求计数器逻辑
- 验证异步请求的正确关闭
- 确认 Element Plus 加载组件配置
调试技巧
// 启用详细日志
console.log('[Request Config]', config)
console.log('[Response Data]', response.data)
// 错误追踪
const reason = new Error(`Request Error ${status} ${method} ${url}`)
return Promise.reject(reason)
总结
lmes-web-base 的 API 请求工具层展现了现代前端应用中 HTTP 请求处理的最佳实践。通过高度抽象和模块化的设计，它成功地将复杂的网络通信逻辑封装成简洁易用的接口，同时保持了足够的灵活性以适应不同的业务需求。
核心优势
- 统一的错误处理：通过响应拦截器实现了一致的错误处理策略
- 智能化的加载管理：基于请求计数的全局加载状态控制
- 完善的权限集成：与权限管理系统无缝对接
- 国际化支持：完整的多语言错误消息处理
- 可扩展性设计：清晰的架构便于功能扩展
技术亮点
- 拦截器链模式：实现了请求和响应的统一处理
- 动态配置机制：支持运行时的灵活配置调整
- 状态管理集成：与 Vue 状态管理系统的深度整合
- 性能优化考虑：智能的加载状态管理和资源释放
这个 API 请求工具层不仅满足了当前项目的功能需求，更为未来的功能扩展和技术演进奠定了坚实的基础。通过持续的优化和改进，它将继续为整个应用提供稳定可靠的网络通信能力。