Vue 最佳实践工作流

将此技能视为一套指令集。除非用户明确要求不同的顺序，否则请按顺序遵循工作流。

核心原则

• 保持状态可预测：单一数据源，其他所有状态都由此派生。
• 使数据流明确：大多数情况下，属性向下传递，事件向上传递。
• 倾向于小型、专注的组件：更易于测试、复用和维护。
• 避免不必要的重新渲染：明智地使用计算属性和侦听器。
• 可读性至关重要：编写清晰、自我说明的代码。

1) 编码前确认架构（必需）

• 默认技术栈：Vue 3 + 组合式 API + <script setup lang="ts">。
• 如果项目明确使用选项式 API，请加载 vue-options-api-best-practices 技能（如果可用）。
• 如果项目明确使用 JSX，请加载 vue-jsx-best-practices 技能（如果可用）。

1.1 必须阅读的核心参考文档（必需）

• 在实现任何 Vue 任务之前，确保阅读并应用以下核心参考文档：
  • references/reactivity.md
  • references/sfc.md
  • references/component-data-flow.md
  • references/composables.md
• 在整个任务过程中，将这些参考文档保留在活跃的工作上下文中，而不仅仅是当特定问题出现时才查阅。

1.2 编码前规划组件边界（必需）

对于任何非平凡的功能，在实现前创建一个简短的组件映射图。

• 用一句话定义每个组件的单一职责。
• 默认情况下，保持入口/根组件和路由级视图组件作为组合表面。
• 将功能 UI 和功能逻辑移出入口/根/视图组件，除非任务本身就是一个极小的单文件演示。
• 在映射图中为每个子组件定义属性/事件约定。
• 当添加多个组件时，优先采用特性文件夹布局（components/<feature>/..., composables/use<Feature>.ts）。

2) 应用基本的 Vue 基础（必需）

这些是必需掌握的基本基础。使用已在章节 1.1 中加载的核心参考文档，在每个 Vue 任务中应用所有这些基础。

响应式

• 必须阅读来自 1.1 的参考文档：reactivity
• 保持源状态最小化（ref/reactive），尽可能使用 computed 派生所有内容。
• 需要时使用侦听器处理副作用。
• 避免在模板中重新计算开销大的逻辑。

SFC 结构和模板安全

• 必须阅读来自 1.1 的参考文档：sfc
• 保持 SFC 各部分的顺序为：<script> → <template> → <style>。
• 保持 SFC 职责专注；拆分大型组件。
• 保持模板声明式；将分支/派生逻辑移至脚本中。
• 应用 Vue 模板安全规则（v-html、列表渲染、条件渲染选择）。

保持组件专注

当一个组件具有 多于一个明确的职责（例如，数据编排 + UI，或多个独立的 UI 部分）时，对其进行拆分。

• 倾向于 更小的组件 + 组合式函数，而不是一个“巨型组件”
• 将 UI 部分 移入子组件（属性传入，事件传出）。
• 将 状态/副作用 移入组合式函数（useXxx()）。

应用客观的拆分触发条件。如果满足 任一 条件，则拆分组件：

• 组件同时拥有多个部分的编排/状态和大量表现性标记。
• 组件拥有 3 个或以上不同的 UI 部分（例如：表单、过滤器、列表、页脚/状态）。
• 某个模板块被重复使用或可能变得可复用（如项目行、卡片、列表条目）。

入口/根组件和路由视图组件规则：

• 保持入口/根组件和路由视图组件精简：仅负责应用外壳/布局、提供者连接和特性组合。
• 当特性包含独立部分时，不要将完整的特性实现放在入口/根/视图组件中。
• 对于 CRUD/列表特性（如待办事项、表格、目录、收件箱），至少拆分为：
  • 特性容器组件
  • 输入/表单组件
  • 列表（和/或项目）组件
  • 页脚/操作 或 过滤器/状态组件
• 仅对于非常小的、可丢弃的演示，才允许使用单文件实现；如果选择这种方式，需明确说明为何无需拆分。

组件数据流

• 必须阅读来自 1.1 的参考文档：component-data-flow
• 使用“属性向下传递，事件向上传递”作为主要模型。
• 仅在组件间确实需要双向绑定时使用 v-model。
• 仅对深层树依赖或共享上下文使用 provide/inject。
• 使用 defineProps、defineEmits 和必要的 InjectionKey 使组件间的约定明确并带有类型。

组合式函数

• 必须阅读来自 1.1 的参考文档：composables
• 当逻辑可复用、涉及状态或副作用较重时，将其提取到组合式函数中。
• 保持组合式函数的 API 小巧、类型明确且可预测。
• 将特性逻辑与表现性组件分离。

3) 仅在需求需要时考虑可选特性

3.1 标准可选特性

默认不要添加这些。仅当存在相关需求时，才加载对应的参考文档。

• 插槽：父组件需要控制子组件的内容/布局 -> component-slots
• 透传属性：包装器/基础组件必须安全地转发属性和事件 -> component-fallthrough-attrs
• 内置组件 <KeepAlive> 用于有状态的视图缓存 -> component-keep-alive
• 内置组件 <Teleport> 用于叠加层/传送门 -> component-teleport
• 内置组件 <Suspense> 用于异步子树的后备边界 -> component-suspense
• 动画相关特性：选择最符合所需动效行为的简单方法。
  • 内置组件 <Transition> 用于进入/离开效果 -> transition
  • 内置组件 <TransitionGroup> 用于列表变化的动画 -> transition-group
  • 基于类的动画，用于非进入/离开效果 -> animation-class-based-technique
  • 状态驱动的动画，用于由用户输入驱动的动画 -> animation-state-driven-technique

3.2 不太常见的可选特性

仅在存在明确的产品或技术需求时使用这些特性。

• 指令：行为是 DOM 特定的，且不适合用组合式函数/组件实现 -> directives
• 异步组件：体积大/不常用的 UI 应懒加载 -> component-async
• 仅在模板无法表达需求时使用渲染函数 -> render-functions
• 插件：当行为需要在应用范围内安装时 -> plugins
• 状态管理模式：当应用范围的共享状态跨越了特性边界 -> state-management

4) 在行为正确后进行性能优化

性能优化是在功能实现之后的步骤。在核心行为实现并验证之前，不要进行优化。

• 大型列表渲染瓶颈 -> perf-virtualize-large-lists
• 静态子树不必要地重新渲染 -> perf-v-once-v-memo-directives
• 热路径列表中过度抽象 -> perf-avoid-component-abstraction-in-lists
• 昂贵的更新触发过于频繁 -> updated-hook-performance

5) 完成前的最终自查

• 核心行为正常工作并符合要求。
• 所有必须阅读的参考文档都已阅读并应用。
• 响应式模型最小且可预测。
• SFC 结构和模板规则已遵循。
• 组件专注且结构良好，必要时进行了拆分。
• 入口/根组件和路由视图组件保持为组合表面，除非有明确的小型演示例外。
• 组件拆分决策明确且有依据（职责边界清晰）。
• 数据流约定明确且带有类型。
• 在复用/复杂性需要的地方使用了组合式函数。
• 如果适用，已将状态/副作用移入组合式函数。
• 仅在需求需要时使用了可选特性。
• 性能优化仅在功能完成后应用。