项目结构与最佳实践 #

src/
├── assets/              # 静态资源
│   ├── images/         # 图片
│   ├── styles/         # 全局样式
│   └── fonts/          # 字体
├── components/          # 公共组件
│   ├── common/         # 通用组件
│   ├── layout/         # 布局组件
│   └── ui/             # UI组件
├── composables/         # 组合式函数
├── directives/          # 自定义指令
├── layouts/             # 布局模板
├── router/              # 路由配置
│   ├── index.js
│   └── routes.js
├── stores/              # 状态管理
│   ├── index.js
│   ├── user.js
│   └── product.js
├── utils/               # 工具函数
│   ├── request.js      # 请求封装
│   ├── storage.js      # 存储封装
│   └── helpers.js      # 辅助函数
├── views/               # 页面组件
│   ├── home/
│   ├── user/
│   └── product/
├── App.vue
└── main.js

src/
├── modules/             # 功能模块
│   ├── user/
│   │   ├── components/
│   │   ├── composables/
│   │   ├── stores/
│   │   ├── views/
│   │   └── router.js
│   ├── product/
│   │   ├── components/
│   │   ├── composables/
│   │   ├── stores/
│   │   ├── views/
│   │   └── router.js
│   └── order/
├── shared/              # 共享资源
│   ├── components/
│   ├── composables/
│   ├── directives/
│   └── utils/
└── App.vue

<!-- ❌ 不推荐：组件职责过多 -->
<template>
  <div>
    <header>...</header>
    <nav>...</nav>
    <main>...</main>
    <footer>...</footer>
  </div>
</template>

<!-- ✅ 推荐：职责单一 -->
<template>
  <div>
    <AppHeader />
    <AppNav />
    <AppMain />
    <AppFooter />
  </div>
</template>

components/
├── common/              # 通用组件
│   ├── Button.vue
│   ├── Input.vue
│   └── Modal.vue
├── layout/              # 布局组件
│   ├── Header.vue
│   ├── Sidebar.vue
│   └── Footer.vue
├── business/            # 业务组件
│   ├── UserCard.vue
│   └── ProductList.vue
└── form/                # 表单组件
    ├── FormInput.vue
    └── FormSelect.vue

<!-- 组件名使用PascalCase -->
<UserCard />
<ProductList />

<!-- 多词命名避免冲突 -->
<BaseButton />
<AppHeader />

<!-- 组件文件命名 -->
components/
├── BaseButton.vue
├── UserCard.vue
└── ProductList.vue

composables/
├── useAuth.js           # 认证相关
├── useFetch.js          # 数据请求
├── useStorage.js        # 本地存储
├── useDebounce.js       # 防抖
└── useThrottle.js       # 节流

// composables/useFeature.js
import { ref, onMounted, onUnmounted } from 'vue'

export function useFeature(options = {}) {
  // 响应式状态
  const state = ref(null)
  const loading = ref(false)
  const error = ref(null)
  
  // 方法
  function doSomething() {
    // ...
  }
  
  // 生命周期
  onMounted(() => {
    // 初始化
  })
  
  onUnmounted(() => {
    // 清理
  })
  
  // 返回
  return {
    state,
    loading,
    error,
    doSomething
  }
}

// composables/useFetch.js
import { ref, toValue, watchEffect } from 'vue'

export function useFetch(url) {
  const data = ref(null)
  const error = ref(null)
  const loading = ref(false)
  
  async function fetchData() {
    loading.value = true
    error.value = null
    
    try {
      const response = await fetch(toValue(url))
      data.value = await response.json()
    } catch (e) {
      error.value = e
    } finally {
      loading.value = false
    }
  }
  
  watchEffect(() => {
    fetchData()
  })
  
  return { data, error, loading, refetch: fetchData }
}

// composables/useLocalStorage.js
import { ref, watch } from 'vue'

export function useLocalStorage(key, defaultValue) {
  const stored = localStorage.getItem(key)
  const data = ref(stored ? JSON.parse(stored) : defaultValue)
  
  watch(data, (newValue) => {
    localStorage.setItem(key, JSON.stringify(newValue))
  }, { deep: true })
  
  return data
}

<template>
  <!-- 模板内容 -->
</template>

<script setup>
// 1. 导入
import { ref, computed, onMounted } from 'vue'
import { useRouter } from 'vue-router'
import MyComponent from './MyComponent.vue'

// 2. Props和Emits
const props = defineProps({
  title: String
})

const emit = defineEmits(['update', 'delete'])

// 3. 响应式状态
const count = ref(0)
const loading = ref(false)

// 4. 计算属性
const doubled = computed(() => count.value * 2)

// 5. 方法
function increment() {
  count.value++
}

// 6. 生命周期
onMounted(() => {
  fetchData()
})

// 7. 暴露给模板引用
defineExpose({
  count,
  increment
})
</script>

<style scoped>
/* 样式 */
</style>

// 组件名：PascalCase
MyComponent.vue
UserCard.vue

// 组合式函数：use前缀
useAuth.js
useFetch.js

// 事件名：kebab-case
emit('update-user')
emit('delete-item')

// Props：kebab-case在模板中
<UserCard user-name="张三" />

// 变量名：camelCase
const userName = ref('')
const isLoading = ref(false)

// 常量：UPPER_SNAKE_CASE
const API_BASE_URL = '/api'
const MAX_RETRY_COUNT = 3

<script setup>
/**
 * 用户卡片组件
 * @description 显示用户信息卡片
 * @author Your Name
 */
import { ref } from 'vue'

// 用户数据
const user = ref({
  name: '',
  email: ''
})

/**
 * 获取用户数据
 * @param {number} id - 用户ID
 * @returns {Promise<void>}
 */
async function fetchUser(id) {
  // 实现逻辑
}
</script>

// 路由懒加载
const routes = [
  {
    path: '/about',
    component: () => import('./views/About.vue')
  }
]

// 组件懒加载
const AsyncComponent = defineAsyncComponent(() =>
  import('./components/HeavyComponent.vue')
)

<template>
  <!-- 跳过不必要的更新 -->
  <div v-memo="[selected]">
    <p>{{ item.name }}</p>
    <p>{{ selected ? '已选中' : '未选中' }}</p>
  </div>
</template>

<template>
  <VirtualList
    :items="largeList"
    :item-height="50"
  >
    <template #default="{ item }">
      <div class="item">{{ item.name }}</div>
    </template>
  </VirtualList>
</template>

<script setup>
import { ref, shallowRef, markRaw } from 'vue'

// 大型不可变数据使用shallowRef
const largeData = shallowRef({ /* ... */ })

// 不需要响应式的对象使用markRaw
const staticConfig = markRaw({
  apiUrl: '/api',
  timeout: 5000
})
</script>

// main.js
const app = createApp(App)

app.config.errorHandler = (err, instance, info) => {
  console.error('全局错误:', err)
  // 上报错误
  reportError(err)
}

app.config.warnHandler = (msg, instance, trace) => {
  console.warn('警告:', msg)
}

<template>
  <slot v-if="!error" />
  <div v-else class="error">
    {{ error.message }}
    <button @click="resetError">重试</button>
  </div>
</template>

<script setup>
import { ref, onErrorCaptured } from 'vue'

const error = ref(null)

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

function resetError() {
  error.value = null
}
</script>