Vue 项目示例

项目配置

安装、初始化和首次配置，请参考 Vue 接入教程。

概述

本示例展示了如何在 Vue 项目中集成 ApiSorcery。Vue 是一个用于构建用户界面的渐进式 JavaScript 框架，配合 TypeScript 支持，通过组合式 API 和响应式状态管理提供出色的开发体验。

特性

• 类型安全：完整的 TypeScript 支持，生成接口和类型定义
• 组合式 API：使用响应式状态管理的现代 Vue 模式
• Axios 集成：内置支持 Axios HTTP 客户端和拦截器
• IntelliSense 支持：完整的 IDE 支持，包含自动完成和类型检查
• Tree shaking：通过 ES 模块支持优化打包体积

功能演示

本示例应用基于真实后端 API，实现了完整的用户管理模块：

• 分页列表 — 支持按 code、姓名、状态条件过滤的分页查询
• 完整 CRUD — 新增、查看、编辑、删除用户记录
• 头像上传 — 通过 POST /file/upload 上传图片，含 10 MB 大小校验
• Excel 导出 — 通过 Blob 响应下载过滤后的结果为 .xlsx 文件
• 字段验证 — 表单提交前异步检查 code 字段是否已存在

代码示例

分页查询 Composable

// composables/useUserList.ts
import { ref, onMounted } from 'vue';
import * as ApiUser from '@/api/auto/demo/ApiUser';
import type { UserInfoDto } from '@/api/auto/demo/model';

export function useUserList() {
  const users = ref<UserInfoDto[]>([]);
  const total = ref(0);
  const loading = ref(false);
  const page = ref(1);

  const fetchUsers = async (filters?: { code?: string; name?: string }) => {
    loading.value = true;
    try {
      const res = await ApiUser.getUserPaged({
        pagination: { page: page.value, limit: 10 },
        code: filters?.code || '',
        name: filters?.name || '',
      });
      users.value = res.results || [];
      total.value = res.total || 0;
    } catch (err) {
      console.error('获取用户失败:', err);
    } finally {
      loading.value = false;
    }
  };

  onMounted(() => fetchUsers());
  return { users, total, loading, page, refetch: fetchUsers };
}

Excel 导出

import * as ApiUser from '@/api/auto/demo/ApiUser';

async function handleExport(filters: { code?: string; name?: string }) {
  const response = await ApiUser.exportUsers({
    code: filters.code || '',
    name: filters.name || '',
  });
  const url = URL.createObjectURL(response.data);
  const link = document.createElement('a');
  link.href = url;
  link.download = response.name || 'users.xlsx';
  link.click();
  URL.revokeObjectURL(url);
}

头像上传

import * as ApiFile from '@/api/auto/demo/ApiFile';

async function uploadAvatar(file: File): Promise<string> {
  const sizeMB = file.size / 1024 / 1024;
  if (sizeMB > 10) throw new Error(`文件大小（${sizeMB.toFixed(2)} MB）超过 10 MB 限制`);
  const fileId = await ApiFile.uploadFile({ file });
  return `${import.meta.env.VITE_API_BASE_URL}/file/${fileId}`;
}

最佳实践

1. 类型定义：利用生成的 TypeScript 接口获得更好的类型安全性
2. 组合式函数：为常见的 API 操作创建可重用的组合式函数
3. 错误处理：使用 Vue 的错误处理机制实现适当的错误处理
4. 请求拦截器：使用 Axios 拦截器进行身份验证和请求/响应转换
5. 环境配置：为开发、测试和生产环境使用不同的 API 端点
6. 代码分割：实现 API 模块和路由的懒加载以优化打包体积
7. 响应式状态：利用 Vue 的响应式系统进行高效的状态管理