告别面条代码！大型Vue3项目的目录架构与模块化分层设计

开篇引言你的 Vue3 项目是不是正在变成另一个 jQuery 时代的噩梦很多团队兴冲冲地升级到了 Vue3用上了script setup和 TypeScript以为这就算踏入了现代化前端开发的门槛。然而半年后当你打开项目根目录面对的是这样的景象components文件夹里躺着 50 个.vue文件命名从UserList.vue到UserListNew.vue再到UserListFinal.vue没人敢删一个新来的同事想改登录页的一个按钮样式却不得不先读懂src/api/下 3000 行的request.ts和src/utils/里十几个毫不相干的工具函数产品经理提了一个“在订单详情里加一个物流追踪地图”的需求你发现地图组件和订单组件互相 import形成了一个死循环依赖……这不是 Vue3 的锅这是架构的锅。如果你只是把 Vue3 当成“更好的 Vue2”来用那你的项目终将不可避免地滑向“面条代码”的深渊。在大型项目中框架只是工具架构才是灵魂。今天我们就来聊聊如何用领域驱动设计DDD思想和垂直切片架构彻底重构你的 Vue3 项目目录让组件和逻辑实现真正的物理级解耦。一、 为什么传统的“技术角色”分层在大型项目中会失效我们先来看看大多数 Vue 项目的标准目录结构也就是 Vue CLI 或 Vite 脚手架默认推荐的结构src/ ├── api/ # 所有接口请求 ├── assets/ # 静态资源 ├── components/ # 全局公共组件 ├── router/ # 路由 ├── store/ # 状态管理 ├── utils/ # 工具函数 └── views/ # 页面级组件这种按“技术角色”划分的方式在小项目中非常直观。​ 但问题在于它没有反映业务的边界。想象一下你的项目有“用户中心”、“商品交易”、“营销活动”三大业务板块。当你要修改“用户中心的收货地址”时你需要同时改动views/UserCenter/Address.vueapi/userApi.ts里面可能还混杂着商品和用户的所有接口store/modules/user.tscomponents/AddressForm.vue万一这个组件也被交易模块用了呢这就是典型的“横切耦合”。​ 一个业务功能的变更需要跨越 N 个技术目录去修改代码开发效率极低且极易引发回归 Bug。二、 破局之道引入领域驱动设计DDD与垂直切片在后端架构中领域驱动设计Domain-Driven Design, DDD​ 已经被证明是解决复杂业务耦合的银弹。它的核心思想是按照业务领域Domain而非技术层级来组织代码。映射到前端我们要做的就是把“横向分层”改为“垂直切片Vertical Slices”。 核心概念什么是垂直切片一个业务功能所需的所有代码UI、逻辑、数据、样式应该尽可能地待在同一个地方。就像一把刀切下去这一片里包含了这个功能所需的全部要素而不是把所有 UI 放一堆、所有逻辑放一堆。三、 实战重构你的 Vue3 项目目录下面是一套经过多个大型 ToB 和 ToC 项目验证的 Vue3 TypeScript 企业级目录结构src/ ├── app/ # 应用级配置只初始化一次的东西 │ ├── main.ts # 入口文件 │ ├── App.vue # 根组件 │ ├── router/ # 路由定义仅路由表不含业务逻辑 │ ├── store/ # 全局状态仅放真正全局的如用户信息、主题配置 │ └── plugins/ # 第三方插件初始化如 axios 实例、监控 SDK │ ├── entities/ # 业务实体跨领域共享的数据模型 │ ├── User/ │ │ ├── types.ts # User 的类型定义 │ │ ├── constants.ts # User 相关常量 │ │ └── utils.ts # User 相关的纯函数工具如格式化用户名 │ └── Product/ │ ├── types.ts │ └── constants.ts │ ├── features/ # 业务特征模块核心按领域垂直切片 │ ├── auth/ # 认证模块 │ │ ├── components/ # 仅属于 auth 的组件LoginForm, SocialAuth │ │ ├── composables/ # auth 相关的组合式函数useLogin, useRegister │ │ ├── api.ts # auth 相关的接口 │ │ ├── store.ts # auth 的局部状态如果用 Pinia 分模块 │ │ ├── types.ts # auth 特有的类型 │ │ └── index.ts # 统一导出barrel file │ │ │ ├── order/ # 订单模块 │ │ ├── components/ # OrderList, OrderDetail, OrderStatusBadge │ │ ├── composables/ # useOrderList, useOrderCancel │ │ ├── api.ts │ │ ├── store.ts │ │ └── index.ts │ │ │ └── dashboard/ # 仪表盘模块 │ └── ... │ ├── shared/ # 跨领域共享资源被多个 features 引用 │ ├── components/ # 真正的通用基础组件Button, Modal, Table │ │ ├── BaseButton/ │ │ │ ├── BaseButton.vue │ │ │ └── index.ts │ │ └── index.ts # 统一导出方便 auto-import │ ├── composables/ # 通用组合式函数useDebounce, useLocalStorage │ ├── utils/ # 通用工具formatDate, deepClone │ ├── hooks/ # 通用 hooks如 useTheme, useBreakpoint │ └── styles/ # 全局样式、变量、mixins │ └── widgets/ # 业务挂件可组合的页面区块介于组件和页面之间 ├── HeaderWidget/ ├── SidebarWidget/ └── UserProfileCard/四、 逐层拆解每一层该放什么不该放什么1️⃣app/—— 应用的骨架不是业务的垃圾桶只放应用启动配置路由实例、Pinia 实例、全局错误处理全局插件注册根组件不放❌ 任何具体业务逻辑❌ 具体 API 调用❌ 具体业务组件判断标准如果把features/和shared/全部删掉只靠app/能不能跑起来一个空白页面如果能说明你的app/层是干净的。2️⃣entities/—— 业务实体的契约层这里存放的是跨领域共享的数据模型和类型定义是整个项目的词汇表。// src/entities/User/types.ts export interface User { id: string name: string email: string role: UserRole avatar?: string } export type UserRole admin | editor | viewer // src/entities/User/utils.ts import type { User } from ./types export const formatUserName (user: User): string { return user.name || user.email.split()[0] } export const isAdmin (user: User): boolean { return user.role admin }关键点entities/层绝对不能引用​features/或shared/中的任何东西单向依赖原则它是最底层的基础像地基一样稳定如果 A 模块和 B 模块都需要用到同一个数据类型它就应该住在entities/里3️⃣features/—— 你的业务逻辑心脏这是整个架构中最重要的一层。每个 feature 就是一个垂直切片。features/auth/ ├── components/ │ ├── LoginForm.vue # 登录表单只在这个模块内用 │ └── SocialAuthBtn.vue # 社交登录按钮 ├── composables/ │ ├── useLogin.ts # 登录逻辑可复用、可测试 │ └── useAuthGuard.ts # 鉴权守卫 ├── api.ts # 登录/注册/登出的接口 ├── store.ts # auth 的 Pinia store ├── types.ts # auth 特有的类型如 LoginParams, TokenInfo └── index.ts # 统一导出useLogin.ts示例// features/auth/composables/useLogin.ts import { ref } from vue import { useRouter } from vue-router import { login as loginApi } from ../api import type { LoginParams } from ../types export function useLogin() { const router useRouter() const loading ref(false) const error refstring | null(null) const login async (params: LoginParams) { loading.value true error.value null try { const { token } await loginApi(params) localStorage.setItem(token, token) router.push(/dashboard) } catch (e: any) { error.value e.message || 登录失败 } finally { loading.value false } } return { login, loading, error } }然后在组件中!-- features/auth/components/LoginForm.vue -- script setup langts import { reactive } from vue import { useLogin } from ../composables/useLogin const { login, loading, error } useLogin() const form reactive({ username: , password: }) const handleSubmit () { login(form) } /script template form submit.preventhandleSubmit input v-modelform.username placeholder用户名 / input v-modelform.password typepassword placeholder密码 / button typesubmit :disabledloading {{ loading ? 登录中... : 登录 }} /button p v-iferror classerror{{ error }}/p /form /template看看这个组件有多干净​ 它只关心渲染表单和调用useLogin所有的业务逻辑、接口请求、路由跳转都藏在 composable 里。这就是极致解耦。4️⃣shared/—— 真正通用的东西才配待在这里严格准入原则放进shared/的东西必须满足——至少被 3 个不同的 feature 引用否则就应该放在对应的 feature 内部。shared/components/ ├── BaseButton/ # ✅ 被 10 个 feature 用 → 放这里 ├── BaseModal/ # ✅ 同上 └── OrderTable/ # ❌ 只有 order 模块用 → 应该在 features/order/components/ shared/composables/ ├── useDebounce.ts # ✅ 通用防抖逻辑 ├── useEventListener.ts # ✅ 通用事件监听 └── useOrderPolling.ts # ❌ 订单专用 → 应该在 features/order/composables/常见误区把shared/当成不知道放哪就扔这的垃圾桶。这会让你以为自己在做复用实际上是在制造隐式耦合。5️⃣widgets/—— 页面级的乐高积木Widgets 是由多个组件组合而成、具有独立业务含义的页面区块。它比组件大比页面小。!-- widgets/UserProfileCard/UserProfileCard.vue -- script setup langts import { useUserStore } from /stores/user import BaseAvatar from /shared/components/BaseAvatar/BaseAvatar.vue import BaseButton from /shared/components/BaseButton/BaseButton.vue const userStore useUserStore() /script template div classuser-profile-card BaseAvatar :srcuserStore.avatar :altuserStore.name / div classinfo h3{{ userStore.name }}/h3 p{{ userStore.bio }}/p /div BaseButton clickuserStore.editProfile编辑资料/BaseButton /div /template这个 Widget 可以在 Dashboard 页、设置页、个人主页等多个地方复用但它内部已经组装好了完整的 UI 和交互逻辑。五、 依赖流向一张图看懂各层关系┌─────────────────────────────────────────────┐ │ app/ │ │ 路由、全局配置、入口 │ └──────────────────┬──────────────────────────┘ │ 引用 ▼ ┌─────────────────────────────────────────────┐ │ features/ │ │ 业务模块垂直切片核心逻辑 │ │ │ │ auth ◄──────► order ◄──────► dashboard │ │ │ │ │ │ │ └──────────────┼──────────────┘ │ │ │ 引用 │ └───────────────────┼─────────────────────────┘ ▼ ┌───────────────────┐ │ entities/ │◄──────┐ │ 数据模型、类型 │ │ └─────────┬─────────┘ │ │ 被引用 │ ▼ │ ┌───────────────────┐ │ │ shared/ │───────┘ │ 通用组件、工具 │ 引用 entities └───────────────────┘铁律依赖只能从上往下绝不反向。层级可以引用不可以引用app/features, shared, entities无限制features/shared, entitiesapp, 其他 features尽量避免entities/什么都不引用纯类型纯函数所有其他层shared/entities类型引用features, app如果 feature A 必须要引用 feature B 的代码怎么办答案提取到entities/或shared/。比如订单模块需要用户信息不应该直接 import 用户模块的组件而是 importentities/User/types.ts里定义的User类型或者通过 Pinia store 来获取用户数据store 放在app/store/或shared/store/。六、 配合 Vite 的路径别名让导入更优雅在vite.config.ts中配置import { defineConfig } from vite import path from path export default defineConfig({ resolve: { alias: { : path.resolve(__dirname, src), app: path.resolve(__dirname, src/app), features: path.resolve(__dirname, src/features), entities: path.resolve(__dirname, src/entities), shared: path.resolve(__dirname, src/shared), widgets: path.resolve(__dirname, src/widgets), } } })然后你就可以这样写// ❌ 之前相对路径地狱 import { useLogin } from ../../../features/auth/composables/useLogin // ✅ 现在清晰明了 import { useLogin } from features/auth/composables/useLogin import type { User } from entities/User/types import BaseButton from shared/components/BaseButton再配合tsconfig.json的paths配置你还能获得完美的 TypeScript 类型跳转和自动补全支持。七、 避坑指南迁移过程中的 3 个致命误区❌ 误区 1一次性全量重构别这么做。​ 在一个 50 页面的老项目中试图用一个周末把所有代码搬到新目录是不现实的也是极其危险的。✅正确做法增量迁移新功能先行。新建功能直接按新架构来每次修改老功能时顺手把它迁移到新结构用 2-3 个月的时间平滑过渡❌ 误区 2过度拆分有些团队学了 DDD 之后把每个组件拆成index.vuestyles.tslogic.tstypes.ts一个简单的按钮组件搞出 5 个文件。✅正确做法按复杂度决定拆分粒度。简单组件一个.vue文件搞定中等组件.vuecomposables.ts复杂模块完整目录结构记住架构是为了服务开发效率不是为了炫技。❌ 误区 3忽视 Barrel File统一导出没有index.ts的统一导出你的 import 语句会变成这样import { LoginForm } from features/auth/components/LoginForm/LoginForm.vue✅加上index.ts// features/auth/components/index.ts export { default as LoginForm } from ./LoginForm/LoginForm.vue export { default as SocialAuthBtn } from ./SocialAuthBtn/SocialAuthBtn.vue然后import { LoginForm, SocialAuthBtn } from features/auth/components清爽多了而且以后组件内部目录调整只要index.ts的导出不便所有消费方都不受影响。这就是接口隔离的魅力。八、 总结好的架构是长出来的不是设计出来的这篇文章我们从为什么传统分层会失效出发引入了 DDD 和垂直切片的思想给出了一套可直接落地的 Vue3 企业级目录结构并拆解了每一层的职责边界和依赖规则。回顾一下核心要点按业务领域垂直切片而非按技术角色横向分层features/ 是心脏entities/ 是地基shared/ 是工具箱依赖只能从上往下绝不反向增量迁移拒绝一刀切重构架构服务于效率不为炫技但这只是第一步。目录结构只是物理层面的解耦真正的灵魂解耦在于——如何把业务逻辑从组件中连根拔起。在下一篇文章中我们将深入探讨组合式函数Composables的艺术教你如何写出高内聚、低耦合、可测试的业务逻辑让组件变成纯粹的视图壳。