編輯 | 究查 | 歷程 | 原始

Vue Project

基於 Vue 3 + TypeScript + Vite 的現代化前端專案模板。

📁 專案架構

本專案採用 Feature-Based 資料夾架構，讓功能模組更加內聚且易於維護。

核心理念

  • 高內聚性：將高度耦合的程式碼放在一起,相關的功能邏輯集中管理
  • 功能優先：主要功能放在 src/features/ 目錄下,每個 feature 作為一個獨立模組
  • 就近原則：每個 feature 內可包含自己的 stores, components, utils, types 等
  • 靈活組織：根據複雜度選擇使用單一檔案或建立資料夾
  • 共用提升：高度共用的代碼放在 src/ 根目錄下(如 src/hooks/, src/stores/, src/utils/)

目錄結構

src/
├── features/              # 功能模組目錄
│   └── example/          # 範例功能模組
│       ├── index.vue     # 主元件
│       ├── api.ts        # API 請求
│       └── index.spec.ts # 單元測試
├── hooks/                # 共用的 Composition API hooks
│   └── useRequest.ts     # API 請求 hook
├── stores/               # 全域狀態管理
│   ├── axios.ts          # Axios 實例與攔截器
│   └── counter.ts        # 範例 store
├── mocks/                # MSW mock 資料
│   ├── browser.ts        # 瀏覽器環境 mock
│   ├── node.ts           # Node 環境 mock
│   ├── handlers.ts       # API handlers
│   └── data/             # Mock 資料
├── router/               # Vue Router 配置
├── utils/                # 共用工具函數
│   └── cn.ts             # Tailwind CSS 類名合併工具
├── types/                # 全域型別定義
├── plugins/              # Vue 插件
│   └── icons/            # Iconify 整合
├── config/               # [選用] 專案全域設定
├── const/                # [選用] 常數定義
└── assets/               # 靜態資源
    ├── css/
    └── icons/            # 圖標資源

🛠️ 技術棧

核心框架

  • Vue 3 - 漸進式前端框架
  • TypeScript - 型別安全的 JavaScript 超集
  • Vite - 次世代前端建構工具
  • Pinia - Vue 3 官方狀態管理

開發工具

  • ESLint - 程式碼品質檢查
  • Prettier - 程式碼格式化
  • Vitest - 單元測試框架
  • Playwright - E2E 測試框架
  • MSW (Mock Service Worker) - API mocking 工具

UI & 樣式

  • Tailwind CSS - 實用優先的 CSS 框架
  • Iconify - 統一的圖標解決方案(內建自動整合工具)

🔧 核心功能說明

Iconify 整合工具

專案內建自動化的 Iconify 圖標整合工具,會自動掃描專案中使用的圖標並產生對應的 JSON 檔案,實現按需載入,減少打包體積。圖標檔案放在 src/assets/icons/ 目錄下,建構時會自動處理。

API 請求架構

  1. useRequest Hook - 提供統一的 API 請求介面
  2. Axios Store - 管理 Axios 實例與全域攔截器(如 token 注入、錯誤處理等)
  3. MSW - 開發環境下提供 API mocking,讓前端開發不依賴後端服務

三者關係:

Component → useRequest → Axios Store → Backend API
                                    ↓ (開發環境)
                                   MSW

cn 工具函數

cn 是基於 clsx 和 tailwind-merge 的工具函數,用於智能合併 Tailwind CSS 類名,解決類名衝突問題。

cn('px-2 py-1', 'px-4') // 輸出: 'py-1 px-4' (後者覆蓋前者)

📦 推薦套件

當專案需求擴展時,以下是可優先選用的套件:

Vue 生態系統

  • @vueuse/core - 豐富的 Vue Composition API 工具集,提供大量開箱即用的組合式函數

通用工具

  • dayjs - 輕量級日期處理庫
  • zod - TypeScript-first 的 schema 驗證庫
  • decimal.js - 任意精度的十進制運算庫,適用於金融等對數值精度要求高的場景
  • numeral.js - 強大的數值格式化工具

資料請求

  • @tanstack/vue-query - 強大的非同步狀態管理庫,提供快取、重試、輪詢等功能,大幅簡化 API 請求邏輯

表單處理

  • vee-validate - Vue 3 表單驗證框架,支援多種驗證策略與 schema 整合

UI 框架

  • Element Plus - 成熟的 Vue 3 UI 組件庫(公司慣用選擇)

💡 開發心法

1. UI 元件開發策略

原則: 除非是複雜或難以實現的元件(如 Table、Popper、DatePicker、VirtualSelect 等),否則盡可能自行開發。

理由:

  • 現在有 AI 輔助,簡單元件開發成本大幅降低
  • 自行開發的元件更貼合專案需求,減少不必要的依賴
  • 對於複雜元件,直接使用 UI 框架可節省大量時間

2. 商業邏輯與元件分離

原則: 盡可能將商業邏輯移至元件之外(如獨立的 composables、utils 或 stores)。

好處:

  • 元件保持簡潔,專注於 UI 呈現
  • 商業邏輯可獨立測試,提高程式碼可測試性
  • 邏輯可跨元件復用

3. 測試規範

原則: 測試不是必須的,但如果寫了測試,就必須保證測試通過才能 commit。

要求:

  • ✅ 所有測試都必須 pass
  • ❌ 不允許 commit 失敗的測試
  • ❌ 如果測試無法修復,請直接刪除,不要留下會誤導的錯誤測試

執行方式: 建議使用 Git hooks(如 husky + lint-staged)確保 commit 前測試通過。

🚀 快速開始

安裝依賴

npm install

開發環境

npm run dev

執行測試

# 單元測試
npm run test:unit

# E2E 測試(首次需安裝瀏覽器)
npx playwright install
npm run test:e2e

程式碼檢查

npm run lint

📚 更多文件

🔧 IDE 設定建議