Vue / 系统课时
建立项目基础规范
建立项目基础规范
本课把一个可运行的 Vue 3 项目整理成可持续协作的工程骨架。完成后,你将得到明确的目录边界、统一命名、可同时被 Vite 与 TypeScript 识别的路径别名,以及可用于提交前检查的基础脚本。
学习目标
- 按业务边界组织目录,避免公共代码与业务代码混杂
- 统一组件、组合式函数、类型和常量的命名规则
- 配置路径别名与基础脚本,并通过构建命令完成验收
用目录与命名划清边界
企业项目的目录不应只按文件类型无限堆叠,也不应把所有代码都塞进单个业务目录。较稳妥的做法是:基础能力按技术职责集中,共享 UI 明确复用边界,业务代码按领域模块内聚。
src/
├─ api/ # 通用请求客户端与拦截器
├─ assets/ # 参与构建的图片、字体等资源
├─ components/
│ └─ base/ # 无业务语义的基础组件
├─ composables/ # 可跨模块复用的组合式函数
├─ config/ # 环境与应用配置
├─ layouts/ # 页面布局
├─ modules/
│ └─ order/
│ ├─ api/ # 订单领域接口
│ ├─ components/ # 仅订单模块使用的组件
│ ├─ pages/ # 路由页面
│ └─ types/ # 订单领域类型
├─ router/
├─ stores/
├─ styles/
│ └─ main.css
├─ utils/
├─ App.vue
└─ main.ts判断代码放在哪里时,先问“它是否包含业务语义”。例如 BaseButton.vue 可以进入 components/base/,而 OrderStatusTag.vue 应留在订单模块。只有经过两个以上业务模块稳定复用的代码,才适合提升到公共目录。
命名要让开发者不打开文件就能判断其角色。团队应把规则写入 README 或贡献指南,并通过代码评审持续执行。
| 对象 | 建议规则 | 示例 |
|---|---|---|
| Vue 组件 | PascalCase | OrderStatusTag.vue |
| 组合式函数 | use + PascalCase |
useOrderQuery.ts |
| 普通工具文件 | camelCase | formatCurrency.ts |
| 类型与接口 | PascalCase | OrderDetail |
| 常量 | UPPER_SNAKE_CASE | DEFAULT_PAGE_SIZE |
| 路由名称 | 领域前缀 + PascalCase | OrderList |
| CSS 类名 | kebab-case | order-status-tag |
避免使用 common.ts、utils2.ts、data.ts 这类无法表达职责的名称。文件职责扩大后应拆分,而不是继续向“万能工具文件”追加函数。
同时配置 Vite 与 TypeScript 别名
只在 Vite 中设置别名,应用可能能运行,但编辑器与类型检查器仍会报告找不到模块;只在 TypeScript 中设置,构建工具又可能无法解析。因此两侧必须保持一致。
vite.config.ts 可以使用文件 URL 生成绝对路径,避免依赖当前工作目录:
import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
export default defineConfig({
plugins: [vue()],
resolve: {
alias: {
'@': fileURLToPath(new URL('./src', import.meta.url)),
},
},
})在负责应用源码的 TypeScript 配置中补充同一映射。下面是 tsconfig.app.json 的片段示例,其他编译选项沿用项目原配置。
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"]
}
}
}配置完成后,入口文件可以稳定使用项目绝对路径:
// src/main.ts
import { createApp } from 'vue'
import App from '@/App.vue'
import '@/styles/main.css'
createApp(App).mount('#app')预期结果:
编辑器能够跳转到 @/App.vue 和 @/styles/main.css。
TypeScript 类型检查不再报告别名模块无法解析。
Vite 开发服务器与生产构建使用同一套导入路径。若修改配置后编辑器仍显示旧错误,先重启 TypeScript 服务和 Vite 开发服务器,再检查 tsconfig.app.json 是否确实被当前项目引用。
用脚本固化检查与依赖方向
脚本名称应描述任务,而不是描述某位开发者的习惯。最小集合通常包括开发、类型检查、构建和本地预览;项目已经安装 ESLint 与 Prettier 时,再加入静态检查和格式化脚本。
下面是 package.json 的片段示例:
{
"scripts": {
"dev": "vite",
"type-check": "vue-tsc --noEmit",
"build": "npm run type-check && vite build",
"preview": "vite preview",
"lint": "eslint .",
"format": "prettier --write ."
}
}执行核心验收命令:
npm run type-check
npm run build预期结果:
类型检查命令以退出码 0 结束。
构建命令以退出码 0 结束,并生成 dist/ 目录。
若存在类型错误、别名错误或无法解析的导入,命令应失败并指出对应文件。不要在 build 中默认执行会自动修改文件的 format 或 lint --fix,否则 CI 构建可能悄悄改变工作区。自动修复适合开发者主动执行,只读检查更适合作为流水线门禁。
目录规范还要约束依赖方向:基础组件不能反向导入具体业务模块,公共工具不能依赖页面,领域模块之间也不应随意读取对方的内部文件。跨模块协作时,应从模块公开入口导出稳定能力,而不是引用深层实现路径。
例如订单模块可以通过 src/modules/order/index.ts 导出类型或服务,外部代码只从 @/modules/order 导入。这样调整模块内部目录时,调用方不需要同步修改大量路径。
本课总结
- 目录规范的核心是公共能力可复用、业务能力按领域内聚,并保持清晰依赖方向
- 命名应直接表达文件角色,避免长期积累含义模糊的万能文件
- 路径别名必须同时配置 Vite 与 TypeScript,基础脚本则负责把规范变成可重复验收的命令
下一课预告
下一课将进入 Vue 3 与 TypeScript 的实际编码约定,建立组件、Props、事件和组合式函数的类型边界。