Vue 3 + TypeScript 企业级项目架构实战：从脚手架到生产环境的最佳实践

1
2
3
4
5

npm create vite@latest my-admin -- --template vue-ts
cd my-admin
npm install
npm install pinia vue-router@4 @vueuse/core
npm install -D @typescript-eslint/parser @typescript-eslint/eslint-plugin

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

src/
├── api/                  # API 请求层
│   ├── modules/          # 按业务模块拆分
│   │   ├── user.ts
│   │   ├── order.ts
│   │   └── dashboard.ts
│   ├── request.ts        # Axios 实例封装
│   └── types.ts          # API 响应类型定义
├── assets/               # 静态资源
│   ├── icons/
│   └── styles/
├── components/           # 全局通用组件
│   ├── DataTable/
│   │   ├── index.vue
│   │   ├── columns.ts
│   │   └── types.ts
│   └── SearchBar/
├── composables/          # 组合式函数 (Hooks)
│   ├── useTable.ts
│   ├── usePagination.ts
│   ├── useFetch.ts
│   └── usePermission.ts
├── layouts/              # 布局组件
│   ├── DefaultLayout.vue
│   └── BlankLayout.vue
├── pages/                # 页面组件 (路由级)
│   ├── Dashboard.vue
│   ├── Login.vue
│   └── user/
│       ├── UserList.vue
│       └── UserDetail.vue
├── router/               # 路由配置
│   ├── index.ts
│   ├── routes.ts
│   └── guards.ts
├── stores/               # Pinia 状态管理
│   ├── modules/
│   │   ├── user.ts
│   │   └── app.ts
│   └── index.ts
├── utils/                # 工具函数
│   ├── storage.ts
│   ├── format.ts
│   └── validator.ts
├── types/                # 全局类型定义
│   ├── global.d.ts
│   └── env.d.ts
├── App.vue
└── main.ts

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

// src/api/request.ts
import axios, { type AxiosRequestConfig, type AxiosResponse } from 'axios'
import { useUserStore } from '@/stores/modules/user'
import { ElMessage } from 'element-plus'

// 定义统一的 API 响应结构
interface ApiResponse<T = any> {
  code: number
  data: T
  message: string
}

const request = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL,
  timeout: 15000,
  headers: { 'Content-Type': 'application/json' },
})

// 请求拦截器：注入 Token
request.interceptors.request.use(
  (config) => {
    const userStore = useUserStore()
    if (userStore.token) {
      config.headers.Authorization = `Bearer ${userStore.token}`
    }
    return config
  },
  (error) => Promise.reject(error)
)

// 响应拦截器：统一错误处理
request.interceptors.response.use(
  (response: AxiosResponse<ApiResponse>) => {
    const { code, data, message } = response.data

    if (code === 200) {
      return data as any
    }

    // Token 过期，跳转登录
    if (code === 401) {
      const userStore = useUserStore()
      userStore.logout()
      window.location.href = '/login'
      return Promise.reject(new Error('登录已过期'))
    }

    ElMessage.error(message || '请求失败')
    return Promise.reject(new Error(message))
  },
  (error) => {
    const msg = error.response?.status === 500
      ? '服务器内部错误'
      : '网络异常，请检查连接'
    ElMessage.error(msg)
    return Promise.reject(error)
  }
)

// 泛型封装，自动推导类型
export function get<T>(url: string, params?: any, config?: AxiosRequestConfig) {
  return request.get<ApiResponse<T>>(url, { params, ...config }) as Promise<T>
}

export function post<T>(url: string, data?: any, config?: AxiosRequestConfig) {
  return request.post<ApiResponse<T>>(url, data, config) as Promise<T>
}

export default request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

// src/composables/useFetch.ts
import { ref, type Ref } from 'vue'

interface UseFetchOptions<T> {
  /** 是否立即执行 */
  immediate?: boolean
  /** 请求成功后的回调 */
  onSuccess?: (data: T) => void
  /** 请求失败后的回调 */
  onError?: (error: Error) => void
}

export function useFetch<T>(
  fetcher: () => Promise<T>,
  options: UseFetchOptions<T> = {}
) {
  const { immediate = true, onSuccess, onError } = options

  const data: Ref<T | null> = ref(null)
  const loading = ref(false)
  const error: Ref<Error | null> = ref(null)

  async function execute() {
    loading.value = true
    error.value = null

    try {
      data.value = await fetcher()
      onSuccess?.(data.value!)
    } catch (err) {
      error.value = err as Error
      onError?.(err as Error)
    } finally {
      loading.value = false
    }
  }

  if (immediate) {
    execute()
  }

  return { data, loading, error, execute }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

// src/composables/useTable.ts
import { ref, reactive, onMounted, type Ref } from 'vue'

interface PaginationState {
  page: number
  pageSize: number
  total: number
}

interface UseTableOptions<T> {
  /** 列表接口 */
  fetcher: (params: { page: number; pageSize: number; [key: string]: any }) => Promise<{
    list: T[]
    total: number
  }>
  /** 每页条数 */
  defaultPageSize?: number
  /** 查询参数 */
  queryParams?: Record<string, any>
}

export function useTable<T>(options: UseTableOptions<T>) {
  const { fetcher, defaultPageSize = 20, queryParams = {} } = options

  const list: Ref<T[]> = ref([])
  const loading = ref(false)
  const pagination = reactive<PaginationState>({
    page: 1,
    pageSize: defaultPageSize,
    total: 0,
  })

  async function loadData() {
    loading.value = true
    try {
      const result = await fetcher({
        page: pagination.page,
        pageSize: pagination.pageSize,
        ...queryParams,
      })
      list.value = result.list
      pagination.total = result.total
    } catch (err) {
      console.error('加载数据失败:', err)
      list.value = []
    } finally {
      loading.value = false
    }
  }

  function handlePageChange(page: number) {
    pagination.page = page
    loadData()
  }

  function handleSizeChange(size: number) {
    pagination.pageSize = size
    pagination.page = 1
    loadData()
  }

  function refresh() {
    loadData()
  }

  onMounted(() => {
    loadData()
  })

  return {
    list,
    loading,
    pagination,
    handlePageChange,
    handleSizeChange,
    refresh,
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

<!-- src/pages/user/UserList.vue -->
<script setup lang="ts">
import { useTable } from '@/composables/useTable'
import { getUserList, type UserInfo } from '@/api/modules/user'

const {
  list: userList,
  loading,
  pagination,
  handlePageChange,
  handleSizeChange,
} = useTable<UserInfo>({
  fetcher: (params) => getUserList(params),
  defaultPageSize: 15,
})
</script>

<template>
  <el-table v-loading="loading" :data="userList" border stripe>
    <el-table-column prop="id" label="ID" width="80" />
    <el-table-column prop="name" label="姓名" />
    <el-table-column prop="email" label="邮箱" />
    <el-table-column prop="role" label="角色" />
  </el-table>

  <el-pagination
    class="mt-4 justify-end"
    :current-page="pagination.page"
    :page-size="pagination.pageSize"
    :total="pagination.total"
    layout="total, prev, pager, next, sizes"
    @current-change="handlePageChange"
    @size-change="handleSizeChange"
  />
</template>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

// src/stores/modules/user.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'
import { login, getUserInfo, logout as logoutApi } from '@/api/modules/user'
import type { UserInfo } from '@/api/types'

export const useUserStore = defineStore('user', () => {
  // State
  const token = ref(localStorage.getItem('token') || '')
  const userInfo = ref<UserInfo | null>(null)

  // Getters
  const isLoggedIn = computed(() => !!token.value)
  const userName = computed(() => userInfo.value?.name || '未登录')
  const permissions = computed(() => userInfo.value?.permissions || [])

  // Actions
  async function handleLogin(username: string, password: string) {
    const data = await login({ username, password })
    token.value = data.token
    localStorage.setItem('token', data.token)
    await fetchUserInfo()
  }

  async function fetchUserInfo() {
    if (!token.value) return
    const data = await getUserInfo()
    userInfo.value = data
  }

  function logout() {
    logoutApi().catch(() => {})
    token.value = ''
    userInfo.value = null
    localStorage.removeItem('token')
  }

  function hasPermission(perm: string): boolean {
    return permissions.value.includes(perm)
  }

  return {
    token,
    userInfo,
    isLoggedIn,
    userName,
    permissions,
    handleLogin,
    fetchUserInfo,
    logout,
    hasPermission,
  }
})

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

// src/router/routes.ts
import type { RouteRecordRaw } from 'vue-router'

const routes: RouteRecordRaw[] = [
  {
    path: '/login',
    component: () => import('@/pages/Login.vue'),
    meta: { layout: 'blank' },
  },
  {
    path: '/',
    component: () => import('@/layouts/DefaultLayout.vue'),
    redirect: '/dashboard',
    children: [
      {
        path: 'dashboard',
        name: 'Dashboard',
        component: () => import('@/pages/Dashboard.vue'),
        meta: { title: '仪表盘', icon: 'dashboard' },
      },
      {
        path: 'user',
        name: 'User',
        redirect: '/user/list',
        meta: { title: '用户管理', icon: 'user' },
        children: [
          {
            path: 'list',
            name: 'UserList',
            component: () => import('@/pages/user/UserList.vue'),
            meta: { title: '用户列表', permission: 'user:list' },
          },
          {
            path: 'detail/:id',
            name: 'UserDetail',
            component: () => import('@/pages/user/UserDetail.vue'),
            meta: { title: '用户详情', hidden: true },
          },
        ],
      },
    ],
  },
]

export default routes

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

// src/router/guards.ts
import type { Router } from 'vue-router'
import { useUserStore } from '@/stores/modules/user'

export function setupRouterGuards(router: Router) {
  router.beforeEach(async (to, _from, next) => {
    const userStore = useUserStore()

    // 白名单页面直接放行
    const whitelist = ['/login', '/404']
    if (whitelist.includes(to.path)) {
      next()
      return
    }

    // 未登录跳转登录页
    if (!userStore.isLoggedIn) {
      next({ path: '/login', query: { redirect: to.fullPath } })
      return
    }

    // 已登录但未获取用户信息，先拉取
    if (!userStore.userInfo) {
      try {
        await userStore.fetchUserInfo()
      } catch {
        userStore.logout()
        next({ path: '/login' })
        return
      }
    }

    // 权限校验
    const requiredPermission = to.meta.permission as string | undefined
    if (requiredPermission && !userStore.hasPermission(requiredPermission)) {
      next('/403')
      return
    }

    next()
  })
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

// src/utils/errorHandler.ts
import { type App, type ErrorPayload, handleError } from 'vue'
import { ElMessage } from 'element-plus'

export function setupErrorHandler(app: App) {
  // Vue 运行时错误
  app.config.errorHandler = (err, instance, info) => {
    console.error('[Vue Error]', err)
    console.error('[Component]', instance?.$options?.name)
    console.error('[Info]', info)

    ElMessage.error('页面出现异常，请刷新重试')
  }

  // 未捕获的 Promise 错误
  window.addEventListener('unhandledrejection', (event) => {
    console.error('[Unhandled Rejection]', event.reason)
    event.preventDefault() // 阻止控制台报错
  })

  // 全局 JS 错误
  window.addEventListener('error', (event) => {
    console.error('[Global Error]', event.error)
  })
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

// src/main.ts
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import router from './router'
import App from './App.vue'
import { setupErrorHandler } from './utils/errorHandler'

const app = createApp(App)

app.use(createPinia())
app.use(router)
setupErrorHandler(app)

router.isReady().then(() => {
  app.mount('#app')
})

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// src/types/env.d.ts
/// <reference types="vite/client" />

interface ImportMetaEnv {
  /** API 基础地址 */
  readonly VITE_API_BASE_URL: string
  /** 应用标题 */
  readonly VITE_APP_TITLE: string
  /** 是否开启 Mock */
  readonly VITE_USE_MOCK: string
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

1
2

const baseUrl = import.meta.env.VITE_API_BASE_URL  // ✅ 类型安全
const wrong = import.meta.env.VITE_BASE_URL          // ❌ 编译报错

1
2

// 路由懒加载 — 只有访问时才加载对应页面
const UserList = () => import('@/pages/user/UserList.vue')

1

<el-table-v2 :data="bigList" :columns="columns" :width="800" :height="600" />

1
2

npm run build -- --mode analyze
npx vite-bundle-visualizer