Kenhuang Academy
  • English

      • Vue.js Best Practices

      Code organization

      1. Use composition API

      <!-- ✅ 推荐：组合式 API -->
<script setup>
import { ref, computed } from 'vue'

const count = ref(0)
const doubleCount = computed(() => count.value * 2)

function increment() {
  count.value++
}
</script>

<!-- ❌ 不推荐：选项式 API（除非维护旧项目） -->
<script>
export default {
  data() {
    return { count: 0 }
  },
  computed: {
    doubleCount() {
      return this.count * 2
    }
  }
}
</script>

      2. Component naming

      <!-- ✅ 推荐：PascalCase -->
<script setup>
import UserProfile from './UserProfile.vue'
import TodoList from './TodoList.vue'
</script>

<template>
  <UserProfile />
  <TodoList />
</template>

<!-- ❌ 不推荐：kebab-case 或单词 -->
<template>
  <user-profile />
  <profile />
</template>

      3. File structure

      src/
├── assets/          # 静态资源
├── components/      # 通用组件
│   ├── common/      # 基础组件
│   ├── layout/      # 布局组件
│   └── business/    # 业务组件
├── composables/     # 组合式函数
├── stores/          # Pinia stores
├── router/          # 路由配置
├── views/           # 页面组件
├── utils/           # 工具函数
├── api/             # API 接口
├── types/           # TypeScript 类型
└── App.vue

      Component design

      1. Single responsibility principle

      <!-- ✅ 推荐：职责单一 -->
<script setup>
// UserAvatar.vue - 只负责显示头像
defineProps({
  src: String,
  size: { type: String, default: 'medium' }
})
</script>

<!-- ❌ 不推荐：职责过多 -->
<script setup>
// UserCard.vue - 包含太多功能
// 头像、个人信息、操作按钮、统计数据...
</script>

      2. Props verification

      <script setup>
// ✅ 推荐：完整的 props 验证
defineProps({
  title: {
    type: String,
    required: true
  },
  count: {
    type: Number,
    default: 0,
    validator: (value) => value >= 0
  },
  status: {
    type: String,
    default: 'pending',
    validator: (value) => ['pending', 'success', 'error'].includes(value)
  }
})

// ❌ 不推荐：没有验证
defineProps(['title', 'count', 'status'])
</script>

      3. Event naming

      <script setup>
// ✅ 推荐：使用 kebab-case
const emit = defineEmits(['update:modelValue', 'item-selected', 'form-submit'])

// ❌ 不推荐：使用 camelCase
const emit = defineEmits(['updateModelValue', 'itemSelected'])
</script>

      Responsive data

      1. Use ref and reactive

      <script setup>
import { ref, reactive } from 'vue'

// ✅ 推荐：基本类型用 ref
const count = ref(0)
const message = ref('Hello')

// ✅ 推荐：对象用 reactive
const user = reactive({
  name: '张三',
  age: 25
})

// ❌ 不推荐：对象用 ref（需要 .value.property）
const user = ref({
  name: '张三',
  age: 25
})
// user.value.name = '李四'  // 繁琐
</script>

      2. Avoid directly modifying props

      <script setup>
const props = defineProps(['count'])

// ❌ 不推荐：直接修改 props
function increment() {
  props.count++  // 错误！
}

// ✅ 推荐：使用本地状态
const localCount = ref(props.count)
function increment() {
  localCount.value++
}

// ✅ 推荐：触发事件
const emit = defineEmits(['update:count'])
function increment() {
  emit('update:count', props.count + 1)
}
</script>

      Computed properties and listeners

      1. Computed properties should be pure functions

      <script setup>
import { ref, computed } from 'vue'

const items = ref([1, 2, 3, 4, 5])

// ✅ 推荐：纯函数，无副作用
const evenItems = computed(() => {
  return items.value.filter(item => item % 2 === 0)
})

// ❌ 不推荐：有副作用
const evenItems = computed(() => {
  console.log('Computing...')  // 副作用
  someGlobalVariable = 123     // 副作用
  return items.value.filter(item => item % 2 === 0)
})
</script>

      2. Avoid modifying the listened value in the listener

      <script setup>
import { ref, watch } from 'vue'

const count = ref(0)

// ❌ 不推荐：可能导致无限循环
watch(count, (newValue) => {
  count.value = newValue + 1  // 危险！
})

// ✅ 推荐：修改其他值
const doubleCount = ref(0)
watch(count, (newValue) => {
  doubleCount.value = newValue * 2
})
</script>

      Template Best Practices

      1. Provide key when using v-for

      <template>
  <!-- ✅ 推荐：使用唯一 key -->
  <div v-for="item in items" :key="item.id">
    {{ item.name }}
  </div>
  
  <!-- ❌ 不推荐：使用索引作为 key（列表会变化时） -->
  <div v-for="(item, index) in items" :key="index">
    {{ item.name }}
  </div>
</template>

      2. Avoid using v-if and v-for at the same time

      <template>
  <!-- ❌ 不推荐：v-if 和 v-for 在同一元素 -->
  <div v-for="item in items" v-if="item.isActive" :key="item.id">
    {{ item.name }}
  </div>
  
  <!-- ✅ 推荐：使用计算属性过滤 -->
  <div v-for="item in activeItems" :key="item.id">
    {{ item.name }}
  </div>
</template>

<script setup>
import { computed } from 'vue'

const activeItems = computed(() => {
  return items.value.filter(item => item.isActive)
})
</script>

      3. Use concise template expressions

      <template>
  <!-- ❌ 不推荐：复杂的模板表达式 -->
  <div>
    {{ user.firstName + ' ' + user.lastName + ' (' + user.age + ' years old)' }}
  </div>
  
  <!-- ✅ 推荐：使用计算属性 -->
  <div>{{ userDisplayName }}</div>
</template>

<script setup>
import { computed } from 'vue'

const userDisplayName = computed(() => {
  return `${user.firstName} ${user.lastName} (${user.age} years old)`
})
</script>

      Performance optimization

      1. Use v-show vs v-if

      <template>
  <!-- ✅ 频繁切换使用 v-show -->
  <div v-show="isVisible">频繁切换的内容</div>
  
  <!-- ✅ 很少改变使用 v-if -->
  <div v-if="isLoggedIn">登录后才显示</div>
</template>

      2. Lazy loading of components

      <script setup>
import { defineAsyncComponent } from 'vue'

// ✅ 推荐：懒加载大型组件
const HeavyComponent = defineAsyncComponent(() =>
  import('./HeavyComponent.vue')
)

// ❌ 不推荐：同步导入所有组件
import HeavyComponent from './HeavyComponent.vue'
</script>

      3. Use v-memo

      <template>
  <!-- ✅ 缓存不常变化的列表项 -->
  <div v-for="item in list" :key="item.id" v-memo="[item.selected]">
    <!-- 只有 item.selected 变化时才重新渲染 -->
    {{ item.name }}
  </div>
</template>

      Combined functions

      1. Naming Convention

      // ✅ 推荐：use 开头
export function useCounter() {
  const count = ref(0)
  const increment = () => count.value++
  return { count, increment }
}

// ❌ 不推荐：没有 use 前缀
export function counter() {
  // ...
}

      2. Return responsive object

      // ✅ 推荐：返回 ref
export function useCounter() {
  const count = ref(0)
  return { count }
}

// ❌ 不推荐：返回普通值
export function useCounter() {
  let count = 0
  return { count }  // 不是响应式的
}

      Error handling

      1. Global error handling

      // main.js
app.config.errorHandler = (err, instance, info) => {
  console.error('Global error:', err)
  // 发送到错误监控服务
}

      2. Component error boundary

      <script setup>
import { onErrorCaptured } from 'vue'

onErrorCaptured((err, instance, info) => {
  console.error('Component error:', err)
  // 返回 false 阻止错误继续传播
  return false
})
</script>

      TypeScript Best Practices

      1. Define types for props

      <script setup lang="ts">
interface Props {
  title: string
  count?: number
  items: Array<{ id: number; name: string }>
}

const props = withDefaults(defineProps<Props>(), {
  count: 0
})
</script>

      2. Define the type for emits

      <script setup lang="ts">
interface Emits {
  (e: 'update:modelValue', value: string): void
  (e: 'submit', data: FormData): void
}

const emit = defineEmits<Emits>()
</script>

      Styling Best Practices

      1. Use scoped style

      <style scoped>
/* ✅ 推荐：scoped 样式不会影响其他组件 */
.button {
  background-color: blue;
}
</style>

      2. Use CSS variables

      <style scoped>
.component {
  --primary-color: #42b983;
  --spacing: 16px;
  
  color: var(--primary-color);
  padding: var(--spacing);
}
</style>

      3. Avoid depth selector abuse

      <style scoped>
/* ❌ 不推荐：过度使用深度选择器 */
:deep(.child .grandchild .great-grandchild) {
  color: red;
}

/* ✅ 推荐：在子组件中定义样式 */
.child {
  color: red;
}
</style>

      Testing Best Practices

      1. Test user behavior

      // ✅ 推荐：测试用户行为
it('should increment count when button is clicked', async () => {
  const wrapper = mount(Counter)
  await wrapper.find('button').trigger('click')
  expect(wrapper.text()).toContain('Count: 1')
})

// ❌ 不推荐：测试实现细节
it('should call increment method', () => {
  const wrapper = mount(Counter)
  const spy = vi.spyOn(wrapper.vm, 'increment')
  expect(spy).toHaveBeenCalled()
})

      2. Use test ID

      <template>
  <button data-testid="submit-btn">提交</button>
</template>
      it('should submit form', async () => {
  const wrapper = mount(Form)
  await wrapper.find('[data-testid="submit-btn"]').trigger('click')
  // ...
})

      Security Best Practices

      1. Avoid XSS attacks

      <template>
  <!-- ✅ 推荐：自动转义 -->
  <div>{{ userInput }}</div>
  
  <!-- ❌ 危险：v-html 可能导致 XSS -->
  <div v-html="userInput"></div>
  
  <!-- ✅ 如果必须使用 v-html，先清理内容 -->
  <div v-html="sanitizedInput"></div>
</template>

<script setup>
import DOMPurify from 'dompurify'

const sanitizedInput = computed(() => {
  return DOMPurify.sanitize(userInput.value)
})
</script>

      2. Environment variable security

      // ❌ 不推荐：在客户端暴露敏感信息
const API_KEY = 'secret-key-123'

// ✅ 推荐：敏感信息放在服务端
// 客户端只使用公开的环境变量
const API_URL = import.meta.env.VITE_API_URL

      Code review checklist

      Components

      • ✅ Component names use PascalCase
      • ✅ Props are fully typed and verified
      • ✅ Events are named using kebab-case
      • ✅ Components have single responsibility
      • ✅ Use scoped style

      Performance

      • ✅ Use lazy loading for large components
      • ✅ List uses unique key
      • ✅ Avoid using v-if and v-for at the same time
      • ✅ Use computed attribute cache appropriately
      • ✅ Images use lazy loading

      Code quality

      • ✅ No console.log
      • ✅ No unused variables
      • ✅ Uniform code format
      • ✅ There are necessary comments
      • ✅ Passed ESLint check

      Test

      • ✅ Key functions are covered by tests
      • ✅ Test user behavior rather than implementation
      • ✅ Test edge cases
      • ✅ Mock external dependencies

      Summarize

      • Use combined APIs and<script setup>
      • Follow naming conventions and file structure
      • Props validation and type definition
      • Proper use of computed properties and listeners
      • Pay attention to performance optimization -Write testable code
      • Pay attention to safety issues
      • Keep code clean and maintainable

      Next step

      Finally, learn Learning Resources to learn more about Vue learning resources.