protagonistss/vue3-best-practices

Vue 3 Best Practices

🌟 技能核心

本技能指导开发者编写 模块化、类型安全、高性能 的 Vue 3 应用。

核心原则：

• Composition API First
• 逻辑复用 (Composables)
• 类型推导优先
• 单一数据流

---

📁 推荐项目结构

src/
├── assets/              # 静态资源
├── components/          # 通用组件
│   ├── ui/              # 基础 UI 组件
│   └── business/        # 业务组件
├── composables/         # 组合式函数 (use*.ts)
├── stores/              # Pinia stores
├── views/               # 页面组件
├── router/              # 路由配置
├── types/               # TypeScript 类型定义
├── utils/               # 工具函数
├── api/                 # API 请求封装
└── App.vue

命名规范： | 类型 | 规范 | 示例 | |------|------|------| | 组件 | PascalCase | UserProfile.vue | | Composables | camelCase + use 前缀 | useAuth.ts | | Stores | camelCase + Store 后缀 | userStore.ts | | 工具函数 | camelCase | formatDate.ts |

---

🧠 核心原则

1. Script Setup 与 Composition API

<script setup lang="ts">
// ✅ 推荐：显式导入，利于代码阅读和依赖追踪
import { ref, computed, watch, onMounted } from 'vue'
import { useUserStore } from '@/stores/userStore'

// 顶层 await 支持
const data = await fetchInitialData()

// 响应式状态
const count = ref(0)
const doubled = computed(() => count.value * 2)

// Store 使用
const userStore = useUserStore()
</script>

要点：

• 默认使用 <script setup lang="ts">，更简洁，运行时性能更好
• 支持顶层 await
• 显式导入 ref, computed, watch 等（而非依赖自动导入）

2. 响应式数据 (Reactivity)

| 场景 | 推荐 | 原因 | |------|------|------| | 基本类型 | ref | 清晰的 .value 访问 | | 对象/数组（默认） | reactive | 更直观；解构需 toRefs | | 需要整体替换/可空对象 | ref | 便于赋新对象与类型约束 | | 深层嵌套大对象 | reactive | 仅当不解构时使用 | | 大型外部实例 | shallowRef | 避免不必要的深度响应 |

// ✅ 推荐
const user = ref<User | null>(null)
user.value = { name: 'John' }

// ⚠️ 谨慎使用 reactive
const state = reactive({ items: [] })
// 解构会丢失响应性！
const { items } = state // ❌ items 不再是响应式

// ✅ 使用 toRefs 解构
const { items } = toRefs(state)

3. 组件通信

Props 定义（带默认值）

// Vue 3.5+ 推荐写法
const { title, count = 0 } = defineProps<{
  title: string
  count?: number
}>()

// Vue 3.4 及以下
const props = withDefaults(defineProps<{
  title: string
  count?: number
}>(), {
  count: 0
})

注意：解构式 props 需要 Vue 3.5+（或编译选项 propsDestructure: true）。否则解构结果非响应式，建议使用 withDefaults 或保留 props.xxx 访问。

Emits 定义

const emit = defineEmits<{
  change: [id: number]
  update: [value: string]
}>()

// 使用
emit('change', 123)

v-model（Vue 3.4+）

// 简化双向绑定
const modelValue = defineModel<string>()
const count = defineModel<number>('count', { default: 0 })

Slots 类型化

defineSlots<{
  default: (props: { item: Item }) => any
  header: () => any
}>()

Expose

// 暴露给父组件的方法/属性
defineExpose({
  focus: () => inputRef.value?.focus(),
  reset
})

4. 组件命名 (defineOptions)

递归组件、调试、DevTools 中必须显式命名：

defineOptions({
  name: 'TreeNode',      // 递归组件必须
  inheritAttrs: false    // 禁用属性自动透传
})

何时需要命名： | 场景 | 必要性 | |------|--------| | 递归组件 | ⭐ 必须 | | DevTools 调试 | 推荐 | | KeepAlive include/exclude | 必须 | | Transition 组件 | 推荐 |

5. 属性透传 (inheritAttrs)

<script setup lang="ts">
defineOptions({ inheritAttrs: false })

// 获取透传的属性
const attrs = useAttrs()
</script>

<template>
  <!-- 手动绑定到内部元素 -->
  <div class="wrapper">
    <input v-bind="attrs" />
  </div>
</template>

6. 泛型组件（Vue 3.3+）

<script setup lang="ts" generic="T extends { id: number }">
defineProps<{
  items: T[]
  selected?: T
}>()

const emit = defineEmits<{
  select: [item: T]
}>()
</script>

---

🧩 逻辑复用 (Composables)

基本模式

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

export function useCounter(initial = 0) {
  const count = ref(initial)
  const doubled = computed(() => count.value * 2)

  function increment() {
    count.value++
  }

  function reset() {
    count.value = initial
  }

  return {
    count,
    doubled,
    increment,
    reset
  }
}

带异步请求的 Composable

// composables/useFetch.ts
import { ref, shallowRef, watchEffect, toValue, type MaybeRefOrGetter } from 'vue'

export function useFetch<T>(url: MaybeRefOrGetter<string>) {
  const data = shallowRef<T | null>(null)
  const error = shallowRef<Error | null>(null)
  const loading = ref(false)

  async function execute() {
    loading.value = true
    error.value = null
    try {
      const res = await fetch(toValue(url))
      data.value = await res.json()
    } catch (e) {
      error.value = e as Error
    } finally {
      loading.value = false
    }
  }

  watchEffect(() => {
    execute()
  })

  return { data, error, loading, refresh: execute }
}

注意：MaybeRefOrGetter/toValue 需要 Vue 3.3+。低版本可用 unref 或改为仅接收 Ref。

最佳实践：

• ✅ 以 use 开头命名
• ✅ 返回对象包含响应式状态和方法
• ✅ 优先使用 VueUse 已有工具
• ❌ 不要在 Composable 中使用 this

---

📦 状态管理 (Pinia)

Setup Store（推荐）

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

export const useUserStore = defineStore('user', () => {
  // State
  const user = ref<User | null>(null)
  const token = ref('')

  // Getters
  const isLoggedIn = computed(() => !!token.value)
  const displayName = computed(() => user.value?.name ?? 'Guest')

  // Actions
  async function login(credentials: LoginDTO) {
    const res = await api.login(credentials)
    user.value = res.user
    token.value = res.token
  }

  function logout() {
    user.value = null
    token.value = ''
  }

  return {
    user,
    token,
    isLoggedIn,
    displayName,
    login,
    logout
  }
})

要点：

• 优先使用 Setup Store，与组件写法一致
• State 保持扁平化
• Getters = computed
• Actions 处理同步/异步逻辑

---

🚫 反模式对照表

| ❌ 错误做法 | ✅ 正确做法 | |-------------|-------------| | 使用 Mixins | 使用 Composables | | const { prop } = props 解构 | props.prop 或 toRefs(props) | | 在 setup 中写 created 逻辑 | 直接写在 setup 顶层 | | 忘记 .value | 始终在 script 中使用 .value | | reactive 后解构 | 使用 ref 或 toRefs | | Options API 混用 | 统一使用 Composition API |

---

⚡ 性能优化

| 技术 | 场景 | 示例 | |------|------|------| | v-memo | 大型列表/表格 | v-memo="[item.id, item.selected]" | | shallowRef | 大型外部实例 | 地图、图表实例 | | KeepAlive | 缓存组件 | 标签页切换 | | 路由懒加载 | 所有路由 | () => import('./Page.vue') | | defineAsyncComponent | 条件渲染组件 | 模态框、抽屉 |

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

// 异步组件
const HeavyModal = defineAsyncComponent(() => 
  import('./HeavyModal.vue')
)

---

🛠️ 技术栈推荐

| 分类 | 推荐 | |------|------| | 构建工具 | Vite | | 路由 | Vue Router 4 | | 状态管理 | Pinia | | UI 组件库 | Element Plus / Naive UI / Ant Design Vue | | 样式方案 | UnoCSS / Tailwind CSS | | 测试 | Vitest + Vue Test Utils | | 工具库 | VueUse |

---

🔄 迁移指南：Options → Composition

| Options API | Composition API | |-------------|-----------------| | data() | ref() / reactive() | | computed: {} | computed() | | methods: {} | 普通函数 | | watch: {} | watch() / watchEffect() | | created | <script setup> 顶层代码 | | mounted | onMounted() | | this.xxx | 直接访问变量 |

---

🐛 常见错误排查

| 问题 | 原因 | 解决 | |------|------|------| | 数据不更新 | 忘记 .value | 检查 ref 访问 | | 解构后不响应 | reactive 解构 | 使用 toRefs() | | computed 不执行 | 未访问 .value | 确保访问响应式依赖 | | watch 不触发 | 监听了原始值 | 使用 getter 函数 | | Props 类型错误 | 缺少类型定义 | 添加泛型类型 |

---

📂 示例文件

本技能包含以下完整示例，位于 examples/ 目录：

| 文件 | 说明 | |------|------| | component-example.vue | 递归树形组件，展示 defineOptions 命名、插槽透传 | | composable-example.ts | usePagination 分页逻辑封装 | | store-example.ts | Pinia Setup Store 完整示例 |

---

🎨 常用指令示例

# 生成 Composable
/vue-coder 提取这段逻辑为一个名为 usePagination 的 Composable 函数。

# 转换 Options API
/vue-coder 将这个 Options API 组件重构为 <script setup lang="ts"> 写法。

# 优化响应式
/vue-coder 检查这段代码中 reactive 的使用是否合理，建议改为 ref。

# 添加类型
/vue-coder 为这个组件的 props 和 emits 添加完整的 TypeScript 类型。

# 性能优化
/vue-coder 分析这个列表组件的性能问题，建议优化方案。