vue-development

Vue 开发

概述

使用 TypeScript、Composition API 和用户行为测试进行现代 Vue 3 开发。**核心原则：**使用 TypeScript 泛型（而非运行时验证）、现代 API（使用 defineModel，而非手动定义 props），并测试用户行为（而非实现细节）。

危险信号——停止并修正

如果你发现自己有以下任何想法或行为，请立即停止：

• “为了快点”／“快速演示”／“紧急情况” → 使用捷径
• “之后再整理” → 接受糟糕的模式
• “TypeScript 太啰嗦了” → 跳过类型
• “这已经可以用于生产环境了” → 却没有类型安全保障
• “遵循现有代码风格” → 但现有代码使用的是旧模式
• “任务明确要求……” → 机械照搬糟糕的要求
• 使用 const props = defineProps()，却未在脚本中使用 props
• 手动定义 modelValue prop + update:modelValue emit → 使用 defineModel()
• “接收 value 并触发变更的组件” → 使用 defineModel()，而非手动定义 props/emit
• TypeScript 可用时仍使用运行时 prop 验证
• 使用数组语法定义 emit：defineEmits(['event']) → 缺少类型安全保障
• 在测试中使用 setTimeout() → 使用合适的异步工具
• 测试 wrapper.vm.* 内部状态 → 测试用户可见的行为
• 在路由中使用 index.vue → 使用路由组 (name).vue
• 使用通用路由参数 [id] → 使用明确的参数名，如 [userId]、[postSlug]
• 在组合式函数中调用 showToast()、alert() 或模态框 → 暴露错误状态，由组件处理 UI
• 外部组合式函数只在一个组件中使用 → 先内联，复用时再提取

以上情况都意味着：使用现代模式，不得例外。

快速规则

**组件：**使用 defineProps<{ }>()（除非在脚本中使用，否则不要赋给 const）、defineEmits<{ event: [args] }>()，以及用于 v-model 的 defineModel<type>()。参见 @references/component-patterns.md

**测试：**使用 @testing-library/vue + MSW。异步操作使用 findBy* 或 waitFor()。绝不要使用 setTimeout() 或测试内部状态。参见 @references/testing-patterns.md

**路由：**使用明确的参数名 [userId]，而非 [id]。避免使用 index.vue，改用 (name).vue。使用 . 表示嵌套：users.edit.vue → /users/edit。参见 @references/routing-patterns.md

**组合式函数：**组件专属逻辑先内联，复用时再提取到外部文件。外部组合式函数：前缀使用 use，不包含 UI 逻辑（改为暴露错误状态）。参见 @references/composable-patterns.md

核心模式：defineModel()

最重要的模式——所有双向绑定都要使用：

<script setup lang="ts">
// ✅ For simple v-model
const value = defineModel<string>({ required: true })

// ✅ For multiple v-models
const firstName = defineModel<string>('firstName')
const lastName = defineModel<string>('lastName')
</script>

<template>
  <input v-model="value" />
  
</template>

**原因：**将 5 行样板代码缩减为 1 行。无需手动定义 modelValue prop + update:modelValue emit。

组件实现工作流

实现复杂的 Vue 组件时，使用 TodoWrite 跟踪进度：

TodoWrite checklist for component implementation:
- [ ] Define TypeScript interfaces for props/emits/models
- [ ] Implement props with defineProps<{ }>() (no const unless used in script)
- [ ] Implement emits with defineEmits<{ event: [args] }>()
- [ ] Add v-model with defineModel<type>() if needed
- [ ] Write user-behavior tests with Testing Library
- [ ] Test async behavior with findBy* queries or waitFor()
- [ ] Verify: No red flags, no setTimeout in tests, all types present

适合创建 TodoWrite 待办事项的情形：

• 实现具有状态、v-model 和测试的新组件
• 将组件重构为现代模式
• 添加带类型参数的路由
• 创建包含异步逻辑的组合式函数

合理化借口对照表

借口	事实
“为了速度／应急／没时间”	正确的模式耗时相同。TypeScript 本身很快。
“TypeScript 太啰嗦了”	defineProps<{ count: number }>() 代码更少。
“之后再整理就行”	一开始就写对。
“这已经可以用于生产环境了”	没有类型安全，就不能用于生产环境。
“简单的数组语法没问题”	缺少类型 = 运行时错误，而 TypeScript 能捕获这些错误。
“手动处理 modelValue 才是正确的”	那是 Vue 2 的做法。在 Vue 3.4+ 中使用 defineModel()。
“测试不稳定，加个超时就好”	超时会掩盖错误。正确处理异步操作。
“遵循现有的代码风格”	旧代码确实存在。使用现代模式加以改进。
“任务明确要求了 X”	理解意图。糟糕的需求也需要良好的实现。
“组合式函数可以显示提示消息”	UI 应由组件负责。公开错误状态。
“[id] 是行业标准”	明确的名称可以避免错误，并启用 TypeScript 自动补全。
“counter.ts 没问题”	必须加上 'use' 前缀：useCounter.ts
“test-utils 是标准做法”	Testing Library 是测试用户行为的黄金标准。

详细参考资料

全面指南请参阅 @references/ 目录：component-patterns.md、testing-patterns.md、testing-composables.md、routing-patterns.md、composable-patterns.md

不适合使用此技能的情况

• Vue 2 项目（API 不同）
• 使用 Options API 的代码库（本技能专注于 Composition API）
• 不使用 TypeScript 的项目（不过应该添加 TypeScript）

实际影响

基准： 压力之下，正确使用模式的比例为 37.5% 使用此技能后： 压力之下，正确使用模式的比例为 100%

类型安全可防止运行时错误。defineModel() 可减少样板代码。Testing Library 能发现真实的用户问题。