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,却意外影响登录模块”这类隐式耦合。

React 项目的模块依赖方向

用公开入口保护模块内部

目录分开后,还需要控制外部能导入什么。可以让每个功能模块通过 index.ts 暴露稳定 API,模块外只从这个入口导入,而不直接访问 ui/、model/ 等内部路径。

下面是片段示例,假设购物车模块内部已经定义 CartPanel、useCart 和 CartItem。

ts
// src/features/cart/index.ts
export { CartPanel } from "./ui/CartPanel";
export { useCart } from "./model/useCart";
export type { CartItem } from "./model/types";

页面只依赖功能模块的公开入口:

tsx
// 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 项目,可以直接运行:

bash
npm run build

预期结果

text
module resolution: 无“找不到模块”错误
build: 退出码 0
output: 生成 dist/

实际构建日志、耗时和产物文件名可能不同。构建成功只能证明引用可以解析,不能自动证明依赖方向合理,因此边界规则仍需要通过公开入口、代码评审或静态检查持续约束。

避免为了分层而制造复杂度

模块边界的目标是降低变化成本,不是让每个功能都拥有固定数量的文件夹。只有一个组件的功能可以先保持简单;当状态、请求和 UI 开始一起增长时再拆分。共享代码也应在至少存在明确复用需求后再进入 shared,否则很容易形成难以理解的“万能工具层”。

判断目录是否健康,可以问两个问题:修改一个功能时,是否大多只需要进入一个功能目录;移动功能内部文件时,外部调用方是否基本不受影响。两者都成立时,目录结构才真正提供了模块边界。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

项目目录与模块边界

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通