Vue 最佳实践

引言

Vue 3 作为现代前端框架的代表，以其简洁的 API 和强大的响应式系统赢得了开发者的青睐。然而，要充分发挥 Vue 的潜力，需要遵循一些最佳实践。本文将深入探讨 Vue 项目中的代码组织、命名规范、项目结构等关键方面，帮助你构建可维护、可扩展的 Vue 应用。

一、项目结构规范

1.1 推荐的目录结构

src/
├── assets/          # 静态资源
├── components/      # 通用组件
│   ├── common/      # 全局通用组件
│   └── features/    # 业务相关组件
├── composables/     # 组合式函数
├── views/           # 页面组件
├── stores/          # 状态管理
├── router/          # 路由配置
├── utils/           # 工具函数
├── types/           # TypeScript 类型定义
├── App.vue          # 根组件
└── main.ts          # 入口文件

1.2 代码示例

// main.ts
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'
import router from './router'

const app = createApp(App)

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

app.mount('#app')

二、组件设计原则

2.1 单一职责原则

每个组件应该只负责一个功能。避免创建"上帝组件"。

<!-- ❌ 不好的做法：组件过于庞大 -->
<template>
  <div>
    <h1>{{ user.name }}</h1>
    <p>{{ user.email }}</p>
    <button @click="handleEdit">编辑</button>
    <div v-if="showForm">
      <input v-model="formData.name" />
      <input v-model="formData.email" />
      <button @click="handleSubmit">保存</button>
    </div>
  </div>
</template>

<!-- ✅ 好的做法：拆分组件 -->
<template>
  <div>
    <UserProfile :user="user" @edit="handleEdit" />
    <EditForm v-if="showForm" :user="user" @submit="handleSubmit" />
  </div>
</template>

2.2 组件命名规范

使用 PascalCase 命名组件，文件名与组件名保持一致。

<!-- UserProfile.vue -->
<script setup lang="ts">
interface Props {
  user: {
    name: string
    email: string
  }
}

defineProps<Props>()
</script>

三、组合式 API 最佳实践

3.1 逻辑复用

使用组合式函数（Composables）来复用逻辑。

// composables/useUser.ts
import { ref, computed } from 'vue'

export function useUser() {
  const user = ref(null)
  const loading = ref(false)
  
  const userName = computed(() => user.value?.name || '匿名用户')
  
  const fetchUser = async () => {
    loading.value = true
    try {
      const res = await fetch('/api/user')
      user.value = await res.json()
    } finally {
      loading.value = false
    }
  }
  
  return {
    user,
    loading,
    userName,
    fetchUser
  }
}

<!-- 使用组合式函数 -->
<script setup lang="ts">
import { useUser } from '@/composables/useUser'

const { user, loading, userName, fetchUser } = useUser()

// 组件生命周期中调用
fetchUser()
</script>

<template>
  <div v-if="loading">加载中...</div>
  <div v-else>
    <h1>{{ userName }}</h1>
  </div>
</template>

3.2 响应式数据选择

合理使用 ref 和 reactive。

// ✅ 推荐：单个值使用 ref
const count = ref(0)

// ✅ 推荐：多个相关值使用 reactive
const user = reactive({
  name: '张三',
  email: 'zhangsan@example.com',
  age: 25
})

// ❌ 避免：对 reactive 对象使用解构
// 这会丢失响应性
const { name } = user  // name 不再是响应式

四、状态管理

4.1 Pinia 使用规范

// stores/user.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'

export const useUserStore = defineStore('user', () => {
  // State
  const user = ref(null)
  const token = ref('')
  
  // Getters
  const isLoggedIn = computed(() => !!token.value)
  const userName = computed(() => user.value?.name || '')
  
  // Actions
  const setUser = (userData) => {
    user.value = userData
  }
  
  const login = async (credentials) => {
    const res = await fetch('/api/login', {
      method: 'POST',
      body: JSON.stringify(credentials)
    })
    const data = await res.json()
    token.value = data.token
    user.value = data.user
  }
  
  const logout = () => {
    token.value = ''
    user.value = null
  }
  
  return {
    user,
    token,
    isLoggedIn,
    userName,
    setUser,
    login,
    logout
  }
})

五、性能优化

5.1 组件优化

<!-- 使用 v-memo 缓存组件 -->
<template>
  <div v-memo="[item.id, item.updatedAt]">
    {{ item.content }}
  </div>
</template>

<!-- 使用 v-once 静态内容 -->
<template>
  <div v-once>
    这个内容永远不会改变
  </div>
</template>

5.2 列表渲染优化

<!-- ✅ 始终为列表项添加 key -->
<template>
  <ul>
    <li v-for="item in items" :key="item.id">
      {{ item.name }}
    </li>
  </ul>
</template>

<!-- ❌ 避免使用 index 作为 key -->
<template>
  <li v-for="(item, index) in items" :key="index">
    {{ item.name }}
  </li>
</template>

六、错误处理

6.1 组件错误边界

<!-- ErrorBoundary.vue -->
<template>
  <div v-if="error">
    <h2>出错了</h2>
    <p>{{ error.message }}</p>
    <button @click="reset">重试</button>
  </div>
  <slot v-else />
</template>

<script setup lang="ts">
import { ref, onErrorCaptured } from 'vue'

const error = ref(null)

const reset = () => {
  error.value = null
}

onErrorCaptured((err) => {
  error.value = err
  return false  // 阻止错误继续传播
})
</script>

七、代码规范

7.1 ESLint 配置

使用 Vue 官方推荐的 ESLint 配置：

// .eslintrc.cjs
module.exports = {
  extends: [
    'plugin:vue/vue3-recommended',
    'eslint:recommended',
    '@vue/typescript/recommended'
  ],
  rules: {
    'vue/multi-word-component-names': 'off',
    'vue/no-unused-vars': 'error'
  }
}

7.2 命名规范

• 组件文件：PascalCase（UserProfile.vue）
• 组合式函数：use 前缀（useUser）
• 事件命名：v-on 风格（@click, @update:model-value）
• Props：camelCase（userName）

总结

遵循 Vue 最佳实践可以显著提升代码质量和开发效率。关键点包括：

1. 合理的项目结构 - 清晰的目录组织
2. 组件单一职责 - 小而专的组件
3. 组合式函数 - 逻辑复用
4. 状态管理 - 使用 Pinia
5. 性能优化 - 合理使用缓存和 key
6. 错误处理 - 完善的错误边界
7. 代码规范 - 统一的风格

记住，最佳实践不是教条，而是经验总结。根据项目实际情况灵活调整，保持代码的可读性和可维护性才是最重要的。

---