vue3-component-decomposition

Vue 3 组件拆分

将大型 Vue 3 组件拆分为更小、可测试的单元，同时保持可读性。

适用场景

• 组件处理多项职责（UI 渲染、数据获取、表单逻辑、筛选、副作用）
• setup() 或 <script setup> 变得难以浏览
• 模板包含复杂表达式或重复代码块
• 某项功能的改动经常导致无关行为出错

拆分流程

1. 移动代码前梳理各项职责：
   • view（标记语言／展示）
   • state（refs/reactive/computed）
   • effects（watch/watchEffect/生命周期）
   • io（API 调用）
2. 优先提取展示型子组件。
3. 明确父子组件之间的接口（props、emits、slots）。
4. 将可复用的有状态逻辑提取到组合式函数中。
5. 让父组件负责协调数据流和组合各项功能。

组件最佳实践

• 每个文件只放一个组件，并使用多词组件名称。
• 保持模板表达式简单；将复杂表达式移至计算值中。
• 在 v-for 中使用 :key，并避免在同一元素上同时使用 v-if 和 v-for。
• 使用类型明确的 props 契约和类型化的 emits。
• 对可变 UI 区域，优先使用 slots，避免布尔 props 泛滥。
• 子组件专注于一项 UI 职责。

组合式函数最佳实践

• 组合式函数使用 use 前缀命名（useOrdersTable、useUserFilters）。
• 返回包含 refs/computed/方法的普通对象，以便解构时保留响应性。
• 接受响应式输入（值/ref/getter），并使用 toValue() 进行规范化。
• 如果逻辑依赖响应式输入，请在 watchEffect() 中调用 toValue()（或直接监听 refs/getters）。
• 在 onMounted() 中执行 DOM 副作用，并始终在 onUnmounted() 中清理。
• 除非有意构建共享状态，否则避免使用隐藏的全局可变状态。

建议的结构

src/
  components/
    feature/
      OrdersPage.vue               # orchestrator
      OrdersToolbar.vue            # presentational controls
      OrdersTable.vue              # table rendering
      OrdersTableRow.vue           # row rendering
  composables/
    useOrdersQuery.ts              # fetch/pagination/sort
    useOrdersFilters.ts            # filter state and derived query
    useOrdersSelection.ts          # row selection logic

注意事项

• 不要提取没有独立价值的微小包装组件。
• 不要创建“全能型组合式函数”；应按业务能力拆分。
• 不要将整个父组件状态传给子组件；只传递必需的 props。
• 不要在展示型组件中混入业务逻辑。

PR 检查清单

• 父组件体现的是功能协调，而不是实现细节的堆砌。
• 子组件 API 清晰，且可以独立理解。
• 组合式函数职责集中，返回结构可预测。
• 副作用已清理，且兼容 SSR。
• 模板复杂度降低，并且测试可以针对更小的单元编写。

参考资料

• Vue 文档：Composables - https://vuejs.org/guide/reusability/composables.html
• Vue 风格指南（已过时，但仍有参考价值）：
  • https://vuejs.org/style-guide/rules-essential.html
  • https://vuejs.org/style-guide/rules-strongly-recommended.html