先讲一件真事儿。前两年我参与过一个中后台项目，接手时正好赶上团队做“模块化重构”，把原来几个动辄上千行的巨型JS文件按功能拆分成了50多个小文件，每个文件平均不到100行，目录层级也从两层直接拉到了五层。重构完成那天大家挺高兴，光各种索引文件加起来写了小一千行。结果呢？两个星期之后，没人敢改代码了——因为要把“查询订单列表并计算优惠金额”这个完整功能读下来，你得同时打开七八个文件来回跳，改一个字段恨不得全局搜索三次才能确认影响范围。

这个经历让我开始认真琢磨一件事：我们天天挂在嘴边的模块化，到底是在拆文件，还是想解决什么更底层的问题？这篇文章是“前端向架构突围”系列里模块化方向的第一篇，我想先不谈工具、不摆框架，只聊一个很多人没想透、但决定了后续所有技术方案走向的核心问题：模块化的思想内核，也就是超越文件拆分的边界思维。它适合每一位正在从“会写代码”走向“会设计代码”的前端开发者，也适合被各种拆分规则困扰的团队负责人。

1. 文件拆到极致反而更乱：问题从来不在“拆”而在“边界”

1.1 一次把项目拆成“迷宫”的翻车现场

回到我开头说的那次重构。当时团队定的拆分标准很简单粗暴：一个函数一个文件、一个组件一个目录、公共逻辑全部抽到shared。听上去挺符合直觉的，对吧？结果代码目录长这样：

src/ ├── components/ │ ├── OrderTable/ │ │ ├── index.tsx │ │ ├── OrderTable.tsx │ │ ├── useOrderTable.ts │ │ ├── columns.tsx │ │ └── styles.ts ├── hooks/ │ ├── useOrder.ts │ ├── useUser.ts │ └── usePrice.ts ├── utils/ │ ├── calcDiscount.ts │ └── formatPrice.ts ├── api/ │ ├── orderApi.ts │ └── userApi.ts └── store/ └── orderStore.ts

表面上看，每个文件都很“专一”，职责清晰。但实际改需求的时候，问题就全暴露了：一个“订单列表加一列优惠金额”的小需求，从组件文件出发，一路改到store、改到api层、改到utils，甚至还要动hooks里的逻辑。文件之间互相import的路径深到怀疑人生，你根本说不清这些文件到底谁属于谁。这哪是模块化？这就是把一块完整的代码切碎了撒在目录树的各个角落，再用import把它们粘回去。

那次重构给我最大的教训是：文件拆分只是模块化的物理表现，它本身不产生架构价值。真正产生价值的，是你对“边界”的定义——哪些东西应该放在一起，哪些东西必须分开，分开之后彼此之间怎么交往。这个想不清楚，文件拆得越碎，系统崩溃得越快。

1.2 文件拆分真正解决的问题，其实很有限

我不是说文件拆分没用，它当然有用，但我们得先搞清楚它到底解决了什么。

回顾前端历史，最早我们在一个script标签里写所有代码，全局变量满天飞，函数之间靠命名约定来规避冲突。后来有了多个script标签按顺序加载文件，但文件顺序一旦错了，运行时直接白屏。再后来社区发明了IIFE模拟命名空间、CommonJS给了Node.js一个模块系统、RequireJS把AMD带上浏览器，直到ES Module成为标准。

ES Module确实解决了好几个实实在在的问题：

• 作用域隔离：每个文件都有独立作用域，变量不会污染全局。
• 依赖关系显式化：import/export让文件之间的引用关系一眼可见。
• 静态分析友好：打包器可以基于import/export做Tree Shaking，去除死代码。
• 循环依赖检测：工具可以在构建期就报出循环依赖。

但注意，上面这些全部停留在语法层和工具层。ES Module告诉你的是“文件之间怎么互相引用”，它完全没有回答“哪些文件应该属于同一个有业务意义的模块”“模块之间允许依赖谁、不允许依赖谁”“一个模块对外暴露什么、隐藏什么”——这些问题属于设计层，恰恰是模块化最核心的内容。

换句话说，文件拆分是模块化的必要不充分条件。你可以用ES Module把代码组织得整整齐齐，但完全没有模块化的思想；你也可以在思想上把系统边界画得很清楚，虽然物理上还没有用模块语法落地。

1.3 拆到极致反而乱的三个根源

总结那次翻车和后来我观察到的类似案例，文件拆完之后项目反而更乱，通常逃不出三个原因。

第一，拆分的单位错了。很多人是按“代码行数”“文件大小”来拆，而不是按“业务能力边界”来拆。一个文件超过200行就觉得“不模块化”，于是拆成5个50行的文件。这五个文件之间强耦合、互相引用，看起来文件苗条了，逻辑上还是一坨。真正的模块划分单位应该是：一组高内聚的、共同完成一个业务能力的代码集合，而不是“行数的多少”。

第二，依赖方向没有规划。模块化做得好，模块之间的依赖应该构成一个有向无环图（DAG）。但没人约束的时候，依赖关系很容易变成一张乱网：A引用B，B引用C，C又反过来引用A。一旦形成循环依赖，初始化顺序就说不清了，改一处逻辑的影响范围也没法评估。到后面你根本不敢动任何一个文件，因为不知道谁会依赖它。

第三，没有接口收口。模块内部的东西全裸奔，外部可以import到这个模块的任何文件、任何函数。这样“模块”就退化成了“一堆共享文件”，没有任何私有边界，内部重构就意味着外部跟着爆炸。

一句话总结：拆是手段，边界才是目的。接下来我们就聊聊边界的本质。

2. 模块化的本质：信息隐藏与变更隔离，这才是边界思维的内核

2.1 一篇1972年的论文，把模块化说透了

很多人以为模块化是工程实践催生的概念，其实它在软件工程理论里早就被研究透了。1972年，David Parnas发表了一篇经典的论文《On the Criteria To Be Used in Decomposing Systems into Modules》，核心观点放到今天依然一针见血：模块划分的依据，不应该是程序员脑子里“先做什么后做什么”的功能流，而应该是“每个模块内部的设计决策彼此尽可能独立”。

论文里的例子我现在还记得：一个文本分析系统，如果按照“输入、扫描、输出”这种流程来分模块，那么任何一个环节格式变了，三个模块都得跟着改；但如果按照“文本格式的内部表示”来划分，各模块只需要和这个表示打交道，格式变了只改负责解析的那个模块。你看，五十多年前的思考，和今天前端做业务域拆分时面临的问题是一模一样的：我们怎么切，才能让未来的变化只落在一个小范围里？

Parnas这篇论文还提出了另一个概念，叫“信息隐藏”（Information Hiding）：模块的设计决策应该尽可能对模块外部隐藏。也就是说，除了对外暴露的接口，模块内部的一切——数据结构、算法实现、细节策略——都不应该被外部知道，也不应该被外部依赖。

2.2 信息隐藏：接口是边界上唯一的门

信息隐藏很容易被人忽视，因为它在“代码能跑”的时候看起来毫无用处。但它恰恰是模块化思想里最有价值的部分。

想象一下一个餐厅：菜单就是它的接口，后厨怎么备菜、用了什么调料、灶台怎么排列，都是内部实现。你作为顾客，只需要点菜等餐，不需要也不允许闯进后厨自己拿盐。餐厅在后厨怎么调整配方、更换供应商、改变烹饪流程，只要菜品和口感不变，对你来说都无感。这就是信息隐藏的价值：内部可以自由演进，外部稳定不受波及。

前端里的对应物非常典型：一个订单模块内部实现从REST API迁移到了GraphQL，或者本地缓存策略从sessionStorage换成了IndexedDB，这些只要接口没变，调用方完全不需要感知。反过来，如果调用方大量使用了订单模块内部的函数、数据结构，那这个“模块化”就是假的，因为接口变成了隐形的、不可控的。

2.3 变更隔离：模块化的终极验收标准

如果说信息隐藏是模块化的设计原则，那“变更隔离”就是模块化的验收指标。一次需求变更，影响了多少个模块？这个数字就是模块化质量的度量衡。

我拿前面提过的“下单流程增加积分折扣”来举例。模块化差的代码库里，这个需求要动：

五个模块被一个需求击穿，联调成本极高。而边界划分合理的情况下，这个需求应该只落在订单模块内部：商品模块只提供“商品原价”这个稳定接口，用户模块只提供“积分余额校验”这个稳定接口，订单模块自己负责把积分换算成优惠、计算抵扣后的金额、调用用户模块扣减积分。改动依然存在，但其他模块对这次改动的感知降到了最低——这正是我们做模块化追求的结果。

3. 三条边界思维准则：接口收口、依赖单向、变更半径

3.1 接口收口：暴露得越少，内部越自由

“接口收口”听起来专业，其实就是一句话：模块对外提供的入口越少越好、越窄越好，最好只有一个“门面”（Facade）。

前端落地这个思想最直接的手段，就是每个模块只通过一个index文件（index.ts / index.js）对外导出。模块内部的其他文件，对模块外部的代码来说，根本不存在。

// features/order/index.ts // 这是order模块唯一的对外出口 export { createOrder } from './services/createOrder'; export { queryOrderList } from './services/queryOrderList'; export { OrderPanel } from './components/OrderPanel'; // 以下不对外暴露 // export { calcDiscount } from './utils/calcDiscount'; // 禁止 // export { orderStore } from './store/orderStore'; // 禁止

为什么强调这点？因为接口窄，意味着模块内部的实现细节可以随时调整，只要出口不变，外部代码就不会被波及。有人可能觉得“内部工具函数被外部复用也没什么”，但问题在于：这个工具函数不是稳定的公共API，它可能因为模块内部需求变化而修改签名、去除参数，结果外部一堆代码悄悄依赖它，一改就炸。这种事在工程里太常见了。

我自己的经验是，接口收口要严格到“强迫症”级别：哪怕某个内部函数现在没有外部引用，也要默认它不可被外部import。等到有第二个真正的业务方需要时，再讨论是否值得把它升级为公开API——这个过程本身就是在做设计评审。

3.2 依赖单向：模块之间应该是树，不是网

边界思维的第二条准则是依赖方向必须单向、清晰。理想状态下，模块间的依赖关系是一棵（或一组）没有环的树，而不是一张互相缠绕的网。

为什么单向依赖这么重要？最直接的原因是循环依赖会让模块彻底失去边界。比如模块A依赖B，模块B依赖A，这两个模块就无法独立理解、独立测试、独立修改。前端里循环依赖还会引起运行时问题：ES Module在静态分析后确实能处理循环，但初始化阶段的“暂时性死区”会让你在模块加载顺序的坑里反复挣扎——一个模块还没初始化完，另一个模块就来取它的导出，结果拿到undefined。

更隐蔽的问题是，循环依赖往往暗示着职责划分出了问题。比如订单模块调用了用户模块的“积分扣减”，用户模块又回头调用了订单模块的“订单状态查询”来确认积分能不能扣——这其实是在说“积分扣减是否允许”这个业务规则到底应该属于哪个模块没想清楚。正确的做法通常是：把双方共同依赖的规则抽到下层模块（例如结算领域里的“积分规则模块”），让订单和用户都只依赖它，而不是互相依赖。

工程上约束依赖方向的办法我也列一下，后面第5章会展开：

• 禁止模块间直接深层import（ESLint的import/no-restricted-paths）。
• 用dependency-cruiser在CI里检查依赖图，出现环直接挂红灯。
• 设计评审时，把模块依赖图画出来，视觉上的“网”就是危险信号。

3.3 变更半径：用“一次改动碰几个文件”来自测

这条准则最容易被忽略，因为它有关“自省”而非“设计”。我强烈建议每个团队做一轮实验：连续记录两周的需求改动，每次改完代码后，数一数这次改动触及了几个模块、几个文件。然后回头审视：这些改动有多少是因为需求本身就需要跨模块，有多少是因为当初的边界划分不当？

拿我的经验来说，如果一个“列表页增加筛选条件”的需求，要改列表组件、要改store、要改api层、要改一个公共utils函数，那大概率是模块边界画错了——这些代码本该属于同一个业务模块，硬被按技术类型拆开了。而如果“增加一种新的支付方式”，只需要在支付模块内部新增一个适配器，外部无感知，那这个边界就是合理的。

我经常给团队讲一个“半径感觉”：改需求时，如果光标在一两个文件之间跳来跳去就能完成，说明模块化在起作用；如果光标在全项目的文件里到处飞，大脑就要报警了。这不是玄学，而是模块化做得好坏的直接体感。变更半径越小，代码的可维护性越强，团队并行开发的效率也越高。

4. 模块化的三个层次：文件层、组件层、领域层

4.1 文件层——ES Module做到的只是“最低级的模块化”

日常开发中我们最容易接触到的模块化是文件层的。在React、Vue项目里写一个组件，每个组件一个目录，目录里放tsx/jsx、样式、测试、局部hooks，再配一个index导出——这就是文件层的模块化。

文件层的模块化解决的问题非常基础：代码的组织形式。它让你能在一个文件里安心写逻辑而不污染别的文件，让构建工具能分析依赖、做tree-shaking，让单元测试能精确地mock某一个模块。这些都是必要的，但远远不够。

我见过很多团队“文件层做得很漂亮”：组件目录规整、hooks抽取到位、文件夹命名统一、lint规则严格。但一旦问到“订单相关的APIs调用放在哪个模块里”“用户登录态应该由哪个模块来维护”“商品详情页和购物车如何共享商品信息”，大家就含糊了。这说明文件层的模块化只是表层功夫，真正的模块化还在更深处。

4.2 组件层——界面自洽单元

组件层是前端特有的模块化层次。React/Vue组件本质上就是一种模块：props是输入接口，事件/回调是输出接口，state是内部实现，用户可以完全不知道组件内部怎么渲染、怎么管理状态，只要接口稳定就能复用。

组件层模块化解决的是界面单元的自洽问题：一个按钮、一个表格、一个弹窗，都应该有独立的样式、逻辑和状态。把组件做好，同一个组件可以在不同页面复用，同一处界面修改不至于牵动其他页面，这是组件化带来的直接价值。

但组件层有一个天然缺陷：它管的是“长得像什么”，不是“业务上属于谁”。同一个用户在订单页和用户中心页都展示头像，头像组件可以复用，但“这两个页面各自应该管理哪些订单状态、哪些用户数据”，组件层完全给不了答案。这就引出了第三个层次——领域层，也是我认为前端模块化里最缺失、最关键的一层。

4.3 领域层——前端最缺的一层

很多团队“组件化做了、文件也拆了”，代码还是乱，根本原因是领域层没有建立。

领域层是什么？就是按业务能力边界划分模块。一个电商项目里，订单、支付、商品、用户、售后，这就是五个领域。每个领域应该是一个完整自洽的模块，包含它自己的UI组件、状态管理、API封装、业务逻辑。领域之间通过稳定的接口协作，而不是互相穿透对方的内部文件。

前端领域层的缺失，通常表现为这样几个典型场景：

• 所有业务API调用都堆在一个api目录里，按后端接口命名，不归属任何前端业务域。
• 全局store / 全局context里放了所有领域的状态，订单、用户、购物车的state挤在一起，任何模块都能改任何数据。
• 一个“登录用户信息”被二十个组件分别使用者，没有统一的用户领域模块来承接。

前端之所以容易缺失领域层，是因为从视觉上看，页面上所有模块都长得很像（都是组件），不像后端可以清晰地分成服务、数据库、API网关。但前端代码的复杂度从来不是来自视觉，而是来自业务状态和业务规则。你不给业务规则划疆界，它们就会互相渗透，最终变成一个改了这头塌了那头的毛线团。

那么领域层的模块化怎么落？核心是这么几个原则：

1. 每个领域有自己的目录，例如src/features/order、src/features/payment。
2. 领域内部的UI、状态、API封装、业务hooks都放在领域目录内，不全局摊开。
3. 跨领域访问统一走领域公开接口（index.ts），不直接import对方内部文件。
4. 跨领域的数据共享通过领域层精心设计的接口完成，而不是大家共用一个大store。

这里说一句大实话：前端领域层的设计，难度比文件层和组件层高一个数量级，因为需要你足够了解业务。你只有知道“下单”这件事涉及哪些状态流转、哪些规则约束、哪些步骤边界，才能画出合理的领域疆界。这也是为什么我一直认为，好的前端架构师首先得是好的业务分析师。

5. 把边界落在工程里：目录设计、导出收口与工具约束

5.1 目录结构是边界的投影

思想层面的边界最终必须映射到代码目录上，否则就是空中楼阁。目录结构怎么组织，直接决定了团队日常开发中是否能“顺路”守住边界。

最常见的错误是按技术类型组织目录：

src/ ├── components/ # 所有组件 ├── hooks/ # 所有自定义hook ├── utils/ # 所有工具函数 ├── api/ # 所有后端接口调用 └── store/ # 所有全局状态

这种结构的问题在于：它把“技术角色”当成了划分依据。它不在意业务逻辑属于哪个域，所有订单相关的组件缝里插针地散落在components里，所有订单状态挤在store里，所有接口调用堆在api里。改一个订单需求，要在components/hooks/api/store四个目录里来回横跳。

我推荐的模式是业务域优先，技术角色其次：

src/ ├── features/ │ ├── order/ │ │ ├── components/ │ │ ├── hooks/ │ │ ├── services/ # API调用封装 │ │ ├── store/ # 订单领域状态 │ │ ├── types/ │ │ └── index.ts # 对外出口 │ ├── payment/ │ │ ├── components/ │ │ ├── services/ │ │ └── index.ts │ └── user/ │ ├── components/ │ ├── services/ │ └── index.ts ├── shared/ # 真正跨域的通用基础（UI基础组件、通用工具） │ ├── components/ │ ├── hooks/ │ └── utils/ └── app/ # 应用组装层（路由、布局、全局配置）

这个结构把业务域作为第一层目录，让每个领域的代码物理上聚在一起。跨域调用只能通过features下的index.ts入口，避免深路径引用。shared目录只放真正与技术方案相关、不含业务规则的基础设施，比如通用按钮、日期格式化工具——它不应该放“订单计算”这类业务逻辑。

当然，没有一种目录结构是万能的。小项目或者工具型项目按技术类型组织完全没问题，但一旦业务复杂到“一个需求要跨多个人并行开发”，业务域优先的优势就会非常明显。

5.2 导出收口：index.ts是一个模块的“脸面”

前面提到，每个业务模块用一个index.ts做唯一出口。这既是接口收口的落地，也是目录结构的必然配套。

写index.ts的时候有几个细节值得注意：

• 只导出公开API。组件、函数、类型，都按“这个模块允许别人用什么”来导出。内部模块不管多有用，默认不导出。
• 导出的是语义能力，不是实现工具。比如导出createOrder(参数)而不是导出orderApi里的postOrder方法。后者是把后端接口直接透传出去，前者才表达了领域能力。
• 类型导出要谨慎。TypeScript里类型会参与编译期契约，跨模块导出类型本身没问题，但要注意不要因此把内部数据结构暴露出去。外部只应该依赖你公开的类型定义，而不是你某个service文件里的中间类型。

有一次我帮一个团队做代码评审，发现他们的index.ts里导出了几乎所有内部文件，原因是“省事，反正都是自己人用”。结果一次内部重构，改了某个service的函数签名，全项目二十多个文件一起编译报错。这就是没做导出收口的代价。

5.3 用工具强制边界：口头约定一定会烂

我特别想强调一点：模块边界靠“团队觉悟”是不可能长期守住的。人都会图省事，需求紧急的时候，“直接从A模块内部拿一个函数用”的诱惑没人能抵抗。所以必须把边界约束写进工具链。

最基础的是ESLint的import/no-restricted-paths规则。它可以禁止某个模块的代码import另一模块的内部文件，只允许import对方入口：

{ "rules": { "import/no-restricted-paths": ["error", { "zones": [ { "target": "./src/features/order", "from": "./src/features/payment", "message": "payment模块不允许直接import order模块的内部文件，只能引用order的index.ts" } ] }] } }

更进一步，用dependency-cruiser检查整个项目的依赖图。它能在CI里执行，检测出循环依赖、越界依赖、深层import等违规，并生成可视化的依赖关系图。我们团队就把dependency-cruiser加进了pre-commit和CI流水线，一旦发现循环依赖或跨模块深路径引用，直接阻断合并。刚开始工程师们天天被红灯拦，怨声载道，两个月后大家就习惯了从模块出口走，违规率直线下降。

如果项目规模更大，Nx这类工具内置了Module Boundary规则，可以在项目级别定义模块间依赖约束，还能配合构建缓存做增量构建。这些工具的共同思路都是一样的：把“边界”从口头约定变成可执行的代码规则。

6. 我踩过的几个坑：过度抽象、跨模块捷径、拆完不治理

6.1 为了复用提前抽象，抢跑了边界

模块化做得久了容易“手痒”，看到两个模块里出现相似的函数，第一反应就是“抽出来放到shared里共用”。我踩过这个坑，而且踩得很惨。

当时订单和售后两个模块里各有一个“计算退款金额包含运费”的逻辑，长得有七八分像。我本着复用精神把它抽到了shared/utils里，还精心设计了参数让它兼容两种场景。结果三个月后，订单模块因为新的优惠策略改了运费计算规则，售后模块没跟上——两边业务规则已经分化，但因为共用同一个函数，任何一边的改动都会波及另一边。最后这两个模块各自都需要不同的运费计算，我被迫把这个“共享函数”又拆了回去，还多花了一天处理中间那段时间的兼容问题。

这个教训让我记住了三条：

• 抽public API之前，至少等它出现第三个使用方。（所谓Rule of Three）
• 共享代码不能脱离业务语义。一个函数一旦放进了shared，就已经是半个公共API了，必须要有清晰、稳定的契约。
• 抽象要面向“稳定”，而不是面向“相似”。在业务快速变化的模块里，相似代码的临时重复，可能好过过早的共享抽象。

6.2 跨模块“捷径引用”，边界形同虚设

第二种坑是“捷径”。需求赶工期，发现另一个模块内部有个现成的工具函数正好能用，直接import了深层路径，没走对方index出口。一次两次觉得没什么，但这类行为累积起来，边界就会千疮百孔。

我记得有一次，支付模块直接引用了订单模块内部的“订单金额计算”函数，因为订单模块当时没把这个能力作为公开接口暴露。结果订单模块为了支持“预售定金”改了这个内部函数的行为，支付模块的展示金额全错了。查了半天才定位到那个深层import——因为代码评审的时候根本没人会注意每一行import，而lint规则也没有配置restricted-paths。

从那以后，我们把“跨模块必须走公开出口”写进了两条硬约束：ESLint规则强制拦截，Code Review的checklist里专门有一项“确认import路径没有跨模块深引用”。现在团队里的新人一开始觉得麻烦，但没人再为这种隐蔽bug熬过夜。

6.3 拆完不治理，三个月后又意大利面

最后一个坑，不是拆分时的问题，而是拆分后的问题：模块边界做完了，以为一劳永逸，结果三个月后架构又塌回原点。

原因其实很简单：业务在演进，模块在变化，当初画好的边界需要持续维护。一个模块对外暴露的接口可能因为业务需求变宽了，一个功能模块可能从订单域迁移到了结算域，某个shared函数可能不知不觉被几十个模块依赖。如果不定期审视这些变化，边界就会在无数次“小改动”中慢慢失效。

我们现在坚持做几件事，基本都是低成本高回报：

• 每季度跑一次dependency-cruiser的全量依赖报告，人工看一眼依赖图有没有出现往年看不到的“连接密度变高”“环悄悄长出来”。
• code review持续关注模块归属。每次提交都问：这个改动放在这个模块里合理吗？是不是在给错误的模块增加职责？
• 模块入口的“公众度”审计。如果一个index.ts导出了20多个API，说明模块的对外表面太宽了，需要警惕内部逻辑是不是被外部过度依赖。

模块化做得不是一个周末的重构冲刺，而是一个持续演进的过程。边界不是画完就完的壁画，是需要长期维护的围栏。

最后的几句实在话

做了这么多年前端，我对模块化最大的体会是：它本质上不是文件组织问题，而是一个“让每一次变更都发生在尽可能小的范围内”的思维方式。文件拆分只是边界的物理载体，组件化只是边界的UI投影，真正决定系统可维护性的，是你有没有把业务规则、状态、接口的边界想清楚，并在工程上持续守护。现在我每次提交代码之前，都会习惯性问自己三个问题：这个改动越界了吗？依赖方向被打破了吗？有没有一个本该承载它的模块被我绕过了？多花十分钟调整归属，往往能省下后面不只十个小时的排查时间。这篇“思想篇”先把底层逻辑理清楚，后续我们再来聊具体的拆法、工具链和落地细节。