简体中文

English
日本語

简体中文

English
日本語

VJSP Vue3 框架 API 文档 ​

概述 ​

VJSP Vue3 框架提供了一套完整的接口管理和请求封装机制，支持企业级中后台应用的开发需求。框架基于 Axios 进行深度封装，提供了统一的请求管理、错误处理、安全防护和性能优化功能。

1. 接口管理和请求封装机制 ​

1.1 请求封装架构 ​

框架采用分层架构设计，将请求处理分为多个层次：

  • Axios 实例层 [axios/service.ts]: 配置基础请求实例，包含请求重试、取消等核心功能
  • 拦截器层 [axios/config.ts]: 处理请求/响应拦截，实现统一错误处理和业务状态码解析
  • API 服务层 [axios/index.ts]: 业务接口封装，提供统一的请求方法调用接口
  • 类型定义层 [types/api]: TypeScript 类型支持，确保类型安全

1.2 核心请求封装 ​

框架提供统一的请求封装机制，支持 GET、POST、PUT、DELETE 等 HTTP 方法：

请求方法使用机制 ​

框架提供统一的HTTP请求封装机制，支持标准HTTP方法调用：

请求方法支持机制：

  1. GET请求机制：支持查询参数传递，自动处理URL编码和参数序列化
  2. POST请求机制：支持请求体数据传递，自动处理JSON序列化和内容类型设置
  3. PUT请求机制：支持资源更新操作，提供完整的数据更新功能
  4. DELETE请求机制：支持资源删除操作，提供安全的删除确认机制

请求处理流程：

  1. 请求预处理：自动添加认证令牌、设置请求头、处理参数序列化
  2. 请求发送：通过底层HTTP客户端发送请求到服务器
  3. 响应处理：统一处理响应数据、状态码验证、错误拦截
  4. 结果返回：返回格式化后的响应数据，包含业务状态码和数据内容

核心特性说明 ​

  1. 安全机制

    • 自动频率限制：防止API请求过于频繁
    • CSRF防护：对敏感操作进行跨站请求伪造保护
    • Token自动注入：请求时自动携带用户认证令牌

  2. 错误处理

    • 统一错误拦截：自动处理网络错误和业务错误
    • 友好提示：使用消息管理器展示错误信息
    • 重试机制：对失败请求进行自动重试

  3. 功能支持

    • 请求取消：支持取消正在进行的请求
    • 文件上传：支持multipart/form-data格式
    • 类型安全：完整的TypeScript类型支持

1.3 业务状态码体系 ​

框架定义了一套完整的业务状态码体系，用于统一处理各种业务场景。状态码定义位于 src/constants/index.ts 文件中。

核心状态码定义 ​

  • SUCCESS_CODE = 'A0000': 请求成功
  • RATE_LIMIT_ERROR_CODE = 'A0006': 频率限制错误
  • CSRF_VALIDATION_ERROR_CODE = 'A0007': CSRF验证失败

状态码处理机制 ​

框架通过统一的错误处理机制处理各种业务状态码，确保应用在不同场景下都能提供良好的用户体验。

状态码处理流程：

  1. 状态码识别：根据响应中的业务状态码识别请求结果
  2. 错误分类处理：将状态码分为成功、警告、错误等不同类别
  3. 用户提示展示：通过消息管理器展示适当的用户提示信息
  4. 业务逻辑处理：根据状态码执行相应的业务逻辑

核心状态码处理策略：

  • 成功状态码（A0000）：正常返回数据，继续后续业务逻辑
  • 认证相关错误码：自动跳转到登录页面，清理用户会话信息
  • 权限相关错误码：显示权限不足提示，限制相关操作
  • 业务逻辑错误码：显示具体的错误信息，指导用户正确操作
  • 系统保护错误码：展示系统保护提示，防止恶意请求

1.4 类型安全支持 ​

框架提供完整的 TypeScript 类型安全支持，确保开发过程中的类型安全性和代码质量。

类型定义机制 ​

  • 模块化类型定义：每个业务模块都有独立的类型定义文件
  • 请求/响应类型：为每个API接口定义完整的请求参数和响应数据类型
  • 业务实体类型：定义用户、角色、菜单等业务实体的数据结构

类型安全特性 ​

  1. 编译时类型检查：在开发阶段捕获类型错误
  2. 智能代码提示：IDE提供完整的类型提示和自动补全
  3. 接口契约保障：确保前后端接口数据格式的一致性
  4. 重构安全性：类型系统帮助安全地进行代码重构

类型安全机制 ​

框架通过完整的TypeScript类型系统提供编译时类型安全保障：

类型安全机制特性：

  1. 接口契约保障：通过类型定义确保前后端接口数据格式的一致性
  2. 编译时检查：在开发阶段捕获类型错误，避免运行时异常
  3. 智能提示支持：IDE提供完整的类型提示和自动补全功能
  4. 重构安全性：类型系统帮助安全地进行代码重构和模块维护

类型安全实现机制：

  1. 模块化类型定义：每个业务模块都有独立的类型定义文件
  2. 请求/响应类型映射：为每个API接口定义完整的请求参数和响应数据类型
  3. 业务实体类型化：定义用户、角色、菜单等业务实体的数据结构
  4. 类型推导机制：自动推导API调用的参数类型和返回值类型

2. 业务模块开发指南 ​

2.1 开发新API模块 ​

步骤1: 创建类型定义 ​

typescript
// src/types/api/module/product.d.ts
export interface ProductItem {
  id: string
  name: string
  price: number
  stock: number
  status: number
  category: string
  createTime: string
}

export interface ProductListRequest {
  pageNum: number
  pageSize: number
  name?: string
  category?: string
  status?: number
}

export interface ProductListResponse {
  list: ProductItem[]
  total: number
}

步骤2: 创建API服务 ​

typescript
// src/api/product/index.ts
import request from '@/axios'
import type {
  ProductItem,
  ProductListRequest,
  ProductListResponse,
} from '@/types/api/module/product'

/**
 * 获取产品列表
 * @param params
 * @returns
 */
export function getProductListApi(params: ProductListRequest) {
  return request.get({
    url: '/modules/product',
    params,
  })
}

/**
 * 新增产品
 * @param data
 * @returns
 */
export function addProductApi(data: ProductItem) {
  return request.post({
    url: '/modules/product',
    data,
  })
}

/**
 * 删除产品
 * @param id
 * @returns
 */
export function deleteProductApi(id: string) {
  return request.delete({
    url: `/modules/product/${id}`,
  })
}

/**
 * 批量删除产品
 * @param ids
 * @returns
 */
export function batchDeleteProductApi(ids: string[]) {
  return request.delete({
    url: '/modules/product/batchRemove',
    data: ids,
  })
}

/**
 * 查询产品详情
 * @param id
 * @returns
 */
export function getProductApi(id: string) {
  return request.get<ProductItem>({
    url: `/modules/product/${id}`,
  })
}

/**
 * 修改产品
 * @param data
 * @returns
 */
export function updateProductApi(data: ProductItem) {
  return request.put({
    url: `/modules/product/${data.id}`,
    data,
  })
}

2.2 在组件中使用API ​

基础用法 ​

html
<template>
  <div>
    <el-table :data="productList" v-loading="loading">
      <el-table-column prop="name" label="产品名称" />
      <el-table-column prop="price" label="价格" />
      <el-table-column prop="stock" label="库存" />
    </el-table>

    <el-pagination
      v-model:current-page="currentPage"
      v-model:page-size="pageSize"
      :total="total"
      @current-change="handlePageChange"
    />
  </div>
</template>

<script setup lang="ts">
  import { ref, onMounted } from 'vue'
  import { getProductListApi } from '@/api/product'
  import type { ProductItem, ProductListRequest } from '@/types/api/module/product'

  const productList = ref<ProductItem[]>([])
  const loading = ref(false)
  const currentPage = ref(1)
  const pageSize = ref(10)
  const total = ref(0)

  // 加载产品列表
  const loadProductList = async () => {
    loading.value = true
    try {
      const response = await getProductListApi({
        pageNum: currentPage.value,
        pageSize: pageSize.value,
      })
      productList.value = response.data.list
      total.value = response.data.total
    } catch (error) {
      console.error('加载产品列表失败:', error)
    } finally {
      loading.value = false
    }
  }

  // 分页处理
  const handlePageChange = (page: number) => {
    currentPage.value = page
    loadProductList()
  }

  onMounted(() => {
    loadProductList()
  })
</script>

使用组合式API封装 ​

typescript
// composables/useProduct.ts
import { ref, computed } from 'vue'
import { getProductListApi, addProductApi, updateProductApi, deleteProductApi } from '@/api/product'
import type { ProductItem, ProductListRequest } from '@/types/api/module/product'

export function useProduct() {
  const productList = ref<ProductItem[]>([])
  const loading = ref(false)
  const currentPage = ref(1)
  const pageSize = ref(10)
  const total = ref(0)

  // 计算属性
  const hasMore = computed(() => {
    return currentPage.value * pageSize.value < total.value
  })

  // 加载产品列表
  const loadProductList = async (params?: Partial<ProductListRequest>) => {
    loading.value = true
    try {
      const response = await getProductListApi({
        pageNum: currentPage.value,
        pageSize: pageSize.value,
        ...params,
      })
      productList.value = response.data.list
      total.value = response.data.total
    } catch (error) {
      console.error('加载产品列表失败:', error)
      throw error
    } finally {
      loading.value = false
    }
  }

  // 创建产品
  const createProduct = async (data: ProductItem) => {
    try {
      await addProductApi(data)
      // 重新加载列表
      await loadProductList()
    } catch (error) {
      console.error('创建产品失败:', error)
      throw error
    }
  }

  // 重置分页
  const resetPagination = () => {
    currentPage.value = 1
    total.value = 0
  }

  return {
    productList,
    loading,
    currentPage,
    pageSize,
    total,
    hasMore,
    loadProductList,
    createProduct,
    resetPagination,
  }
}

2.3 最佳实践 ​

错误处理最佳实践 ​

框架推荐采用分层的错误处理策略，确保应用在不同场景下都能提供良好的用户体验和系统稳定性。

核心处理策略：

  1. 异步操作包装：使用 try-catch 结构包装所有异步API调用
  2. 统一错误处理：通过消息管理器展示用户友好的错误信息
  3. 错误日志记录：在控制台记录详细的错误信息便于调试
  4. 防重复提示：避免相同错误信息的频繁显示

处理流程：

  1. 异常捕获：捕获API调用过程中可能出现的各种异常
  2. 错误分类：根据错误类型进行差异化处理
  3. 用户提示：通过消息管理器展示适当的用户提示
  4. 日志记录：记录详细错误信息用于问题排查
  5. 状态恢复：确保应用在错误发生后能够正常继续运行

请求取消最佳实践 ​

框架提供完善的请求取消机制，帮助开发者有效管理组件生命周期中的异步请求，避免内存泄漏和无效请求处理。

核心取消策略：

  1. 组件生命周期管理：在组件卸载时自动取消相关请求
  2. 精确取消控制：支持取消特定端点或所有请求
  3. 错误类型识别：区分请求取消错误和其他类型的错误
  4. 资源清理：确保请求取消后相关资源得到正确释放

应用场景：

  1. 组件卸载：当用户离开页面时取消正在进行的请求
  2. 重复请求：避免同一数据的重复请求竞争
  3. 用户操作：用户主动取消长时间运行的请求
  4. 条件变更：当请求条件发生变化时取消旧请求

实现机制：

  1. 请求标识：为每个请求生成唯一标识符用于精确取消
  2. 取消令牌：使用AbortController实现请求取消功能
  3. 状态管理：跟踪请求状态和取消时机
  4. 错误处理：区分请求取消错误和真正的错误情况

3. 认证授权与安全机制 ​

3.1 认证机制 ​

登录认证流程 ​

框架提供标准化的登录认证流程，确保用户身份验证的安全性和一致性。

认证流程机制：

  1. 凭证验证：用户提交用户名和密码进行身份验证
  2. 令牌生成：服务器验证成功后生成访问令牌
  3. 令牌存储：使用令牌管理器安全存储令牌信息
  4. 用户信息管理：存储和同步用户基本信息
  5. 状态同步：更新应用认证状态和路由权限

安全特性：

  1. 安全传输：所有认证请求通过HTTPS加密传输
  2. 令牌保护：令牌管理器提供安全的令牌存储机制
  3. 会话管理：支持会话过期和自动续期
  4. 错误处理：统一的认证失败处理机制

流程控制：

  1. 登录验证：验证用户凭证的有效性
  2. 状态更新：更新全局认证状态
  3. 路由跳转：根据认证结果进行页面导航
  4. 错误反馈：提供清晰的错误提示信息

令牌管理机制 ​

框架采用安全的令牌管理机制，通过专门的令牌管理器实现访问令牌和刷新令牌的全生命周期管理。该机制确保用户认证状态的安全性和可靠性。

核心功能特性：

  1. 令牌存储安全

    • 使用安全的存储方式管理访问令牌和刷新令牌
    • 支持令牌过期时间自动管理
    • 防止令牌泄露和非法访问

  2. 令牌生命周期管理

    • 自动检测令牌过期状态
    • 支持令牌刷新和自动续期
    • 提供完整的令牌清理机制

  3. 安全防护措施

    • 令牌存储加密保护
    • 防止令牌重放攻击
    • 支持令牌失效检测

工作机制流程：

  1. 令牌获取：用户登录成功后获取访问令牌和刷新令牌
  2. 令牌存储：安全存储令牌信息并记录过期时间
  3. 令牌验证：每次请求前验证令牌有效性
  4. 令牌刷新：检测到令牌过期时自动使用刷新令牌获取新令牌
  5. 令牌清理：用户登出或检测到异常时自动清理令牌信息

3.2 安全防护机制 ​

频率限制机制 ​

框架实现了多层级频率限制机制，通过 RateLimiter 类提供全局、用户和端点级别的请求频率控制。该机制基于时间窗口算法，支持配置最大请求次数和时间窗口大小，有效防止API滥用和DDoS攻击。

核心特性：

  • 多层级限制：支持全局、用户、端点、用户-端点四个维度的频率控制
  • 时间窗口算法：基于滑动时间窗口统计请求次数
  • 自动清理：定期清理过期请求记录，避免内存泄漏
  • 配置灵活：支持不同端点设置不同的限制策略

CSRF 防护机制 ​

框架采用双重验证的CSRF防护机制，通过随机令牌和请求头验证确保请求的合法性。防护机制包括令牌生成、存储、验证和自动刷新功能。

防护流程：

  1. 令牌生成：使用密码学安全的随机数生成器创建唯一令牌
  2. 令牌存储：令牌存储在客户端并设置合理过期时间
  3. 请求验证：对敏感操作验证CSRF令牌的有效性
  4. 自动刷新：令牌过期时自动生成新令牌

安全管理器 ​

安全管理器统一管理所有安全相关功能，包括请求权限检查、CSRF头生成和安全策略配置。通过拦截器机制在请求发送前进行安全检查，确保系统安全性。

功能职责：

  • 请求权限验证：检查用户对端点的访问权限
  • 安全头管理：自动添加CSRF等安全相关请求头
  • 策略配置：统一管理所有安全相关的配置参数

3.3 错误处理机制 ​

统一错误处理机制 ​

VJSP Vue3 框架采用分层错误处理机制，通过响应拦截器实现统一的业务状态码处理逻辑。该机制能够智能识别不同类型的错误，并提供相应的用户提示和系统处理。

处理层次：

  1. 业务状态码处理：根据预定义的业务状态码进行针对性处理
  2. HTTP状态码处理：处理网络层面的错误状态
  3. 特殊场景处理：针对文件流、认证过期等特殊场景的差异化处理

核心功能：

  • 状态码映射：将业务状态码映射到具体的用户提示和系统行为
  • 自动登出：检测到认证过期时自动执行登出流程
  • 错误信息标准化：统一错误信息的格式和展示方式
  • 防重复提示：避免相同错误信息的重复显示

网络错误处理机制 ​

框架实现了完善的网络错误处理机制，能够识别不同类型的网络异常并提供友好的用户提示。处理范围包括请求超时、服务器错误、网络连接中断等常见网络问题。

错误类型识别：

  • 请求超时：ECONNABORTED错误码处理
  • 服务器错误：HTTP 5xx状态码处理
  • 网络连接：离线状态检测和处理
  • 通用错误：其他网络异常的统一处理

消息管理器机制 ​

消息管理器采用防重复显示机制，通过时间间隔控制和消息内容去重，避免相同消息的频繁显示。该机制基于Element Plus消息组件，提供统一的错误、警告、成功和信息提示管理。

核心特性：

  • 消息去重：相同消息在一定时间间隔内只显示一次
  • 优先级管理：不同类型消息的显示优先级控制
  • 状态跟踪：记录消息显示状态和频率
  • 配置灵活：支持自定义消息显示间隔和样式

4. 性能优化与监控 ​

4.1 缓存优化 ​

通用缓存机制 ​

项目采用统一的缓存管理机制，通过 CacheUtil 类提供标准化的数据缓存功能。该机制支持多种存储策略和高级特性，确保数据的安全性和性能。

核心特性：

  • 存储策略选择：支持 localStorage 和 sessionStorage 两种存储方式
  • 数据加密：可选的数据加密功能，保护敏感信息
  • 过期管理：自动清理过期缓存数据
  • 类型安全：提供完整的 TypeScript 类型支持

功能范围：

  • 缓存设置：支持设置缓存过期时间和加密选项
  • 缓存获取：自动处理数据解密和过期检查
  • 缓存管理：提供缓存移除、清空和状态检查功能
  • 错误处理：完善的错误处理和日志记录

字典数据缓存机制 ​

项目中的字典数据采用专门的缓存机制，结合了数据缓存和请求重试功能，确保字典数据的可靠性和性能。

缓存策略：

  • 时间窗口缓存：设置5分钟的有效缓存时间
  • 状态管理：跟踪数据加载状态和错误信息
  • 智能刷新：支持强制刷新和缓存有效性检查

重试机制：

  • 指数退避：重试延迟随重试次数指数增长
  • 最大重试限制：最多重试3次，避免无限重试
  • 状态重置：成功获取数据后重置重试计数

核心功能：

  • 自动缓存管理：根据时间窗口自动判断缓存有效性
  • 并发控制：防止同一数据的重复请求
  • 错误恢复：网络异常时的自动重试机制
  • 状态同步：确保数据加载状态的正确性

4.2 请求优化 ​

请求重试机制 ​

项目实现了智能的请求重试机制，通过拦截器模式实现网络异常的自动恢复和性能优化。

重试策略：

  • 指数退避算法：重试延迟随重试次数指数增长，避免服务器压力
  • 随机抖动：添加随机延迟避免多个客户端同时重试
  • 智能判断：仅对可重试的错误类型（网络错误、5xx服务器错误等）进行重试
  • 最大限制：设置最大重试次数，避免无限重试循环

拦截器架构：

  • 频率限制拦截器：在请求发送前检查频率限制，防止API滥用
  • CSRF防护拦截器：自动添加CSRF令牌，保护敏感操作
  • 响应重试拦截器：处理响应错误，实现智能重试逻辑

核心特性：

  • 请求取消管理：支持请求的取消和清理
  • 错误分类处理：区分不同类型的错误并采取相应策略
  • 状态跟踪：跟踪每个请求的重试状态和次数
  • 性能优化：通过合理的重试策略提升请求成功率

频率限制机制 ​

框架实现了多层级频率限制机制，有效防止API请求滥用和恶意攻击：

核心机制特性：

  1. 多层级控制策略

    • 用户级别限制：基于用户ID进行全局请求频率控制
    • 端点级别限制：针对特定API端点的请求频率限制
    • 用户端点组合限制：用户对特定端点的访问频率控制

  2. 时间窗口算法

    • 采用滑动时间窗口算法，精确控制单位时间内的请求次数
    • 支持自定义时间窗口大小和最大请求次数配置
    • 自动清理过期请求记录，避免内存泄漏

  3. 动态限制器管理

    • 按需创建限制器实例，避免不必要的资源占用
    • 支持实时查询剩余请求次数和重置时间
    • 提供完整的限制状态监控能力

工作机制流程：

  1. 请求标识：根据用户ID和端点路径生成唯一标识符
  2. 层级检查：依次检查用户、端点、用户端点三个层级的限制
  3. 时间窗口验证：在当前时间窗口内统计请求次数
  4. 决策判断：任一层级超出限制则拒绝请求，否则允许通过
  5. 状态更新：记录成功请求的时间戳，更新统计信息

配置灵活性：

  • 支持不同层级设置独立的限制参数
  • 可根据业务需求调整限制策略的严格程度
  • 提供全局默认配置和特定场景的定制化配置

总结 ​

VJSP Vue3 框架的API管理系统提供了完整的接口管理解决方案，具有以下特点：

  1. 类型安全: 完整的 TypeScript 类型支持
  2. 安全防护: 内置频率限制、CSRF防护等安全机制
  3. 错误处理: 统一的错误处理和消息管理
  4. 性能优化: 请求缓存、批量处理等优化策略
  5. 易于扩展: 模块化的API设计，便于业务扩展

通过遵循本文档的最佳实践，开发者可以高效地开发和维护企业级应用的API接口。