前端Vue3项目代码开发规范

前端Vue3项目代码开发规范

这是一份专为 Vue3 技术栈设计的前端开发规范标准，由于目前项目小组刚组建，前端代码编写暂未形成规范，故结合 GitHub 流行规范（如 Airbnb、Vue 官方风格指南）和工程化实践，梳理出了一份前端项目开发规范标准以备小组成员共享，文档包含四个核心模块：

---

一、代码书写规范

1. Vue 组件规范

• 组件结构顺序（单文件组件 SFC）

  <template>   <!-- 最多一个顶级元素 -->
    <div>...</div>
  </template>
  ​
  <script setup>  // 使用 Composition API + <script setup>
  // 导入顺序：Vue → 第三方库 → 组件 → 工具类 → 样式
  import { ref, computed } from 'vue'
  import { useUserStore } from '@/stores/user'
  import BaseButton from './BaseButton.vue'
  </script>
  ​
  <style scoped>  <!-- 强制 scoped 或 CSS Modules -->
  .component-block { ... }
  </style>

• 命名约定：

  • 组件名：PascalCase（如 UserProfile.vue）
  • 自定义事件：kebab-case（如 @update-value）
  • Props：camelCase 声明，模板中使用 kebab-case

2. Pinia 状态管理

// stores/user.ts
export const useUserStore = defineStore('user', () => {
  // State
  const username = ref('')
  
  // Actions
  const fetchUser = async () => { 
    const res = await axios.get('/api/user') 
    username.value = res.data.name
  }
  
  // Getters
  const isLoggedIn = computed(() => !!username.value)
  
  return { username, fetchUser, isLoggedIn }
})

3. 路由规范（Vue Router）

// router/index.ts
const routes = [
  {
    path: '/user/:id',
    name: 'user-profile', // 路由名使用 kebab-case
    component: () => import('@/views/UserProfile.vue'), // 动态导入
    meta: { requiresAuth: true }
  }
]

---

二、文件命名规范

类型	命名规则	示例
Vue 组件	PascalCase	SearchInput.vue
页面视图	PascalCase	UserDashboard.vue
Pinia Store	camelCase	useCartStore.ts
工具函数	camelCase	formatCurrency.js
路由文件	kebab-case	admin-routes.ts
资产文件	kebab-case	icon-arrow-right.svg

目录结构示例：

src/
├── components/
│   ├── base/               // 基础组件
│   │   └── BaseButton.vue
│   └── layout/
├── views/
│   └── UserProfile.vue
├── stores/
│   └── useCartStore.ts
├── utils/
│   └── dateFormatter.ts
└── api/
    └── authApi.ts          // API 模块化封装

---

三、Git 提交规范

采用 Conventional Commits 标准：

<type>(<scope>): <subject>
# 示例
feat(user): add password reset UI
fix(router): handle 404 redirect
chore(deps): upgrade axios to 1.2.0

常用 type：

• feat：新功能
• fix：Bug 修复
• docs：文档变更
• style：代码样式调整
• refactor：重构（不修复 bug 也不增加功能）
• test：测试相关
• chore：构建/工具变更

---

四、代码校验规范

1. 工具链配置

# 必备依赖
npm install -D eslint prettier eslint-plugin-vue @typescript-eslint/parser 
eslint-config-prettier husky lint-staged

2. ESLint 配置（.eslintrc.cjs）

module.exports = {
  root: true,
  env: { browser: true, es2021: true },
  extends: [
    'eslint:recommended',
    'plugin:vue/vue3-recommended',
    'plugin:prettier/recommended' 
  ],
  rules: {
    'vue/multi-word-component-names': 'off', // 允许单单词组件名
    'vue/no-unused-vars': 'error',
    'vue/component-api-order': ['error', { // Composition API 顺序
      order: ['setup', 'props', 'data', 'computed', 'methods', 'lifecycle']
    }]
  }
}

3. Prettier 配置（.prettierrc）

{
  "semi": false,
  "singleQuote": true,
  "trailingComma": "es5",
  "printWidth": 100,
  "htmlWhitespaceSensitivity": "ignore"
}

4. Git Hook 自动化（package.json）

{
  "scripts": {
    "lint": "eslint . --ext .js,.ts,.vue --fix",
    "prepare": "husky install"
  },
  "lint-staged": {
    "*.{js,ts,vue}": ["eslint --fix", "prettier --write"],
    "*.{css,scss}": ["stylelint --fix"]
  }
}

初始化流程：

npx husky install
npx husky add .husky/pre-commit "npx lint-staged"

---

五、附加工程化建议

0. IDE 统一：推荐 VSCode + 插件：

   • Vue Language Features (Volar)
   • ESLint / Prettier
   • EditorConfig

1. 提交信息校验：

   npm install -D @commitlint/cli @commitlint/config-conventional
   echo "module.exports = { extends: ['@commitlint/config-conventional'] }" > .commitlintrc.js
   npx husky add .husky/commit-msg 'npx commitlint --edit $1'

2. CI/CD 集成（示例：GitHub Actions）：

   jobs:
     lint:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v3
         - run: npm install
         - run: npm run lint

执行策略：

0. 将规范文档存入项目根目录 /docs/frontend-standard.md
1. 首次会议宣讲规范，使用脚手架初始化校验工具
2. 代码审查时重点检查规范符合度
3. 每月迭代优化规范内容

通过此规范可显著提升代码一致性、降低维护成本，同时为后续项目扩展奠定基础。