vue-master

name	vue-master
description	Vue 3 开发主技能，包含开发规范并协调 Vue 相关子技能。适用于所有 Vue 3 项目开发，提供标准化的开发流程和最佳实践指导。
license	MIT
metadata	{"author":"MiMoCode","version":"1.0.0"}

Vue 3 开发规范

页面拆分

1. 不同路由/功能必须拆分到独立的 .vue 文件，严禁所有代码写在一个文件里。
2. 一个页面文件只负责一个主要业务场景。

组件提取

• 出现以下情况，必须拆分为独立组件：
  • 同一段模板/逻辑在 2 处以上使用。
  • 单个文件超过 300 行（不含样式）。
  • 包含独立业务逻辑（如表单、弹窗、列表项）。
• 通用组件放 src/components，业务组件放页面目录下的 components/ 文件夹。

文件行数限制

• Vue 文件（模板 + 脚本）建议 ≤ 400 行，1000 行是底线，超过必须拆分。
• 样式超过 200 行建议拆分到独立 .scss / .css 文件。

JS/TS 语法规范

• 全面使用 ES6+ 语法（const/let、箭头函数、解构、模板字符串、async/await），禁止 var。
• 使用 === / !==，避免 == / !=。

组合式 API (Composition API)

• <script setup lang="ts"> 组合式 API
• 超过 20 行的响应式逻辑（如状态、方法、生命周期）应抽离到 composables/ 目录下的独立 .ts 文件。
• 纯工具函数放到 utils/ 目录。

响应式与类型

• 使用 ref 处理基本类型，reactive 处理对象/数组。
• Props 和 Emits 必须显式声明类型（TypeScript 项目）。

样式规范

• 必须使用 scoped 或 CSS Modules，避免样式泄露。
• 全局样式只在 src/styles 中定义。

错误处理

• 所有异步操作（onMounted、用户点击触发的 API 请求）必须包含 try/catch。
• 关键用户操作要有加载状态和错误提示。

注释要求

• 复杂组件（超过 150 行）顶部写一段注释说明：用途、主要 Props、关键事件。
• Composables 文件必须有文件头注释说明返回值。

相关技能

核心技能

• vue-best-practices - Vue 3 + Composition API + TypeScript 最佳实践，包含响应式、SFC 结构、组件拆分等核心指导
• vue-pinia-best-practices - Pinia 状态管理最佳实践，包含 Store 设置、响应式、状态模式
• vue-router-best-practices - Vue Router 4 最佳实践，包含导航守卫、路由参数、生命周期

辅助技能

• vue-testing-best-practices - Vue 测试最佳实践，包含 Vitest、Vue Test Utils、Playwright E2E 测试
• vue-jsx-best-practices - JSX 在 Vue 中的使用，包含与 React JSX 的语法差异
• vue-debug-guides - Vue 3 调试指南，包含运行时错误、警告、异步错误处理、水合问题
• create-adaptable-composable - 创建可复用的 composables，包含 MaybeRef/MaybeRefOrGetter 输入模式

使用指南

技能加载顺序

1. 进行 Vue 开发时，首先加载本技能 (vue-master)
2. 根据具体需求加载相关子技能：
   • 日常开发：加载 vue-best-practices
   • 状态管理：加载 vue-pinia-best-practices
   • 路由开发：加载 vue-router-best-practices
   • 编写测试：加载 vue-testing-best-practices
   • 调试问题：加载 vue-debug-guides

开发流程

1. 需求分析：明确功能需求和组件边界
2. 架构设计：规划组件结构、数据流、状态管理
3. 编码实现：遵循开发规范，使用 Composition API
4. 测试验证：编写单元测试和集成测试
5. 代码审查：检查是否符合规范和最佳实践

代码质量检查清单

• 组件是否遵循单一职责原则
• 文件行数是否在限制范围内
• 是否使用 TypeScript 类型声明
• 异步操作是否有错误处理
• 样式是否使用 scoped 或 CSS Modules
• 是否遵循响应式最佳实践