Vue3 项目示例

概述

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

特性

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

快速设置

1. 安装 ApiSorcery

npm install -g autoapi

2. 初始化配置

autoapi init -l ts

这将创建一个 .autoapirc.json 配置文件：

{
  "application": {
    "name": "TypeScript API 客户端",
    "language": "ts",
    "outputDir": "./src/api/auto"
  },
  "services": [
    {
      "code": "main",
      "name": "主服务",
      "source": "https://your-api.com/swagger.json",
      "enabled": true
    }
  ]
}

3. 安装依赖

npm install axios
npm install -D @types/node

4. 生成 API 客户端

autoapi generate

5. 在 Vue3 中使用

import { ref, onMounted } from 'vue';
import { ApiMain } from '@/api/auto/main/api';
import type { User } from '@/api/auto/main/model';

export default {
  setup() {
    const users = ref<User[]>([]);
    const loading = ref(false);
    const apiMain = new ApiMain();

    const fetchUsers = async () => {
      loading.value = true;
      try {
        const response = await apiMain.getUsers();
        users.value = response.data || [];
      } catch (error) {
        console.error('获取用户失败:', error);
      } finally {
        loading.value = false;
      }
    };

    onMounted(fetchUsers);

    return { users, loading, fetchUsers };
  }
};

Vue3 集成模式

组合式 API 与 Composables

// composables/useUsers.ts
import { ref, onMounted } from 'vue';
import { ApiMain } from '@/api/auto/main/api';

export function useUsers() {
  const users = ref<User[]>([]);
  const loading = ref(false);
  const error = ref<Error | null>(null);
  const apiMain = new ApiMain();

  const fetchUsers = async () => {
    loading.value = true;
    error.value = null;
    try {
      const response = await apiMain.getUsers();
      users.value = response.data || [];
    } catch (err) {
      error.value = err as Error;
    } finally {
      loading.value = false;
    }
  };

  onMounted(fetchUsers);

  return { users, loading, error, refetch: fetchUsers };
}

在 Vue 组件中使用

<template>
  <div>
    <div v-if="loading">加载中...</div>
    <div v-else-if="error">错误: {{ error.message }}</div>
    <ul v-else>
      <li v-for="user in users" :key="user.id">
        {{ user.name }}
      </li>
    </ul>
    <button @click="refetch">刷新</button>
  </div>
</template>

<script setup lang="ts">
import { useUsers } from '@/composables/useUsers';

const { users, loading, error, refetch } = useUsers();
</script>

选项式 API 支持

<script lang="ts">
import { defineComponent } from 'vue';
import { ApiMain } from '@/api/auto/main/api';

export default defineComponent({
  data() {
    return {
      users: [] as User[],
      loading: false,
      apiMain: new ApiMain()
    };
  },
  async mounted() {
    await this.fetchUsers();
  },
  methods: {
    async fetchUsers() {
      this.loading = true;
      try {
        const response = await this.apiMain.getUsers();
        this.users = response.data || [];
      } finally {
        this.loading = false;
      }
    }
  }
});
</script>

最佳实践

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