Vue 中后台项目目录结构设计

后端同学写前端最容易卡在“文件应该放哪”。目录结构不是美观问题，而是协作效率问题。

这篇给你一个中后台项目可落地的结构模板。

一、推荐目录结构

src/
  api/                  # 接口定义层，只做请求封装
    modules/
      user.ts
      order.ts
  assets/               # 静态资源
  components/           # 通用组件（跨页面复用）
  composables/          # 可复用逻辑（useXxx）
  constants/            # 常量与枚举
  layouts/              # 布局壳（侧边栏、顶栏）
  router/               # 路由定义与守卫
  stores/               # 状态管理（Pinia）
  styles/               # 全局样式与变量
  types/                # TS 类型声明
  utils/                # 工具函数（时间、格式化等）
  views/                # 页面级组件（路由页面）
    user/
      UserList.vue
      UserForm.vue
  App.vue
  main.ts

二、每一层的边界要清晰

1. views 只负责页面编排

• 组织页面结构。
• 调用 api 与 stores。
• 处理页面级交互。

不要把复杂请求封装、通用函数直接写在 views 里。

2. api 只负责“请求契约”

• 定义接口方法。
• 约束请求参数和响应类型。
• 统一错误转换（必要时）。

不要在 api 里操作 DOM，也不要依赖具体页面组件。

3. stores 负责跨页面共享状态

• 用户登录态、权限、主题配置等。
• 需要多个页面共享的数据。

页面临时状态不要全塞进 stores，否则会过度全局化。

三、给后端同学的“模块化视角”

你可以把前端按后端分层理解：

• controller 类比 views
• service client 类比 api
• global context/cache 类比 stores
• common 类比 utils/components

这样迁移认知成本最低。

四、新增一个业务模块时的入手顺序

以“用户管理”为例：

1. 先补类型：types/user.ts
2. 再补接口：api/modules/user.ts
3. 再建页面：views/user/UserList.vue
4. 最后挂路由：router/modules/user.ts

这个顺序能让你在编码时始终沿着数据流走，不容易失控。

五、目录规范建议

• 组件命名使用 PascalCase，文件与组件名保持一致。
• 组合式函数用 useXxx.ts 命名。
• 路由模块按业务域拆分，不要一个 router/index.ts 塞全部路由。
• 每个目录都尽量“单一职责”。

六、旧项目目录混乱时怎么做

不要一次性重构全项目，采用“小步改进”：

1. 只对当前改动模块执行新规范。
2. 新增代码强制走新目录，不再往旧目录继续堆。
3. 每次需求顺手迁移 1~2 个旧文件。

这样 2~3 个迭代后，项目结构会自然收敛。

七、结构评审清单

提测前可以自查：

• 新增接口是否都在 api/modules。
• 页面里是否存在重复请求逻辑。
• 是否出现跨层级直接引用（如 views 直接改全局工具底层逻辑）。
• 目录命名是否和业务语义一致。

目录结构稳定后，后面的联调、排错和交接都会轻很多。