Vue 3 项目结构

ThesisAI 生成的 Vue 3 项目采用标准化的目录结构，便于理解和维护。

完整目录结构

frontend

public // 公共静态资源（直接复制到输出）

favicon.ico

src

api // API 客户端层

client.ts // HTTP 客户端封装（已配置拦截器）

auth.ts // 认证相关 API

[module].ts // 各业务模块 API

assets // 静态资源（会被处理）

images

styles

components // 通用组件

ui // UI 库组件（shadcn-vue 等）

button

input

...

FileUpload.vue // 文件上传组件（内置）

[Feature].vue // 业务通用组件

composables // 组合式函数（优先于 Store）

useAuth.ts // 认证相关（内置，调用 store）

use[Feature].ts // TanStack Query composables

config // 配置文件

nav.ts // 导航菜单配置

layouts // 布局组件（内置）

DefaultLayout.vue // 默认顶导航布局

SidebarLayout.vue // 侧边栏布局

AdminLayout.vue // 管理后台布局

AuthLayout.vue // 登录/注册布局

router // 路由配置

index.ts // 路由定义与守卫

stores // Pinia 状态管理（仅必要时使用）

auth.ts // 认证状态（内置）

types // TypeScript 类型定义

api.d.ts // API 响应类型

[module].d.ts // 业务类型

utils // 工具函数（内置）

format.ts // 格式化（日期、金额等）

validators.ts // 校验函数

excel.ts // Excel 导入导出

views // 页面组件

admin // 管理后台页面

DashboardPage.vue

CrudPage.vue // CRUD 模板页

[Module]Page.vue

auth // 认证页面

LoginPage.vue

RegisterPage.vue

HomePage.vue

[Feature]Page.vue

App.vue // 根组件

main.ts // 入口文件

index.html // HTML 模板

vite.config.ts // Vite 配置

tailwind.config.js // Tailwind 配置

tsconfig.json // TypeScript 配置

package.json

Dockerfile // Docker 部署配置

核心目录说明

api/ - API 客户端层

存放所有与后端交互的代码。

api/client.ts

// HTTP 客户端已封装好，特性：
// - 自动注入 Authorization Token
// - 统一错误处理和 Toast 提示
// - 响应数据自动解构（直接返回 data）
import { httpClient } from './client'

// 使用示例
const users = await httpClient.get<User[]>('/users')
// users 直接就是 User[] 类型，无需 .data

API 文件组织

每个业务模块一个文件：user.ts、product.ts、order.ts 等。

composables/ - 组合式函数

存放可复用的逻辑，优先使用 composables 而非 Pinia Store。

类型	示例	说明
数据请求	useUsers.ts	封装 TanStack Query
业务逻辑	useCart.ts	购物车逻辑
UI 状态	usePagination.ts	分页状态

composables/useProducts.ts

import { useQuery, useMutation, useQueryClient } from '@tanstack/vue-query'
import { productApi } from '@/api/product'

export function useProducts(params: ProductListParams) {
  return useQuery({
    queryKey: ['products', params.page, params.pageSize],
    queryFn: () => productApi.getList({
      page: params.page.value,
      page_size: params.pageSize.value,
    }),
  })
}

export function useDeleteProduct() {
  const queryClient = useQueryClient()
  return useMutation({
    mutationFn: productApi.delete,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['products'] })
    },
  })
}

layouts/ - 布局组件

已内置，无需创建，直接在路由中使用：

布局	用途
DefaultLayout	普通页面，顶部导航
SidebarLayout	需要侧边菜单的页面
AdminLayout	管理后台
AuthLayout	登录/注册

router/index.ts

const routes = [
  {
    path: '/',
    component: () => import('@/layouts/DefaultLayout.vue'),
    children: [
      { path: '', component: () => import('@/views/HomePage.vue') },
    ],
  },
  {
    path: '/admin',
    component: () => import('@/layouts/AdminLayout.vue'),
    meta: { requiresAuth: true, permissions: ['admin'] },
    children: [
      { path: '', component: () => import('@/views/admin/DashboardPage.vue') },
    ],
  },
]

stores/ - Pinia 状态管理

何时使用 Pinia？

只有以下情况才使用 Pinia，其他情况优先使用 composables：

1. 需要在非组件环境访问（如 axios 拦截器、路由守卫）
2. 需要跨多个不相关组件共享复杂状态
3. 需要 DevTools 调试支持

常见必须用 Pinia 的场景：用户认证状态

views/ - 页面组件

按功能模块组织页面：

views/
├── admin/           # 管理后台
│   ├── DashboardPage.vue
│   ├── UserManagePage.vue
│   └── CrudPage.vue      # CRUD 模板（可复制使用）
├── auth/            # 认证
│   ├── LoginPage.vue
│   └── RegisterPage.vue
├── HomePage.vue
└── ProductListPage.vue

CRUD 页面模板

views/admin/CrudPage.vue 是内置的 CRUD 模板，包含：

• 表格 + 分页
• 筛选表单
• 新增/编辑弹窗
• 删除确认
• TanStack Query 集成

开发管理后台页面时，直接复制此模板修改。

utils/ - 工具函数

已内置，直接导入使用：

文件	功能
format.ts	日期、金额格式化
validators.ts	邮箱、手机号校验
excel.ts	Excel 导入导出

使用工具函数

import { formatDate, formatCurrency } from '@/utils/format'
import { isEmail, isPhone } from '@/utils/validators'
import { exportToExcel, importFromExcel } from '@/utils/excel'

formatDate(new Date())           // '2024-01-15'
formatCurrency(1234.56)          // '¥1,234.56'
isEmail('test@example.com')      // true

文件命名规范

类型	规范	示例
组件	PascalCase	UserCard.vue
页面	PascalCase + Page 后缀	UserListPage.vue
composable	camelCase + use 前缀	useUsers.ts
API	camelCase + 模块名	user.ts
类型	camelCase + .d.ts	user.d.ts
工具	camelCase	format.ts

导入别名

项目配置了以下路径别名：

import { useUsers } from '@/composables/useUsers'  // src/composables
import { userApi } from '@/api/user'               // src/api
import { useAuthStore } from '@/stores/auth'       // src/stores
import { formatDate } from '@/utils/format'        // src/utils