bun + vite7 的结合，孕育的 Robot Admin 【靓仔出道】（十一）

Robot_Admin API集成指南：构建优雅的前端API层

阅读时间： 8分钟难度等级：进阶适用框架： Vue3 + TypeScript + Axios

Robot_Admin项目采用结构化方法实现API集成，使用Axios实现与后端服务的无缝通信。本文档解释了API调用的组织方式、如何与端点交互以及扩展API层的最佳实践。

🏗️ 架构概览

Robot_Admin中的API集成遵循模块化架构，分离关注点并提高可维护性。系统基于定制的Axios实例构建，包含请求/响应拦截器，用于处理常见的任务，如认证和错误管理。

核心优势

这种架构提供了多项优势：

关注点分离：API调用按领域/功能分组
可重用性：通用请求配置集中处理
一致的错误处理：所有API调用的集中错误管理
认证：受保护端点的自动令牌管理

⚙️ HTTP客户端配置

项目使用在request.ts中定义的自定义Axios配置，作为所有API调用的基础。

php 复制代码

// 基本配置
const service = axios.create({
  baseURL: VITE_API_BASE || '',
  timeout: 5000,
  headers: {
    'Content-Type': 'application/json',
  },
})

API基础URL从环境变量中加载，便于在开发、测试和生产环境之间切换。

🔐 认证处理

Axios请求拦截器自动将认证令牌注入API请求中。这简化了制作认证请求的过程，开发者无需手动为每个调用添加令牌。

javascript 复制代码

// 请求拦截器
service.interceptors.request.use(
  config => {
    const { token, logout } = s_userStore()
    if (token) {
      if (d_isCheckTimeout()) {
        logout()
        return Promise.reject(new Error('令牌已过期，请重新登录'))
      }
      config.headers.Authorization = `Bearer ${token}` // 注意空格
    }
    return config
  },
  error => Promise.reject(error)
)

拦截器功能

从用户存储中检索认证令牌
检查令牌是否过期
如果有效，将令牌作为Bearer令牌添加到Authorization头部
如果过期，登出用户并拒绝请求

❌ 错误处理

API错误通过响应拦截器集中管理，处理常见的错误场景，如认证失败（401错误），并提供一致的用户体验。

go 复制代码

// 响应拦截器
service.interceptors.response.use(
  response => {
    // 仅返回业务数据，业务层直接取数据
    if (response.status === 200) return response
    message.error('接口调用失败')
    return Promise.reject(new Error(response.statusText || '接口请求失败'))
  },
  error => {
    const { logout } = s_userStore()
    if (error?.response?.status === 401) {
      logout()
      message.error('登录已过期，请重新登录')
    } else {
      message.error(error.message || '响应拦截请求失败')
    }
    return Promise.reject(error)
  }
)

集中错误处理优势

自动显示用户友好的错误信息
通过登出用户处理认证过期
标准化应用中的错误处理

📁 API模块组织

API调用按领域组织到src/api目录中的特定模块中。每个文件将特定功能或实体的相关端点分组：

模块	描述	示例端点
user.ts	用户认证	feature(), chapter()
permission.ts	权限管理	permissionList()
role.ts	角色管理	roleList(), rolePermission(), distributePermission()
user-manage.ts	用户管理	getUserMangeList(), deleteUser(), userRoles()

这种组织方式便于查找和维护与特定功能相关的API调用，提高代码的可维护性和可发现性。

🔄 进行API调用

基本GET请求

最简单的API调用形式是无参数的GET请求：

javascript 复制代码

export const permissionList = () => {
  return request({
    url: '/permission/list',
  })
}

调用此函数时，将向/permission/list发送GET请求，并附带认证令牌（如果可用）。

带查询参数的GET请求

对于需要查询参数的端点：

csharp 复制代码

export const getUserMangeList = params => {
  return request({
    url: '/user-manage/list',
    params,
  })
}

params对象将自动序列化并附加到URL作为查询参数。

带路径参数的GET请求

对于包含路径参数的端点：

typescript 复制代码

export const userDetail = (id: string) => {
  return request({
    url: `/user-manage/detail/${id}`,
  })
}

路径参数直接使用模板字面量嵌入URL中。

带数据负载的POST请求

对于需要发送请求体数据的端点：

javascript 复制代码

export const updateRole = (id, roles) => {
  return request({
    url: `/user-manage/update-role/${id}`,
    method: 'POST',
    data: {
      roles,
    },
  })
}

data对象将自动序列化为JSON并放入请求体中。

🎯 在组件中使用API调用

在组件或存储中使用这些API函数：

从适当的模块导入API函数
调用函数并处理Promise响应

javascript 复制代码

// 在组件或可组合函数中
import { getUserMangeList } from '@/api/user-manage'
 
const fetchUsers = async () => {
  try {
    const response = await getUserMangeList({ page: 1, limit: 10 })
    // 处理成功响应
    console.log(response.data)
  } catch (error) {
    // 错误已由拦截器处理，但可以添加自定义处理
    console.error('获取用户失败：', error)
  }
}

🚀 扩展API层的最佳实践

添加新的API端点时，遵循以下最佳实践：

分组相关端点：将相关API函数放在同一模块文件中
使用描述性名称：函数名称应清晰表明其用途
文档化端点：为每个API函数添加JSDoc注释
类型参数：尽可能使用TypeScript类型定义函数参数
一致的模式：遵循为类似端点建立的模式

添加新API函数的示例

php 复制代码

/**
 * @description: 创建新用户
 */
export const createUser = (userData) => {
  return request({
    url: '/user-manage/create',
    method: 'POST',
    data: userData,
  })
}

🛠️ 组件中的API错误处理

虽然全局拦截器处理常见错误，但特定情况可能需要自定义错误处理：

javascript 复制代码

import { deleteUser } from '@/api/user-manage'
 
const handleDeleteUser = async (id) => {
  try {
    await deleteUser(id)
    // 成功处理 - 例如，更新本地状态
    userList.value = userList.value.filter(user => user.id !== id)
  } catch (error) {
    // 自定义错误处理
    if (error.response?.status === 403) {
      // 特定处理禁止错误
      console.error('您没有权限删除用户')
    }
    // 无需显示通用错误信息，拦截器已处理
  }
}

📝 总结

Robot_Admin中的API集成系统为与后端服务的通信提供了坚实的基础。通过利用集中的Axios配置和遵循已建立的API调用组织模式，您可以高效地添加与后端交互的新功能，同时保持代码的整洁和可维护性。

请记住，认证系统自动处理令牌管理，因此只要用户正确认证，大多数API调用将无需额外配置即可与受保护端点工作。

关键要点：

✅ 使用拦截器实现认证和错误的统一处理
✅ 按功能域组织API模块，提高可维护性
✅ 遵循一致的命名和结构模式
✅ 适当使用TypeScript增强类型安全

如果这篇文章对你有帮助，欢迎点赞收藏！有问题可以在评论区讨论。

期待共建！

如果这套组件系统对你的开发工作有所启发或帮助，请不要吝啬你的 Star！每一个 ⭐ 都是对我最大的鼓励和支持。

👉 点击这里 Star 支持项目（🧧行大运摸大票💰）

🔗 探索更多资源

📋 资源类型	🔗 链接	📝 说明
🎯 在线预览	robotadmin.cn	体验完整功能演示
📚 详细文档	tzagileteam.com	深入了解实现细节
💻 源码仓库	https:/github.com/ChenyCHENYU/Robot_Admin	获取完整源代码

非常期待听到你的想法！