@teojs/vite-plugin-normalizing-apis

一个 Vite 插件，用于自动化管理和规范化 API 接口。它可以自动扫描指定目录下的 API 文件，生成类型声明和虚拟模块，让你可以更优雅地管理和使用 API。

特性

• 📁 按目录结构自动组织 API
• 🔄 自动生成 TypeScript 类型声明
• 📝 支持自定义 API 模板
• 🚀 开发时热更新
• 💡 完整的类型提示

安装

1# npm
2npm install @teojs/vite-plugin-normalizing-apis -D
3
4# yarn
5yarn add @teojs/vite-plugin-normalizing-apis -D
6
7# pnpm
8pnpm add @teojs/vite-plugin-normalizing-apis -D

配置

1. 配置 Vite 插件

1// vite.config.ts
2import { defineConfig } from 'vite'
3import generatedApis from '@teojs/vite-plugin-normalizing-apis'
4
5export default defineConfig({
6  plugins: [
7    generatedApis({
8      apisDirs: 'src/service/apis', // API 文件存放目录
9      dts: 'src/service/types.d.ts', // 类型声明文件输出路径
10      tpl: 'src/service/tpl.ts', // API 模板文件路径
11    }),
12  ],
13})

2. 添加类型声明引用

1// types/vite-env.d.ts
2/// <reference types="@teojs/vite-plugin-normalizing-apis/client" />

3. 导出 API

1// src/service/index.ts
2export * from 'virtual:normalizing-apis'

使用示例

1. 创建 API 文件

1// src/service/apis/user/login.ts
2import type { AxiosRequestConfig } from 'axios'
3import http from '@/service/axios.config'
4
5interface RequestConfig extends AxiosRequestConfig {
6  data: {
7    username: string
8    password: string
9  }
10}
11
12interface ResponseData {
13  code: string
14  message: string
15  data: {
16    token: string
17    userId: string
18  }
19}
20
21/**
22 * @description 用户登录
23 */
24export default function api(config: RequestConfig): Promise<ResponseData> {
25  return http<ResponseData>({
26    method: 'post',
27    url: '/api/user/login',
28    ...config,
29  })
30}

2. 在组件中使用

1<script setup lang="ts">
2import { apis } from '@/service'
3
4async function handleLogin() {
5  try {
6    const res = await apis.user.login({
7      data: {
8        username: 'admin',
9        password: '123456',
10      },
11    })
12    console.log('登录成功:', res.data)
13  } catch (error) {
14    console.error('登录失败:', error)
15  }
16}
17</script>

API 目录结构示例

src/service/apis/
├── user/
│   ├── login.ts
│   ├── logout.ts
│   └── profile.ts
├── product/
│   ├── list.ts
│   └── detail.ts
└── order/
    ├── create.ts
    └── list.ts

配置项说明

参数	类型	必填	默认值	说明
apisDirs	string	是	-	API 文件存放目录，相对于项目根目录
dts	string	是	-	类型声明文件的输出路径
tpl	string	否	-	API 模板文件路径，新建 API 文件时会自动填充此模板内容

最佳实践

1. 将 API 按业务模块分类存放
2. 每个 API 文件只导出一个默认函数
3. 使用 TypeScript 编写 API，提供完整的类型定义
4. 为每个 API 添加清晰的注释说明

注意事项

1. API 文件必须导出默认函数
2. 确保 API 目录结构清晰合理
3. 建议使用 TypeScript 以获得更好的类型提示
4. 模板文件变更后需要重启开发服务器

License

MIT