vue-composition-api-best-practices

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

版本兼容性

本技能面向 Vue 3.3+，部分功能需要更高的次版本号：

快速决策表

代码组织

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

TypeScript 与 Script Setup

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

Store 集成

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

组合式函数设计

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

响应性与性能

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

测试

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

速查表

SFC 代码组织顺序（11 步）

1. defineOptions     → 组件名称
2. defineProps       → Props 类型声明
3. defineModel       → 双向绑定（3.4+）
4. inject            → 注入依赖
5. defineEmits       → 事件类型声明
6. Store 声明         → useXxxStore()
7. 外部 hooks         → useI18n()、useDesign() 等
8. 功能声明           → const { ... } = useFeature()
9. provide           → 提供依赖
10. defineExpose     → 暴露公共 API
11. 功能实现          → function useFeature() {}

响应式 API 选择

基本类型       → ref
需要深层响应    → ref
大型对象/动态组件 → shallowRef
不需要重新赋值   → reactive（谨慎使用）
永不响应式      → markRaw + shallowRef

Store 访问规则

组件内 (<script setup>)  → useAppStore()
组件外 (hooks/utils/plugins) → useAppStoreWithOut()
解构保持响应式            → storeToRefs(store)

反模式 TOP 5

依赖模式速查