Vue3开发规范与代码风格指南

构建Vue3项目时，规范的目录结构和代码风格能显著提升团队协作效率。本文将详细介绍从项目架构到组件封装的完整开发范式。

目录结构

my-vue3-project/
├── src/
│   ├── assets/                      # 静态资源（图片、字体等）
│   ├── components/
│   │   ├── common/                  # 通用UI组件（跨项目复用，无业务逻辑）
│   │   │   └── BaseButton.vue
│   │   └── biz/                     # 通用业务组件（跨页面复用，含业务逻辑）
│   │       └── BizUserCard.vue
│   ├── composables/                 # 组合式函数（可复用的状态逻辑）
│   │   └── useUser.ts
│   ├── layouts/                     # 布局组件（页面整体结构）
│   │   ├── default.vue
│   │   └── components/              # 布局专用组件（仅布局层使用）
│   │       └── AppHeader.vue
│   ├── pages/                       # 页面组件（路由对应，kebab-case命名）
│   │   ├── user-profile.vue
│   │   └── user/                    # 页面模块
│   │       ├── list.vue
│   │       └── components/          # 页面专用组件（仅当前模块使用）
│   │           └── UserFilter.vue
│   ├── router/                      # 路由配置（管理页面路由）
│   │   ├── index.ts
│   │   └── user-routes.ts
│   ├── stores/                      # Pinia状态管理（全局共享状态）
│   │   └── userStore.ts
│   ├── services/                    # API服务层（封装后端接口调用）
│   │   └── userService.ts
│   ├── utils/                       # 工具函数（纯函数，无副作用）
│   │   ├── formatDate.ts
│   │   └── validateEmail.ts
│   ├── types/                       # TypeScript类型定义（接口、枚举等）
│   │   ├── User.ts
│   │   └── api.ts
│   ├── styles/                      # 全局样式（变量、混入、重置样式）
│   │   └── global.scss
│   ├── App.vue
│   └── main.ts
├── tests/
│   └── unit/                        # 单元测试（与src目录结构对应）
│       ├── components/
│       └── utils/
└── package.json

文件命名规则

类型	规则	示例	说明
通用UI组件	Base + PascalCase	BaseButton.vue	无业务逻辑，纯UI
通用业务组件	Biz + PascalCase	BizUserCard.vue	跨页面复用，含业务
布局组件	App + PascalCase	AppHeader.vue	仅布局层使用
页面文件	kebab-case	user-profile.vue	与路由路径一致
页面专用组件	PascalCase	UserFilter.vue	仅当前模块使用
组合式函数	use + camelCase	useUser.ts	逻辑复用
Store	camelCase + Store	userStore.ts	全局状态
Service	camelCase + Service	userService.ts	API封装
工具函数	camelCase	formatDate.ts	纯函数
类型定义	PascalCase	User.ts	接口/枚举
测试文件	源文件名 + .spec.ts	BaseButton.spec.ts	单元测试

组件编写

组件分类与命名

组件类型	目录	命名规则	示例
通用UI组件	components/common/	Base + PascalCase	BaseButton.vue
通用业务组件	components/biz/	Biz + PascalCase	BizUserCard.vue
布局组件	layouts/components/	App + PascalCase	AppHeader.vue
页面专用组件	pages/xxx/components/	PascalCase	UserFilter.vue

单文件组件结构

<script setup lang="ts">
// 1. 类型导入
import type { UserInfo } from '@/types/User'// 2. 第三方库
import { ElMessage } from 'element-plus'// 3. 组件导入
import BaseButton from '@/components/common/BaseButton.vue'// 4. 工具/组合式函数
import { useUser } from '@/composables/useUser'// 5. Props
interface Props {
  userId: string
  title?: string
}
const props = withDefaults(defineProps<Props>(), {
  title: '默认'
})// 6. Emits
const emit = defineEmits<{
  (e: 'update', user: UserInfo): void
}>()// 7. 响应式数据
const loading = ref(false)// 8. 计算属性
const displayName = computed(() => user.value?.name)// 9. 方法
async function fetchUser() {}// 10. 生命周期
onMounted(() => {})// 11. 暴露
defineExpose({ refresh: fetchUser })
script><template>
  
  <BaseButton @click="handleClick" />
  <el-button type="primary" />
template><style scoped lang="scss">
// BEM命名
.user-card {
  &__header {}
  &--active {}
}
style>

模板使用规则

组件类型	模板中写法	示例
自定义组件	PascalCase
第三方UI库	kebab-case
原生HTML	小写

组合式函数模板

// composables/useCounter.ts
export function useCounter(initialValue = 0) {
  const count = ref(initialValue)
  const doubled = computed(() => count.value * 2)  function increment() { count.value++ }
  function reset() { count.value = initialValue }  return { count, doubled, increment, reset }
}

状态管理与 API 服务

Store 规范（Pinia）

文件树示例

stores/
├── userStore.ts
├── cartStore.ts
└── productStore.ts

模板

// stores/userStore.ts
import { defineStore } from 'pinia'export const useUserStore = defineStore('user', {
  state: () => ({ 
    name: '', 
    isLoggedIn: false 
  }),
  
  getters: { 
    displayName: (state) => state.name || '游客' 
  },
  
  actions: {
    async login(email: string, password: string) {
      // 登录逻辑
    },
    logout() { 
      this.$reset() 
    }
  }
})

组件中使用

<script setup>
import { storeToRefs } from 'pinia'
import { useUserStore } from '@/stores/userStore'const userStore = useUserStore()
// 状态用 storeToRefs 解构保持响应性
const { name, displayName } = storeToRefs(userStore)
// actions 直接解构
const { login, logout } = userStore
script>

---

Service 规范

文件树示例

services/
├── userService.ts
├── productService.ts
└── api/
    ├── client.ts       # axios实例配置
    └── interceptors.ts # 拦截器

模板

// services/userService.ts
import request from './api/client'
import type { UserInfo, LoginParams } from '@/types/User'export const userService = {
  async getUser(id: string): Promise<UserInfo> {
    const { data } = await request.get(`/api/users/${id}`)
    return data
  },
  
  async login(params: LoginParams): Promise<{ token: string }> {
    const { data } = await request.post('/api/users/login', params)
    return data
  }
}

工具函数与类型定义

工具函数规范

文件树示例

utils/
├── formatDate.ts       # 日期格式化
├── formatCurrency.ts   # 货币格式化
├── validateEmail.ts    # 邮箱验证
└── storage.ts          # 本地存储封装

模板

// utils/formatDate.ts
export function formatDate(date: Date, format = 'YYYY-MM-DD'): string {
  const d = new Date(date)
  const year = d.getFullYear()
  const month = String(d.getMonth() + 1).padStart(2, '0')
  const day = String(d.getDate()).padStart(2, '0')
  
  return format
    .replace('YYYY', String(year))
    .replace('MM', month)
    .replace('DD', day)
}// utils/validateEmail.ts
export function validateEmail(email: string): boolean {
  const emailRegex = /^[^s@]+@([^s@.,]+.)+[^s@.,]{2,}$/
  return emailRegex.test(email)
}

---

类型定义规范

文件树示例

types/
├── User.ts             # 用户相关类型
├── Product.ts          # 商品相关类型
├── api.ts              # API通用类型
└── global.d.ts         # 全局类型声明

模板

// types/User.ts
export interface UserInfo {
  id: string
  name: string
  email: string
  role: UserRole
}export enum UserRole { 
  Admin = 'admin', 
  User = 'user' 
}// types/api.ts
export interface ApiResponseunknown> {
  code: number
  message: string
  data: T
}

使用方式

//  正确：使用 type 关键字导入纯类型
import type { UserInfo } from '@/types/User'//  正确：枚举需要值导入
import { UserRole } from '@/types/User'

测试规范

文件树示例

tests/unit/
├── components/
│   ├── common/
│   │   └── BaseButton.spec.ts
│   └── biz/
│       └── BizUserCard.spec.ts
├── composables/
│   └── useCounter.spec.ts
├── stores/
│   └── userStore.spec.ts
├── services/
│   └── userService.spec.ts
└── utils/
    └── formatDate.spec.ts

组件测试模板

// tests/unit/components/common/BaseButton.spec.ts
import { mount } from '@vue/test-utils'
import BaseButton from '@/components/common/BaseButton.vue'describe('BaseButton', () => {
  it('renders correctly', () => {
    const wrapper = mount(BaseButton, { 
      slots: { default: 'Click' } 
    })
    expect(wrapper.text()).toBe('Click')
  })  it('emits click event when clicked', async () => {
    const wrapper = mount(BaseButton)
    await wrapper.trigger('click')
    expect(wrapper.emitted('click')).toBeTruthy()
  })
})

组合式函数测试模板

// tests/unit/composables/useCounter.spec.ts
import { useCounter } from '@/composables/useCounter'describe('useCounter', () => {
  it('initializes with default value', () => {
    const { count } = useCounter()
    expect(count.value).toBe(0)
  })  it('increments count correctly', () => {
    const { count, increment } = useCounter(5)
    increment()
    expect(count.value).toBe(6)
  })
})

工具函数测试模板

// tests/unit/utils/formatDate.spec.ts
import { formatDate } from '@/utils/formatDate'describe('formatDate', () => {
  it('formats date with default format', () => {
    const date = new Date(2024, 0, 15)
    expect(formatDate(date)).toBe('2024-01-15')
  })  it('formats date with custom format', () => {
    const date = new Date(2024, 0, 15)