Vue项目代码规范的最佳实践与实战应用指南

src/
├── api/                 # API接口层
│   ├── modules/        # 业务模块接口
│   └── interceptors.ts # 请求拦截器
├── assets/              # 静态资源
│   ├── images/
│   ├── styles/
│   └── fonts/
├── components/          # 公共组件
│   ├── common/         # 通用组件
│   ├── business/       # 业务组件
│   └── ui/            # UI组件库
├── composables/         # 组合式函数
├── layouts/            # 布局组件
├── pages/              # 页面组件（路由页面）
├── plugins/            # 插件配置
├── router/             # 路由配置
│   ├── modules/       # 路由模块
│   └── guards.ts      # 路由守卫
├── stores/             # 状态管理
│   ├── modules/      # 状态模块
│   └── index.ts       # 主入口
├── styles/             # 全局样式
├── types/              # 类型定义
├── utils/              # 工具函数
│   ├── constants.ts   # 常量定义
│   ├── helpers.ts     # 辅助函数
│   └── validators.ts  # 验证函数
└── App.vue

// ✅ 推荐
UserProfile.vue
ProductList.vue
DataTable.vue
 
// ❌ 避免
user-profile.vue
product_list.vue

// ✅ 推荐
formatDate.js
deepClone.js
validateEmail.js
 
// ❌ 避免
FormatDate.js
format_date.js

<template>
  <!-- 模板区域：保持简洁，避免复杂逻辑 -->
  <div class="user-profile">
    <user-avatar :src="user.avatar" :alt="user.name" />
    <user-info :user="user" @update="handleUpdate" />
  </div>
</template>
 
<script setup lang="ts">
// 导入区域：按顺序组织导入
import { ref, computed, watch, onMounted } from 'vue'
import type { User } from '@/types/user'
import { useUserStore } from '@/stores/user'
import UserAvatar from './UserAvatar.vue'
import UserInfo from './UserInfo.vue'
 
// 类型定义
interface Props {
  userId: string
  editable?: boolean
}
 
interface Emits {
  update: [user: User]
  delete: [userId: string]
}
 
// 组件定义
const props = withDefaults(defineProps<Props>(), {
  editable: false
})
 
const emit = defineEmits<Emits>()
 
// 状态管理
const userStore = useUserStore()
const loading = ref(false)
const error = ref<string | null>(null)
 
// 计算属性
const user = computed(() => userStore.getUserById(props.userId))
const canEdit = computed(() => props.editable && user.value?.isActive)
 
// 方法定义
const handleUpdate = async (updatedUser: User) => {
  try {
    loading.value = true
    await userStore.updateUser(updatedUser)
    emit('update', updatedUser)
  } catch (err) {
    error.value = err instanceof Error ? err.message : '更新失败'
  } finally {
    loading.value = false
  }
}
 
// 生命周期
onMounted(async () => {
  if (!user.value) {
    await userStore.fetchUser(props.userId)
  }
})
</script>
 
<style scoped>
/* 样式区域：使用scoped避免样式污染 */
.user-profile {
  display: flex;
  align-items: center;
  gap: 16px;
  padding: 20px;
  background: #fff;
  border-radius: 8px;
}
</style>

// ✅ 推荐：完整的类型定义
interface Props {
  title: string
  count?: number
  items: Item[]
  config?: Partial<Config>
}
 
// ❌ 避免：缺少类型信息
const props = defineProps(['title', 'count', 'items'])

// ✅ 推荐：精确的事件定义
interface Emits {
  'item-click': [item: Item, index: number]
  'update:title': [value: string]
  'load-more': []
}
 
// ❌ 避免：模糊的emit定义
const emit = defineEmits(['click', 'update', 'load'])

// stores/user.ts
import { defineStore } from 'pinia'
import type { User, UserState } from '@/types/user'
import { userApi } from '@/api/modules/user'
 
export const useUserStore = defineStore('user', () => {
  // 状态定义
  const users = ref<User[]>([])
  const currentUser = ref<User | null>(null)
  const loading = ref(false)
  const error = ref<string | null>(null)
 
  // 计算属性
  const activeUsers = computed(() => 
    users.value.filter(user => user.isActive)
  )
  
  const userCount = computed(() => users.value.length)
 
  // 方法定义：按功能分组
  // 获取操作
  const getUserById = (id: string): User | undefined => {
    return users.value.find(user => user.id === id)
  }
 
  // 异步操作
  const fetchUsers = async (): Promise<void> => {
    loading.value = true
    error.value = null
    
    try {
      const response = await userApi.getUsers()
      users.value = response.data
    } catch (err) {
      error.value = err instanceof Error ? err.message : '获取用户失败'
      throw err
    } finally {
      loading.value = false
    }
  }
 
  // 修改操作
  const updateUser = async (user: User): Promise<void> => {
    const index = users.value.findIndex(u => u.id === user.id)
    if (index !== -1) {
      users.value[index] = { ...users.value[index], ...user }
    }
  }
 
  // 重置操作
  const resetStore = (): void => {
    users.value = []
    currentUser.value = null
    error.value = null
  }
 
  return {
    // 状态
    users: readonly(users),
    currentUser: readonly(currentUser),
    loading: readonly(loading),
    error: readonly(error),
    
    // 计算属性
    activeUsers,
    userCount,
    
    // 方法
    getUserById,
    fetchUsers,
    updateUser,
    resetStore
  }
})

// ✅ 推荐：集中管理状态
const userStore = useUserStore()
const { users, currentUser } = storeToRefs(userStore)
 
// ❌ 避免：重复定义状态
const localUsers = ref([]) // 与store中的状态重复

// ✅ 推荐：在store中处理异步逻辑
const fetchData = async () => {
  try {
    await store.fetchData()
  } catch (error) {
    // 统一错误处理
    showError(error)
  }
}
 
// ❌ 避免：在组件中分散处理
const fetchData = async () => {
  loading.value = true
  try {
    const data = await api.getData()
    localData.value = data
  } catch (error) {
    // 错误处理逻辑重复
  } finally {
    loading.value = false
  }
}

// .eslintrc.js
module.exports = {
  root: true,
  env: {
    node: true,
    browser: true,
    es2021: true
  },
  extends: [
    'eslint:recommended',
    '@vue/eslint-config-typescript',
    '@vue/eslint-config-prettier'
  ],
  parserOptions: {
    ecmaVersion: 2021,
    parser: '@typescript-eslint/parser'
  },
  rules: {
    // Vue特定规则
    'vue/multi-word-component-names': 'error',
    'vue/component-definition-name-casing': ['error', 'PascalCase'],
    'vue/component-name-in-template-casing': ['error', 'PascalCase'],
    'vue/html-self-closing': ['error', {
      html: {
        void: 'never',
        normal: 'always',
        component: 'always'
      }
    }],
    
    // TypeScript规则
    '@typescript-eslint/no-unused-vars': 'error',
    '@typescript-eslint/explicit-function-return-type': 'warn',
    
    // 通用规则
    'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    'no-debugger': process.env.NODE_ENV === 'production' ? 'warn' : 'off'
  }
}

// .prettierrc
{
  "semi": false,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 80,
  "arrowParens": "avoid",
  "endOfLine": "lf"
}

// 文件级注释：描述文件用途
/**
 * 用户管理相关工具函数
 * 提供用户数据的格式化、验证等操作
 * @module utils/user
 */
 
// 函数级注释：描述函数功能、参数、返回值
/**
 * 格式化用户显示名称
 * @param user - 用户对象
 * @param format - 显示格式，可选 'full' | 'short' | 'initial'
 * @returns 格式化后的用户名称
 * @example
 * formatUserName({ firstName: '张', lastName: '三' }, 'full') // '张三'
 * formatUserName({ firstName: '张', lastName: '三' }, 'short') // '张'
 */
export function formatUserName(
  user: User, 
  format: 'full' | 'short' | 'initial' = 'full'
): string {
  // 实现逻辑...
}
 
// 复杂逻辑注释：解释实现思路
// 使用二分查找优化搜索性能，时间复杂度从O(n)降低到O(log n)
const index = binarySearch(sortedArray, target)

<template>
  <!-- ✅ 频繁切换用v-show -->
  <div v-show="isVisible">频繁显示/隐藏的内容</div>
  
  <!-- ✅ 条件渲染用v-if -->
  <div v-if="hasData">数据存在时显示</div>
  
  <!-- ✅ 复杂条件用computed -->
  <div v-if="shouldShowComponent">复杂条件渲染</div>
</template>
 
<script setup>
// 复杂条件用computed缓存
const shouldShowComponent = computed(() => {
  return hasData.value && userHasPermission.value && !isLoading.value
})
</script>

<template>
  <!-- ✅ 使用key和合理的更新策略 -->
  <div v-for="item in optimizedList" :key="item.id">
    <list-item :item="item" />
  </div>
</template>
 
<script setup>
// 使用computed缓存过滤结果
const optimizedList = computed(() => {
  return rawList.value
    .filter(item => item.isActive)
    .sort((a, b) => b.createdAt - a.createdAt)
})
 
// 大数据列表使用虚拟滚动
const { list: virtualList } = useVirtualList(
  hugeDataList,
  { itemHeight: 60 }
)
</script>

// ✅ 路由级代码分割
const routes = [
  {
    path: '/dashboard',
    component: () => import('@/pages/Dashboard.vue')
  },
  {
    path: '/settings',
    component: () => import('@/pages/Settings.vue')
  }
]
 
// ✅ 组件级异步加载
const AsyncChart = defineAsyncComponent(() => 
  import('@/components/Chart/HeavyChart.vue')
)
 
// ✅ 条件异步加载
const HeavyComponent = computed(() => 
  showHeavyComponent.value 
    ? defineAsyncComponent(() => import('@/components/Heavy.vue'))
    : null
)

// stores/optimized.ts
export const useOptimizedStore = defineStore('optimized', () => {
  // 使用shallowRef避免深层响应式
  const hugeList = shallowRef([])
  
  // 使用computed缓存复杂计算
  const filteredList = computed(() => 
    hugeList.value.filter(item => item.isActive)
  )
  
  // 批量更新使用$patch
  const batchUpdate = (items) => {
    // ✅ 推荐：批量更新
    store.$patch(state => {
      items.forEach(item => {
        const index = state.list.findIndex(i => i.id === item.id)
        if (index !== -1) {
          state.list[index] = item
        }
      })
    })
    
    // ❌ 避免：逐个更新
    // items.forEach(item => {
    //   updateSingleItem(item)
    // })
  }
  
  return {
    hugeList: readonly(hugeList),
    filteredList
  }
})

// components/__tests__/UserProfile.spec.ts
import { describe, it, expect, vi } from 'vitest'
import { mount } from '@vue/test-utils'
import UserProfile from '../UserProfile.vue'
import { createPinia, setActivePinia } from 'pinia'
 
describe('UserProfile', () => {
  // 测试数据准备
  const mockUser = {
    id: '1',
    name: '张三',
    email: 'zhangsan@example.com',
    isActive: true
  }
  
  beforeEach(() => {
    // 初始化Pinia
    setActivePinia(createPinia())
  })
  
  it('应该正确渲染用户信息', () => {
    const wrapper = mount(UserProfile, {
      props: { userId: '1' },
      global: {
        stubs: {
          // 子组件打桩
          UserAvatar: true,
          UserInfo: true
        }
      }
    })
    
    expect(wrapper.find('.user-profile').exists()).toBe(true)
  })
  
  it('应该触发更新事件', async () => {
    const wrapper = mount(UserProfile, {
      props: { userId: '1' }
    })
    
    // 模拟用户更新
    await wrapper.vm.handleUpdate(mockUser)
    
    // 验证事件触发
    expect(wrapper.emitted('update')).toBeTruthy()
    expect(wrapper.emitted('update')![0]).toEqual([mockUser])
  })
  
  it('应该处理错误情况', async () => {
    const wrapper = mount(UserProfile, {
      props: { userId: 'invalid' }
    })
    
    // 模拟错误
    await wrapper.vm.handleUpdate(mockUser)
    
    // 验证错误处理
    expect(wrapper.vm.error).toBeTruthy()
  })
})

// tests/integration/user-management.spec.ts
import { describe, it, expect, beforeAll, afterAll } from 'vitest'
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import { createRouter, createWebHistory } from 'vue-router'
import App from '@/App.vue'
import { routes } from '@/router'
 
describe('用户管理集成测试', () => {
  let app: ReturnType<typeof createApp>
  let router: ReturnType<typeof createRouter>
  
  beforeAll(async () => {
    // 初始化应用
    app = createApp(App)
    router = createRouter({
      history: createWebHistory(),
      routes
    })
    
    app.use(createPinia())
    app.use(router)
    
    // 启动应用
    app.mount('#app')
    
    // 等待路由准备就绪
    await router.isReady()
  })
  
  afterAll(() => {
    // 清理资源
    app.unmount()
  })
  
  it('应该完成用户创建流程', async () => {
    // 导航到用户创建页面
    await router.push('/users/create')
    
    // 填写表单
    const formData = {
      name: '新用户',
      email: 'newuser@example.com',
      role: 'user'
    }
    
    // 提交表单并验证结果
    // ... 测试逻辑
    
    expect(currentRoute.value.path).toBe('/users')
  })
})

// 当你在TRAE IDE中编写代码时：
const userList = ref([])
const getUserData = async () => {
  const response = await fetch('/api/users')
  userList.value = response.data
}
 
// TRAE IDE智能体会提示：
// "⚠️ 检测到潜在问题：
// 1. 缺少错误处理机制
// 2. 建议添加loading状态管理
// 3. 响应数据未验证
// 
// ✅ 推荐改进："
const userList = ref([])
const loading = ref(false)
const error = ref<string | null>(null)
 
const getUserData = async () => {
  loading.value = true
  error.value = null
  
  try {
    const response = await fetch('/api/users')
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`)
    }
    const data = await response.json()
    
    // 数据验证
    if (Array.isArray(data)) {
      userList.value = data
    } else {
      throw new Error('Invalid data format')
    }
  } catch (err) {
    error.value = err instanceof Error ? err.message : '获取用户数据失败'
    console.error('Failed to fetch users:', err)
  } finally {
    loading.value = false
  }
}

// 原始代码：重复逻辑
const validateUserName = (name: string) => {
  if (name.length < 2) {
    return { valid: false, message: '用户名长度不能少于2个字符' }
  }
  if (name.length > 20) {
    return { valid: false, message: '用户名长度不能超过20个字符' }
  }
  if (!/^[a-zA-Z0-9_]+$/.test(name)) {
    return { valid: false, message: '用户名只能包含字母、数字和下划线' }
  }
  return { valid: true, message: '' }
}
 
// TRAE IDE重构建议：使用策略模式
interface ValidationRule {
  test: (value: string) => boolean
  message: string
}
 
const createValidator = (rules: ValidationRule[]) => {
  return (value: string) => {
    for (const rule of rules) {
      if (!rule.test(value)) {
        return { valid: false, message: rule.message }
      }
    }
    return { valid: true, message: '' }
  }
}
 
const validateUserName = createValidator([
  {
    test: name => name.length >= 2,
    message: '用户名长度不能少于2个字符'
  },
  {
    test: name => name.length <= 20,
    message: '用户名长度不能超过20个字符'
  },
  {
    test: name => /^[a-zA-Z0-9_]+$/.test(name),
    message: '用户名只能包含字母、数字和下划线'
  }
])

# 项目代码规范（自动生成）
 
## 组件命名规范
- 页面组件：PascalCase，以Page结尾（如UserListPage）
- 业务组件：PascalCase，具有明确业务含义（如ProductCard）
- 通用组件：PascalCase，以通用性命名（如DataTable、SearchInput）
 
## 状态管理规范
- 使用Pinia进行状态管理
- Store命名：use + 业务名称 + Store（如useProductStore）
- 状态修改必须通过store方法
- 异步操作统一在store中处理
 
## API调用规范
- 统一使用/api目录管理接口
- 按业务模块组织接口文件
- 响应数据必须进行类型验证
- 错误处理统一使用拦截器

"帮我创建一个Vue3 + TypeScript + Vite的项目，需要包含：
- 完整的ESLint + Prettier配置
- Pinia状态管理
- Vue Router路由
- 基于Element Plus的UI组件库
- 完善的目录结构
- 测试环境配置"

// 提交前的自动检查流程
const preCommitChecks = {
  // 代码格式检查
  formatting: () => runPrettier(),
  
  // 代码规范检查
  linting: () => runESLint(),
  
  // 类型检查
  typeChecking: () => runTypeScript(),
  
  // 单元测试
  unitTests: () => runVitest(),
  
  // 代码复杂度分析
  complexity: () => analyzeComplexity(),
  
  // 重复代码检测
  duplication: () => detectDuplication()
}
 
// 所有检查通过后，才允许提交代码