vue-composition-api-best-practices

\r \r Vue 3 组合式 API 与 \x3Cscript setup>、TypeScript 集成及代码组织模式的最佳实践。\r \r

版本兼容性\r

\r 本技能面向 Vue 3.3+，部分功能需要更高的次版本号：\r \r | 特性 | 最低版本 | 参考 |\r |---------|:---:|---|\r | defineOptions | 3.3+ | script-setup |\r | toValue() | 3.3+ | script-setup |\r | defineModel | 3.4+ | script-setup |\r | watch 搭配 once 选项 | 3.4+ | reactivity |\r | useTemplateRef() | 3.5+ | script-setup |\r | useId() | 3.5+ | script-setup |\r | onWatcherCleanup() | 3.5+ | reactivity |\r \r

快速决策表\r

\r | 问题 | 参考阅读 |\r |---------|-------------|\r | 我的 \x3Cscript setup> 很乱，难以浏览 | SFC 代码组织 |\r | 某个功能的逻辑分散在很多行中 | useXxx 函数模式 |\r | 相同逻辑在多个组件中重复 | 功能提取 |\r | 两个功能相互影响，但不知道正确的处理模式 | 跨功能依赖 |\r | Props/emits 类型安全、defineModel 使用 | script setup 最佳实践 |\r | 在 hooks/工具函数/插件中无法访问 Store | 组件外 Store 访问 |\r | 如何组织新的组合式函数文件 | 组合式函数设计模式 |\r | 页面感觉慢，可能是响应性问题 | 响应性与性能 |\r | 如何测试组合式函数 | 组合式函数测试 |\r | 类型安全的 provide/inject | script setup - Provide/Inject |\r \r

代码组织\r

• SFC 代码缺乏清晰的组织结构 → 参见 sfc-code-organization\r
• 功能逻辑分散在脚本各处 → 参见 use-function-pattern\r
• 需要将可复用逻辑提取为组合式函数 → 参见 feature-extraction\r
• 跨功能依赖导致混乱 → 参见 cross-feature-dependencies\r \r

TypeScript 与 Script Setup\r

• 需要 script setup 的 TypeScript 最佳实践 → 参见 script-setup-best-practices\r \r

Store 集成\r

• 在 Vue 组件外部访问 Pinia store → 参见 store-without-pattern\r \r

组合式函数设计\r

• 设计健壮、可复用的组合式函数 → 参见 composable-design-patterns\r \r

响应性与性能\r

• 优化响应性以获得更好性能 → 参见 reactivity-performance\r \r

测试\r

• 使用 Vitest 测试组合式函数 → 参见 composable-design-patterns\r \r ---\r \r

速查表\r

\r

SFC 代码组织顺序（11 步）\r

\r

1. defineOptions     → 组件名称\r
2. defineProps       → Props 类型声明\r
3. defineModel       → 双向绑定（3.4+）\r
4. inject            → 注入依赖\r
5. defineEmits       → 事件类型声明\r
6. Store 声明         → useXxxStore()\r
7. 外部 hooks         → useI18n()、useDesign() 等\r
8. 功能声明           → const { ... } = useFeature()\r
9. provide           → 提供依赖\r
10. defineExpose     → 暴露公共 API\r
11. 功能实现          → function useFeature() {}\r
```\r
\r
### 响应式 API 选择\r
\r
```\r
基本类型       → ref\r
需要深层响应    → ref\r
大型对象/动态组件 → shallowRef\r
不需要重新赋值   → reactive（谨慎使用）\r
永不响应式      → markRaw + shallowRef\r
```\r
\r
### Store 访问规则\r
\r
```\r
组件内 (\x3Cscript setup>)  → useAppStore()\r
组件外 (hooks/utils/plugins) → useAppStoreWithOut()\r
解构保持响应式            → storeToRefs(store)\r
```\r
\r
### 反模式 TOP 5\r
\r
| # | 反模式 | 正确做法 |\r
|---|--------|---------|\r
| 1 | 解构 props → 丢失响应式 | `toRefs(props)` 或直接用 `props.xxx` |\r
| 2 | 组件外用 `useXxxStore()` | 用 `useXxxStoreWithOut()` |\r
| 3 | `ref` 用于动态组件/大对象 | 用 `shallowRef` |\r
| 4 | 混用 Options API + script setup | 只选一种风格 |\r
| 5 | 事件监听不清理 | `onUnmounted` 中移除 / 使用 VueUse 的 `useEventListener` |\r
\r
### 依赖模式速查\r
\r
| 场景 | 推荐模式 |\r
|------|---------|\r
| 父子组件通信 | Props + Emits |\r
| 兄弟功能交互 | 回调参数（`onXxxChange`） |\r
| 跨层级多对多 | 事件总线（`useEmitt`） |\r
| 共享状态 | Store 桥接组合式函数 |\r
| 功能编排 | 组合式函数编排模式 |\r