React / 系统课时
项目目录与模块边界
项目目录与模块边界
这一节解决 React 项目变大后“文件越来越多、谁都能 import 谁”的问题。目标不是追求漂亮目录,而是让代码按功能聚合,并用明确的依赖方向降低跨模块修改和循环依赖的风险。
学习目标
- 按业务功能组织 React 代码,而不是把所有组件、Hooks 和请求分别堆进大目录。
- 用上层组合、下层复用的方向约束模块依赖。
- 通过模块公开入口减少深层导入,让内部重构不轻易影响调用方。
先按变化原因切分目录
目录边界应反映“哪些代码通常一起变化”。一个结算页面需要购物车状态、价格计算和展示组件,这些内容如果属于同一功能,就应该优先放在同一个功能模块,而不是分别散落到全局 components、hooks、services 目录。
一个中型项目可以采用下面的职责划分。它不是必须照抄的模板,小项目没有必要提前创建空目录。
| 位置 | 主要职责 |
|---|---|
src/app/ |
应用启动、路由、全局 Provider 和顶层组合 |
src/pages/ |
页面级组合,连接多个功能模块 |
src/features/ |
按业务能力组织的功能模块,如购物车、登录 |
src/shared/ |
与具体业务无关的 UI、工具、基础请求封装和类型 |
功能模块内部再按需要出现 ui/、model/、api/ 等子目录。关键不是子目录名称,而是功能代码尽量聚合在自己的边界内。
先规定依赖方向
一个容易维护的基本方向是:app 可以依赖 pages,pages 可以组合 features,features 可以依赖 shared;反向依赖应避免。shared 如果反过来导入某个业务功能,它就不再是真正共享的底层能力。
不同功能模块也应尽量由页面或应用层组合,而不是互相读取内部文件。这样可以减少“购物车改一个 Hook,却意外影响登录模块”这类隐式耦合。

用公开入口保护模块内部
目录分开后,还需要控制外部能导入什么。可以让每个功能模块通过 index.ts 暴露稳定 API,模块外只从这个入口导入,而不直接访问 ui/、model/ 等内部路径。
下面是片段示例,假设购物车模块内部已经定义 CartPanel、useCart 和 CartItem。
// src/features/cart/index.ts
export { CartPanel } from "./ui/CartPanel";
export { useCart } from "./model/useCart";
export type { CartItem } from "./model/types";页面只依赖功能模块的公开入口:
// src/pages/CheckoutPage.tsx
import { CartPanel } from "../features/cart";
export function CheckoutPage() {
return (
<main>
<h1>结算</h1>
<CartPanel />
</main>
);
}这种写法允许购物车模块以后把 CartPanel 移到别的内部目录,只要 index.ts 的公开契约不变,页面就不需要跟着改。相反,../features/cart/ui/CartPanel 这种深层导入会把调用方绑定到内部结构,应通过代码评审或 lint 规则限制。
用构建验证引用是否完整
调整目录后,至少要执行一次生产构建,确认移动文件后没有留下失效导入。对于已配置 build 脚本的 Vite 项目,可以直接运行:
npm run build预期结果
module resolution: 无“找不到模块”错误
build: 退出码 0
output: 生成 dist/实际构建日志、耗时和产物文件名可能不同。构建成功只能证明引用可以解析,不能自动证明依赖方向合理,因此边界规则仍需要通过公开入口、代码评审或静态检查持续约束。
避免为了分层而制造复杂度
模块边界的目标是降低变化成本,不是让每个功能都拥有固定数量的文件夹。只有一个组件的功能可以先保持简单;当状态、请求和 UI 开始一起增长时再拆分。共享代码也应在至少存在明确复用需求后再进入 shared,否则很容易形成难以理解的“万能工具层”。
判断目录是否健康,可以问两个问题:修改一个功能时,是否大多只需要进入一个功能目录;移动功能内部文件时,外部调用方是否基本不受影响。两者都成立时,目录结构才真正提供了模块边界。