vue-best-practices

Vue 最佳实践工作流

将此技能用作一套指令。除非用户明确要求采用不同顺序，否则请按顺序执行此工作流。

核心原则

• 保持状态可预测： 只有一个事实来源，其余内容都由此派生。
• 明确数据流： 大多数情况下，Props 向下传递，Events 向上传递。
• 按职责拆分： 让每个实现专注于明确的职责，并明确实现之间的契约。
• 避免不必要的重新渲染： 谨慎使用计算属性和侦听器。
• 重视可读性： 编写清晰、易于理解的代码。

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

• 默认技术栈：Vue 3 + Composition API + <script setup lang="ts">。
• 如果项目明确使用 Options 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 职责、有状态工作流和 DOM 生命周期。梳理其归属方、使用方，以及协调所需的契约。
• 根据会共同变化的行为或共同维护的不变量来判断内聚性。同处一个页面、读取相同数据或只有一个使用方，本身都不足以成为放在同一个实现中的理由。
• 让根组件／路由组件组合各项功能并协调页面行为。对功能组件和组合式函数也要进行相同的职责审查；将整个功能移到子组件或 useFeature() 函数中，并不代表已完成合理拆分。
• 遵循项目现有布局，并根据受影响行为的范围确定设计规模。局部修复不需要绘制整个项目的组件图，也不需要新增架构层。

2) 应用 Vue 基础要点（必需）

以下是必备的核心基础知识。使用第 1.1 节中已加载的核心参考资料，在每项 Vue 任务中应用所有这些要点。

响应性

• 必须阅读第 1.1 节中的参考资料：响应性
• 尽量精简源状态（ref／reactive），尽可能使用 computed 派生其他内容。
• 如需执行副作用，请使用侦听器。
• 避免在模板中重复执行开销较大的逻辑。

SFC 结构和模板安全

• 必须阅读第 1.1 节中的参考资料：SFC
• 按以下顺序排列 SFC 部分：<script> → <template> → <style>。
• 保持 SFC 职责内聚；拆分时使用下方的边界标准。
• 保持模板声明式；将分支逻辑和派生逻辑移至脚本中。
• 遵循 Vue 模板安全规则（v-html、列表渲染和条件渲染的选择）。

选择有用的边界

• 提取职责明确、可分离的 UI 功能和有状态工作流，前提是这样能减少代码使用者或维护者需要理解的内容。只使用一次的组件和组合式函数也完全可行；并非必须复用。将 UI 职责所需的状态和事件处理保留在该 UI 中。
• 进行结构性重构时，为上述职责实现有用的边界。既要审视提取出来的部分，也要检查仍然放在一起的部分。较小的公共 API 可能掩盖仍需拆分的实现。
• 将文件长度、UI 区块数量和 API 大小视为审查信号，而非提取阈值。如果额外划分边界无法隐藏实质性的复杂度，就将规模较小且内聚的生产功能保留在一个 SFC 中。
• 如果拆分会增加大量转发或相互回调，应先将局部状态和 DOM 行为移到负责它们的 UI 中，再识别真正共享的依赖及其生命周期。视情况采用显式契约或作用域上下文。只有当边界已没有有用的封装职责时才合并，而不应仅仅为了减少连接代码而合并。
• 仅在输入构成内聚概念时才将它们组合起来。传递整个控制器、组合无关的处理程序或添加兜底事件，都无法减少使用者需要理解的依赖。

组件数据流

• 1.1 中的必读参考：component-data-flow
• 将 props 向下传递、事件向上冒泡作为主要模式。
• 仅当组件契约确实需要双向数据绑定时才使用 v-model。
• 如果中间组件只是转发依赖，则使用类型化、具备作用域的 provide/inject 来共享后代组件所需的依赖；应先重新评估组件边界。有关作用域和所有权，请参阅数据流参考。
• 根据需要使用 defineProps、defineEmits 和 InjectionKey，保持契约明确且类型化。

组合式函数

• 1.1 中的必读参考：composables
• 使用聚焦的能力组合实质性的有状态行为，包括有助于改善代码组织的单次使用工作流。简单的组件局部逻辑应保留在组件中；纯计算则使用普通函数。
• 区分实现的所有权与公共门面。协调器负责连接各项能力并实现跨能力操作；不应包含它们的全部实现，也不应重新导出所有内部内容。
• 返回供使用者使用的状态和操作。如果使用者需要互不相关的内部内容组，也应审视该使用者的职责。封装响应式簿记，让使用者可以读取当前值，而无需手动触发失效更新。
• 将 DOM 交互和清理工作保留给负责它们的 UI 或组合式函数。保留其他功能所需的显式协调，例如在保存前提交待处理的草稿。

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）结构和模板规则。
• 边界审查的两方面均已通过：实质上可分离的职责没有仍集中在一个实现中；提取出的单元能够隐藏有用的复杂性，而不只是转发调用。
• 公共契约有类型定义且隐藏内部实现。沿代码追踪一个有代表性的本地变更：它应留在负责该变更的 UI／工作流及合理的协调逻辑中，不应导致无关的转发修改。
• 状态的所有权和生命周期明确；共享使用方使用同一个预期实例，独立实例仍保持独立，副作用由其所有者负责清理。
• 重构保留现有行为，包括待处理工作和跨功能操作。使用项目适用的测试；仅减少 API 或文件大小并不能证明重构成功。
• 仅在需求要求时使用可选功能。
• 仅在功能完成后应用性能优化。