Next.js 中的 FSD 无需循环导入:层、公共 API 和自动验证
循环从何而来?
该代理添加了“添加到收藏夹”功能。它需要类型 Product,它从 entities/product 导入它。然后,您需要在产品卡中嵌入一个收藏夹按钮,代理将 features/favorites 直接导入到 entities/product/ui/ProductCard.tsx 中。结果就是一个循环:本质依赖于特征,特征依赖于本质。在运行时,这表现为模块初始化期间导入值的 undefined,在汇编中表现为不可预测的块顺序。
FSD 通过一个规则解决了这个问题:模块只能从严格低于其自身的层导入,并且同一层的切片彼此不了解。
依赖的层次和方向
app → инициализация, провайдеры, глобальные стили pages → композиция страниц widgets → крупные самостоятельные блоки (шапка, лента, карточка с действиями) features → пользовательские действия (добавить в избранное, авторизоваться) entities → бизнес-сущности (product, user, order) shared → UI-кит, утилиты, api-клиент, конфиг; без бизнес-логики
只允许从上到下导入:widgets可以使用features、entities、shared;仅 entities - shared。 shared 不会从上面的层导入任何内容。
收藏夹示例通过更高级别的组合来解决:entities 中的 ProductCard 占用 actions 槽,并且 widgets/product-list 向那里传递一个来自 features/favorites 的按钮。
// entities/product/ui/ProductCard.tsx
export function ProductCard({ product, actions }: { product: Product; actions?: React.ReactNode }) {
return (
<div>
<h3>{product.title}</h3>
<span>{product.price}</span>
{actions}
</div>
);
}
// widgets/product-list/ui/ProductList.tsx
import { ProductCard } from "@/entities/product";
import { ToggleFavorite } from "@/features/favorites";
export function ProductList({ items }: { items: Product[] }) {
return items.map(p => <ProductCard key={p.id} product={p} actions={<ToggleFavorite productId={p.id} />} />);
}公共切片API
每个切片仅导出其 index.ts 中声明的内容:
// entities/product/index.ts
export { ProductCard } from "./ui/ProductCard";
export type { Product } from "./model/types";
export { getProduct } from "./api/getProduct";禁止绕过 index.ts 导入 @/entities/product/ui/ProductCard。这允许您更改切片的内部结构而不影响消费者。
当实体需要相互了解时
Order包含Product,订单类型指的是产品类型。对于这种情况,FSD 有 @x 表示法 - 针对特定邻居的单独公共 API:
// entities/product/@x/order.ts
export type { Product } from "../model/types";
// entities/order/model/types.ts
import type { Product } from "@/entities/product/@x/order";
export type Order = { id: string; items: { product: Product; qty: number }[] };这种关系是可见的并且仅限于类型。如果逻辑开始流过 @x,则这是一个信号,表明实体应组合或共同放入 shared 中。
Next.js 应用程序路由器和 FSD
FSD 中的 app 和 pages 文件夹与 Next.js 路由同名。推荐选项:Next.js 路由保留在根 app/ 中,FSD 层位于 src/ 中,并且路由文件仅重新导出页面:
app/
products/[id]/page.tsx → export { ProductPage as default } from "@/pages/product";
src/
app/ # провайдеры, стили
pages/
widgets/
features/
entities/
shared/
pages/README.md # пустая корневая папка, чтобы Next.js не принял src/pages за Pages Router自动检查
代理人会在没有第一时间检查的情况下违反规则。这三种仪器相辅相成。
Steiger - 官方 FSD linter,检查结构、公共 API 和导入方向:
npx steiger ./src
ESLint 与 import/no-restricted-paths 防止直接在编辑器中导入图层:
// eslint.config.mjs (фрагмент)
import importPlugin from "eslint-plugin-import";
export default [
{
plugins: { import: importPlugin },
rules: {
"import/no-cycle": ["error", { maxDepth: 10 }],
"import/no-restricted-paths": ["error", {
zones: [
{ target: "./src/shared", from: ["./src/entities", "./src/features", "./src/widgets", "./src/pages", "./src/app"] },
{ target: "./src/entities", from: ["./src/features", "./src/widgets", "./src/pages", "./src/app"] },
{ target: "./src/features", from: ["./src/widgets", "./src/pages", "./src/app"] },
{ target: "./src/widgets", from: ["./src/pages", "./src/app"] },
],
}],
},
},
];Steiger 检查禁止一层内交叉导入 (features/a → features/b); ESLint 区域不会在不列出每个切片的情况下表达这一点。
madge 找到项目中已经存在的循环:
npx madge --circular --extensions ts,tsx --ts-config tsconfig.json src
import/no-cycle 在大型项目上会显着减慢 linting 速度;它只能在 CI 中运行,在编辑器中留下区域。
代理规则
- Слои: app > pages > widgets > features > entities > shared. Импорт только вниз. - Слайсы одного слоя не импортируют друг друга. Связь — через композицию на слое выше. - Импорт из слайса только через его index.ts. - Типы соседней сущности — только через entities/<name>/@x/<consumer>.ts. - После изменений запусти npx steiger ./src и исправь все ошибки.
当不需要 FSD 时
对于登陆页面、十几个屏幕的管理面板或原型,FSD 添加的文件夹数量超出了其用途。将 components、lib 和 app 分开并包含 import/no-cycle 就足够了。当多个人或代理同时处理代码并且有超过两打功能时,该方法会得到回报。