React / 系统课时
项目目录与模块边界
项目目录与模块边界
本课将把默认 Vite 工程整理成适合持续扩展的前端结构。重点不是增加目录数量,而是让页面、组件、服务、状态和工具各自承担单一职责,避免业务代码互相穿透。
学习目标
- 按业务职责规划 React 项目目录
- 明确页面、组件、服务、状态和工具模块的依赖方向
- 通过公开出口限制跨模块引用
先定义职责边界
页面模块负责组合界面并响应路由,通用组件负责可复用展示与交互,服务模块负责 HTTP 请求,状态模块保存跨组件共享状态,工具模块只提供无业务状态的纯函数。
目录不是边界本身。真正的边界由“谁可以依赖谁”决定:页面可以调用服务和状态,业务组件可以使用通用组件,但底层工具不应反向导入页面,通用组件也不应直接请求某个业务接口。
推荐目录与依赖方向
下面是一套适合中小型 React 项目的起点。业务增长后,可继续把 features 按用户、订单等领域拆分,而不是把所有接口和状态堆进全局目录。
text
src/
├─ app/ # 应用入口、路由和全局 Provider
├─ pages/ # 路由级页面
├─ features/ # 按业务领域组织组件、服务和状态
│ └─ users/
│ ├─ api.ts
│ ├─ model.ts
│ ├─ UserList.tsx
│ └─ index.ts
├─ components/ # 无具体业务含义的通用组件
├─ services/ # HTTP 客户端与通用请求能力
├─ stores/ # 全局且跨领域的状态
├─ utils/ # 纯函数工具
└─ types/ # 全局共享类型
这张图的阅读顺序是从上到下。越靠下的模块越通用,越不应该知道具体页面;同级业务模块之间也不应直接读取内部文件。
用公开出口落实边界
片段示例:下面代码依赖一个 Vite React TypeScript 项目,并假设 services/http.ts 已提供返回 JSON 的 get 方法。features/users/index.ts 是该领域唯一公开出口,页面不直接引用其内部文件。
ts
// src/features/users/model.ts
export interface User {
id: number
name: string
}
// src/features/users/api.ts
import { get } from '../../services/http'
import type { User } from './model'
export function fetchUsers(): Promise<User[]> {
return get<User[]>('/api/users')
}
// src/features/users/index.ts
export { fetchUsers } from './api'
export type { User } from './model'
// src/pages/UserPage.tsx
import { useEffect, useState } from 'react'
import { fetchUsers, type User } from '../features/users'
export default function UserPage() {
const [users, setUsers] = useState<User[]>([])
useEffect(() => {
fetchUsers().then(setUsers)
}, [])
return <ul>{users.map((user) => <li key={user.id}>{user.name}</li>)}</ul>
}生效行为是:页面只知道 features/users 提供了什么,不知道 api.ts 和 model.ts 如何组织。以后重命名内部文件时,只要公开出口不变,页面导入就无需修改。
验收模块边界
完成目录调整后,执行构建检查导入路径和类型是否完整。
bash
npm run build预期输出
text
✓ built in <TIME>代码评审时再检查三个问题:页面是否直接拼接请求地址,通用组件是否依赖具体业务,业务模块是否越过 index.ts 引用其他模块内部文件。任意一项为“是”,都说明边界仍需收紧。
按自己的节奏,确认真正理解。