Pulse
ae39e45460
NOVAS SKILLS: - next-best-practices v0.1.0 (CLEAN) — Next.js App Router, RSC, caching, data - nextjs-patterns v1.0.0 (CLEAN) — Next.js 15: Server Actions, route handlers - vite v1.0.0 (CLEAN) — env vars, aliases, proxy, CJS compat - uncle-bob v1.0.0 (CLEAN) — Clean Code, SOLID, Clean Architecture - clean-code-review v1.0.0 (CLEAN) — naming, guard clauses, anti-patterns, refactoring - vue v1.0.0 (CLEAN) — Vue framework - vue-composition-api-best-practices v1.0.0 (CLEAN) — composables, Pinia, reactivity BIBLIOTECA INTELIGENTE libs/ (10 dominios, 11 arquivos): - typescript/ — TS safe + generics gotchas - react/ — Next.js App Router + Vite config - vue/ — Composition API + Pinia - linux/ — System diagnostic cheatsheet - database/ — PostgreSQL + MySQL patterns - browser/ — Chromium CLI + E2E testing - security/ — SAST audit (OWASP Top 10) - best-practices/ — Clean Code + SOLID + Clean Architecture - deploy/ — Docker multi-stack + OpenClaw ops - + INDEX.md como guia de navegacao .learnings/ — LRN-20260519-003 criado (biblioteca compartilhada)
120 lines
5.4 KiB
Markdown
120 lines
5.4 KiB
Markdown
---
|
||
name: vue-composition-api-best-practices
|
||
description: "Vue 3 组合式 API 与 <script setup> 最佳实践。涵盖代码组织、useXxx 模式、组合式函数设计、Store 集成、响应性优化及功能提取。"
|
||
license: MIT
|
||
metadata:
|
||
author: github.com/acanzaima
|
||
version: 1.0.0
|
||
tags: [vue3, composition-api, script-setup, typescript, pinia, composables, reactivity, performance]
|
||
---
|
||
|
||
Vue 3 组合式 API 与 `<script setup>`、TypeScript 集成及代码组织模式的最佳实践。
|
||
|
||
## 版本兼容性
|
||
|
||
本技能面向 **Vue 3.3+**，部分功能需要更高的次版本号：
|
||
|
||
| 特性 | 最低版本 | 参考 |
|
||
|---------|:---:|---|
|
||
| `defineOptions` | 3.3+ | [script-setup](reference/script-setup-best-practices.md) |
|
||
| `toValue()` | 3.3+ | [script-setup](reference/script-setup-best-practices.md) |
|
||
| `defineModel` | 3.4+ | [script-setup](reference/script-setup-best-practices.md) |
|
||
| `watch` 搭配 `once` 选项 | 3.4+ | [reactivity](reference/reactivity-performance.md) |
|
||
| `useTemplateRef()` | 3.5+ | [script-setup](reference/script-setup-best-practices.md) |
|
||
| `useId()` | 3.5+ | [script-setup](reference/script-setup-best-practices.md) |
|
||
| `onWatcherCleanup()` | 3.5+ | [reactivity](reference/reactivity-performance.md) |
|
||
|
||
## 快速决策表
|
||
|
||
| 问题 | 参考阅读 |
|
||
|---------|-------------|
|
||
| 我的 `<script setup>` 很乱，难以浏览 | [SFC 代码组织](reference/sfc-code-organization.md) |
|
||
| 某个功能的逻辑分散在很多行中 | [useXxx 函数模式](reference/use-function-pattern.md) |
|
||
| 相同逻辑在多个组件中重复 | [功能提取](reference/feature-extraction.md) |
|
||
| 两个功能相互影响，但不知道正确的处理模式 | [跨功能依赖](reference/cross-feature-dependencies.md) |
|
||
| Props/emits 类型安全、`defineModel` 使用 | [script setup 最佳实践](reference/script-setup-best-practices.md) |
|
||
| 在 hooks/工具函数/插件中无法访问 Store | [组件外 Store 访问](reference/store-without-pattern.md) |
|
||
| 如何组织新的组合式函数文件 | [组合式函数设计模式](reference/composable-design-patterns.md) |
|
||
| 页面感觉慢，可能是响应性问题 | [响应性与性能](reference/reactivity-performance.md) |
|
||
| 如何测试组合式函数 | [组合式函数测试](reference/composable-design-patterns.md#9-testing-composables) |
|
||
| 类型安全的 `provide`/`inject` | [script setup - Provide/Inject](reference/script-setup-best-practices.md#provideinject-with-typescript) |
|
||
|
||
### 代码组织
|
||
- SFC 代码缺乏清晰的组织结构 → 参见 [sfc-code-organization](reference/sfc-code-organization.md)
|
||
- 功能逻辑分散在脚本各处 → 参见 [use-function-pattern](reference/use-function-pattern.md)
|
||
- 需要将可复用逻辑提取为组合式函数 → 参见 [feature-extraction](reference/feature-extraction.md)
|
||
- 跨功能依赖导致混乱 → 参见 [cross-feature-dependencies](reference/cross-feature-dependencies.md)
|
||
|
||
### TypeScript 与 Script Setup
|
||
- 需要 script setup 的 TypeScript 最佳实践 → 参见 [script-setup-best-practices](reference/script-setup-best-practices.md)
|
||
|
||
### Store 集成
|
||
- 在 Vue 组件外部访问 Pinia store → 参见 [store-without-pattern](reference/store-without-pattern.md)
|
||
|
||
### 组合式函数设计
|
||
- 设计健壮、可复用的组合式函数 → 参见 [composable-design-patterns](reference/composable-design-patterns.md)
|
||
|
||
### 响应性与性能
|
||
- 优化响应性以获得更好性能 → 参见 [reactivity-performance](reference/reactivity-performance.md)
|
||
|
||
### 测试
|
||
- 使用 Vitest 测试组合式函数 → 参见 [composable-design-patterns](reference/composable-design-patterns.md#9-testing-composables)
|
||
|
||
---
|
||
|
||
## 速查表
|
||
|
||
### 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
|
||
|
||
| # | 反模式 | 正确做法 |
|
||
|---|--------|---------|
|
||
| 1 | 解构 props → 丢失响应式 | `toRefs(props)` 或直接用 `props.xxx` |
|
||
| 2 | 组件外用 `useXxxStore()` | 用 `useXxxStoreWithOut()` |
|
||
| 3 | `ref` 用于动态组件/大对象 | 用 `shallowRef` |
|
||
| 4 | 混用 Options API + script setup | 只选一种风格 |
|
||
| 5 | 事件监听不清理 | `onUnmounted` 中移除 / 使用 VueUse 的 `useEventListener` |
|
||
|
||
### 依赖模式速查
|
||
|
||
| 场景 | 推荐模式 |
|
||
|------|---------|
|
||
| 父子组件通信 | Props + Emits |
|
||
| 兄弟功能交互 | 回调参数（`onXxxChange`） |
|
||
| 跨层级多对多 | 事件总线（`useEmitt`） |
|
||
| 共享状态 | Store 桥接组合式函数 |
|
||
| 功能编排 | 组合式函数编排模式 |
|