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

FSD في Next.js بدون عمليات استيراد دورية: الطبقات وواجهة برمجة التطبيقات العامة والتحقق التلقائي

@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 не импортирует ничего из слоёв выше.

Пример с избранным решается композицией на уровне выше: ProductCard из entities принимает слот 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} />} />);
}

Public API слайса

Каждый слайс экспортирует наружу только то, что объявлено в его index.ts:

// entities/product/index.ts
export { ProductCard } from "./ui/ProductCard";
export type { Product } from "./model/types";
export { getProduct } from "./api/getProduct";

Импорт @/entities/product/ui/ProductCard в обход index.ts запрещён. Это позволяет менять внутреннюю структуру слайса, не трогая потребителей.

Когда сущностям нужно знать друг о друге

Order содержит Product, и тип заказа ссылается на тип товара. Для таких случаев в FSD есть нотация @x — отдельный public 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 App Router и FSD

Папки app и pages в FSD совпадают по имени с роутингом 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, проверяет структуру, public 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"] },
        ],
      }],
    },
  },
];

Запрет кросс-импортов внутри одного слоя (features/a → features/b) проверяет Steiger; ESLint-зоны этого не выражают без перечисления каждого слайса.

madge находит уже существующие циклы в проекте:

npx madge --circular --extensions ts,tsx --ts-config tsconfig.json src

import/no-cycle на большом проекте заметно замедляет линтинг; его можно запускать только в 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