生产级可扩展前端项目架构设计：从目录分层到模块解耦最佳实践

生产级可扩展前端项目架构设计：从目录分层到模块解耦最佳实践# 生产级可扩展前端项目架构设计：从目录分层到模块解耦最佳实践 随着业务规模扩张，不少前端项目都会陷入目录混乱、重复代码多、跨模块依赖混乱的痛点，每次迭代改一处逻辑就要动十几个关联文件，新人入职熟悉项目的成本居高不下。本文基于多年中大型前端项目落地经验，设计一套兼顾普适性与扩展性的前端结构方案，适配React、Vue等主流技术栈。 ## 一、核心设计原则 我们参考DDD领域划分思路给前端项目做边界切割，严格遵守三个核心规则： 1. 单向依赖规则：底层通用模块不能反向依赖上层业务模块，所有依赖只能从上层流向底层 2. 职责单一规则：每个目录的边界清晰，不允许跨领域存放无关逻辑 3. 可插拔规则：单个业务模块可以直接从项目中抽离、替换，不会影响其他模块的正常运行 ## 二、完整层级目录结构 我们把整个项目划分为5个大的层级，从上到下分别是业务场景层、领域组件层、通用能力层、基础框架层、第三方依赖层：  完整的目录骨架示例如下： ``` src/ ├── assets/ # 全局静态资源 ├── common/ # 通用能力层，和业务无关的公共抽象 │ ├── components/ # 全局通用组件（弹窗、表单、上传等） │ ├── hooks/ # 通用自定义hooks │ ├── utils/ # 工具函数 │ └── styles/ # 全局样式变量、重置样式 ├── domains/ # 领域组件层，按业务域划分的可复用组件 │ ├── order/ # 订单域通用组件 │ ├── user/ # 用户域通用组件 │ └── product/ # 商品域通用组件 ├── modules/ # 业务场景层，对应完整页面级业务逻辑 │ ├── order-list/ │ ├── order-detail/ │ ├── user-center/ │ └── ... ├── router/ # 路由配置 ├── store/ # 全局状态管理 ├── services/ # 接口请求层 └── App.tsx / main.ts # 项目入口文件 ``` ## 三、各模块职责边界说明 1. 通用能力层：完全剥离业务属性，所有组件、工具函数都可以直接跨项目复用，不允许引入任何业务相关的枚举、接口定义 2. 领域组件层：和特定业务域绑定，比如订单卡片、用户头像昵称组合组件，只在对应业务域内复用，不感知上层页面的逻辑 3. 业务场景层：每个目录对应一个完整的页面，内部的私有组件、页面状态、逻辑都放在当前目录下，不需要暴露给外部，避免跨页面的隐式依赖 ## 四、配套工程化管控规则 为了保证架构规则不被迭代过程破坏，我们可以在工程中加入依赖校验配置，用eslint-plugin-import配置禁止底层模块引入上层模块的逻辑： ```javascript // .eslintrc.js 配置片段 "import/no-restricted-paths": [ "error", { zones: [ { target: "./src/common", from: "./src/domains", message: "通用层不能依赖领域层" }, { target: ["./src/common", "./src/domains"], from: "./src/modules", message: "业务场景层不能被底层模块依赖" } ] } ] ``` 这套结构落地后，不管是后续新增业务模块、做微前端拆分，还是局部技术栈升级，都可以以极低的成本完成，不会出现牵一发而动全身的问题。