架构(功能切片设计)
优先级: P2(中等)
采用 功能切片设计 (FSD) 构建可扩展的应用程序。 警告: FSD 会引入样板代码。仅当项目预期会显著增长(例如 20 个以上功能)时使用。对于较小的项目,优先使用简单的模块化结构。
策略
- RSC 边界: 严格执行从服务端到客户端传递 props 的序列化规则。参见 RSC 边界与序列化。
- 应用层要薄:
app/目录(App Router)仅用于路由。- 规则:
page.tsx只能导入 Widgets/Features。页面中不应直接包含业务逻辑(useEffect、fetch)。
- 规则:
- 按切片而非类型分组: 按业务领域(用户、产品、购物车)对代码进行分组,而不是按文件类型(组件、钩子、工具)。
- 糟糕:
src/components/LoginForm.tsx、src/hooks/useLogin.ts - 良好:
src/features/auth/login/包含两者。
- 糟糕:
- 层层级: 代码只能从低于它的层中导入。
App->Widgets->Features->Entities->Shared。
- 避免过多的实体: 不要过早地创建 Entities。
- 规则: 从
Features或Pages开始逻辑。仅当数据/逻辑在多个不同的 feature 中严格复用时,才将其移至Entities。 - 规则: 简单的 CRUD 应放在
shared/api中,而不是entities。
- 规则: 从
- 标准分段: 在切片内使用标准分段名称。
ui(组件)、model(状态/动作)、api(数据获取)、lib(辅助函数)、config(常量)。- 避免: 使用
components、hooks、services作为分段名称。
结构参考
有关具体的目录布局和层定义,请参见参考文档。
架构检查清单(强制性)
-
层导入: 是否有任何层从其上层导入?(App > Widgets > Features > Entities > Shared)
-
页面逻辑:
page.tsx是否保持精简,仅包含 Widgets/Features 且不含任何useEffect/fetch? -
RSC 边界: 服务端组件是否与客户端组件正确隔离,并使用正确的
'use client'边界? -
公共 API: 对某个切片的所有访问是否都通过顶层
index.ts(公共 API)执行? -
跨切片: 同一层内的切片(例如两个 feature)是否直接相互导入?(禁止)
-
Server Actions: 将它们放在 Feature 的
model/文件夹中(例如features/auth/model/actions.ts)。 -
数据访问层 (DAL): 将逻辑放在 Entity 的
model/文件夹中(例如entities/user/model/dal.ts)。 -
UI 组件: 基础 UI(shadcn)属于
shared/ui。特定于 Feature 的 UI 属于features/*/ui。
反模式
- 禁止跨切片导入: 同一层内的切片不得直接相互导入。
page.tsx中禁止业务逻辑: 页面仅导入 Widgets/Features;不含任何useEffect/fetch。- 禁止按文件类型分组: 按领域分组(
features/auth/),而不是按类型(components/、hooks/)。 - 禁止过早创建 Entity: 从 Features 开始;仅当严格复用时才移至 Entities。