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

在实际项目开发中，随着业务的扩大和团队成员的增多，代码结构混乱、命名不统一、文件职责不清晰的问题常常让人头疼。

本文基于大量 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: number
  name: string
  status: UserStatus
}

// src/types/api.ts
export interface ApiResponse<T> {
  code: number
  data: T
  message: 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}`)

🧭 七、架构优化建议

命名统一化

确保模块、文件、类型、常量的命名风格一致，避免混乱。
目录平衡化

模块层级不宜过深，3 层以内最为合适（如：services/user/user.api.ts）。
类型与枚举分离

不将类型定义与接口请求混在一个文件中，保持单一职责。
API 层统一导出

在 services/index.ts 中集中导出所有模块 API，方便全局引入与管理。
组合式逻辑模块化

公共逻辑尽量封装为 useXxx，保持组件简洁。

🏁 八、总结

这套规范注重「一致性、可扩展性、低耦合 」三大核心原则。

对于中大型 Vue3 + TypeScript 项目，能有效提高团队协作效率与代码质量。

📦 通过合理的命名与目录设计，项目的维护成本将大幅降低。

⚙️ 搭配 ESLint + Prettier 可进一步保障规范落地。

💬 觉得有帮助的话，点个赞、收藏一下吧！

后续我会分享更多 Vue3 架构与工程化最佳实践，让你的项目结构更优雅 🚀