当前位置：首页 > news >正文

[特殊字符] Vue3 项目最佳实践：组件命名、目录结构与类型规范指南

news 2025/11/7 11:02:11

在实际项目开发中，随着业务的扩大和团队成员的增多，代码结构混乱、命名不统一、文件职责不清晰的问题常常让人头疼。
本文基于大量 Vue3 + TypeScript 项目的经验，整理出一套可扩展、清晰且易维护的项目架构与命名规范。

🧩 一、组件命名规范

组件命名不仅影响可读性，也直接决定了后续维护和复用的便捷性。

✅ 组件文件命名

文件名：使用 PascalCase（首字母大写的驼峰命名）
示例：UserProfile.vue、ProductCard.vue
页面文件：页面级组件同样使用 PascalCase
示例：Main.vue、UserCenter.vue
组件引用：推荐使用 <UserProfile /> 而不是 <user-profile />（更贴近类式语义）

💡 二、变量与函数命名规范

良好的变量命名让逻辑更加直观统一。

类型	规则	示例
普通变量	camelCase（小驼峰）	`userName`、`isVisible`、`currentIndex`
常量	UPPER_SNAKE_CASE（大写下划线）	`MAX_COUNT`、`API_BASE_URL`
组合式函数	以 `use` 开头	`useCounter`、`useAuth`、`useUserInfo`

🧱 三、枚举与类型定义规范

类型定义是 TypeScript 项目的核心，合理的组织结构能让类型清晰且易于维护。

🔖 枚举定义

在 src/types/enums.ts 中集中定义全局枚举。

// src/types/enums.ts
export enum UserStatus {ACTIVE = 'active',INACTIVE = 'inactive',PENDING = 'pending',
}export enum ThemeType {LIGHT = 'light',DARK = 'dark',
}

🧾 类型定义

不同业务模块应独立定义类型文件。

// src/types/user.ts
export interface User {id: numbername: stringstatus: UserStatus
}// src/types/api.ts
export interface ApiResponse<T> {code: numberdata: Tmessage: string
}

🗂️ 四、目录组织结构规范

清晰的目录结构是大型项目的基础。
下面是一份推荐的 Vue3 + TS 工程结构：

/
├── env.d.ts                 # 全局类型声明文件
├── formula.config.ts        # Formula 配置文件
├── tsconfig.json            # 主 TypeScript 配置
├── tsconfig-formulaConfig.json # Formula 子配置
└── src/├── index.ts             # 应用入口├── config/              # 应用配置│   ├── http.config.ts│   ├── routes.config.ts│   └── auth.config.ts├── pages/               # 页面组件│   └── Main.vue├── components/          # 公共组件├── composables/         # 组合式函数├── services/            # 业务逻辑 API 层│   ├── common/          # 公共 API│   ├── user/            # 用户模块│   ├── product/         # 产品模块│   └── index.ts         # API 统一导出├── enums/               # 枚举定义（与 services 同结构）├── assets/              # 静态资源（样式、图片等）├── types/               # 类型定义└── layout/              # 布局文件

📘 五、文件职责说明

目录	说明
`config/`	存放项目配置（HTTP、路由、权限等）
`pages/`	路由级页面组件
`components/`	通用组件（可跨模块使用）
`composables/`	组合式函数（封装逻辑与状态）
`services/`	按业务模块划分的 API 层
`enums/`	与 services 对应的枚举集合
`assets/`	样式、图标、图片等静态资源
`types/`	类型定义与接口声明
`layout/`	页面布局结构

🧠 六、命名与文件实例

// src/enums/common/status.ts
export enum LoadingStatus {IDLE = 'idle',LOADING = 'loading',SUCCESS = 'success',ERROR = 'error',
}// src/enums/user/user.ts
export enum UserStatus {ACTIVE = 'active',PENDING = 'pending',
}// src/services/common/upload.api.ts
export const uploadFile = (file: File) => http.post('/upload', file)// src/services/user/user.api.ts
export const getUserList = () => http.get('/users')
export const getUserProfile = (id: string) => http.get(`/users/${id}`)