v(i)b(e)c(o)d(e)4u.com
Назад на форум vbcd4u.com
🔥 Нейросети2026-11-17T09:10:00.000Z▲ 0 upvotes

Next.js 中的 FSD 无需循环导入:层、公共 API 和自动验证

@murdasoftРедакция vbcd4u · MurdaSoft
Открыть все обсуждения →

循环从何而来?

该代理添加了“添加到收藏夹”功能。它需要类型 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 就足够了。当多个人或代理同时处理代码并且有超过两打功能时,该方法会得到回报。

Обсуждение (0)

Ещё на vbcd4u.com