Vue / 系统课时

建立项目基础规范

建立项目基础规范

本课把一个可运行的 Vue 3 项目整理成可持续协作的工程骨架。完成后,你将得到明确的目录边界、统一命名、可同时被 Vite 与 TypeScript 识别的路径别名,以及可用于提交前检查的基础脚本。

学习目标

  • 按业务边界组织目录,避免公共代码与业务代码混杂
  • 统一组件、组合式函数、类型和常量的命名规则
  • 配置路径别名与基础脚本,并通过构建命令完成验收

用目录与命名划清边界

企业项目的目录不应只按文件类型无限堆叠,也不应把所有代码都塞进单个业务目录。较稳妥的做法是:基础能力按技术职责集中,共享 UI 明确复用边界,业务代码按领域模块内聚。

text
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 生成绝对路径,避免依赖当前工作目录:

ts
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 的片段示例,其他编译选项沿用项目原配置。

json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

配置完成后,入口文件可以稳定使用项目绝对路径:

ts
// src/main.ts
import { createApp } from 'vue'
import App from '@/App.vue'
import '@/styles/main.css'

createApp(App).mount('#app')

预期结果:

text
编辑器能够跳转到 @/App.vue 和 @/styles/main.css。
TypeScript 类型检查不再报告别名模块无法解析。
Vite 开发服务器与生产构建使用同一套导入路径。

若修改配置后编辑器仍显示旧错误,先重启 TypeScript 服务和 Vite 开发服务器,再检查 tsconfig.app.json 是否确实被当前项目引用。

用脚本固化检查与依赖方向

脚本名称应描述任务,而不是描述某位开发者的习惯。最小集合通常包括开发、类型检查、构建和本地预览;项目已经安装 ESLint 与 Prettier 时,再加入静态检查和格式化脚本。

下面是 package.json 的片段示例:

json
{
  "scripts": {
    "dev": "vite",
    "type-check": "vue-tsc --noEmit",
    "build": "npm run type-check && vite build",
    "preview": "vite preview",
    "lint": "eslint .",
    "format": "prettier --write ."
  }
}

执行核心验收命令:

bash
npm run type-check
npm run build

预期结果:

text
类型检查命令以退出码 0 结束。
构建命令以退出码 0 结束,并生成 dist/ 目录。
若存在类型错误、别名错误或无法解析的导入,命令应失败并指出对应文件。

不要在 build 中默认执行会自动修改文件的 format 或 lint --fix,否则 CI 构建可能悄悄改变工作区。自动修复适合开发者主动执行,只读检查更适合作为流水线门禁。

目录规范还要约束依赖方向:基础组件不能反向导入具体业务模块,公共工具不能依赖页面,领域模块之间也不应随意读取对方的内部文件。跨模块协作时,应从模块公开入口导出稳定能力,而不是引用深层实现路径。

例如订单模块可以通过 src/modules/order/index.ts 导出类型或服务,外部代码只从 @/modules/order 导入。这样调整模块内部目录时,调用方不需要同步修改大量路径。

本课总结

  • 目录规范的核心是公共能力可复用、业务能力按领域内聚,并保持清晰依赖方向
  • 命名应直接表达文件角色,避免长期积累含义模糊的万能文件
  • 路径别名必须同时配置 Vite 与 TypeScript,基础脚本则负责把规范变成可重复验收的命令

下一课预告

下一课将进入 Vue 3 与 TypeScript 的实际编码约定,建立组件、Props、事件和组合式函数的类型边界。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

建立项目基础规范

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通