FSD w Next.js bez cyklicznych importów: warstwy, publiczne API i automatyczna weryfikacja
Skąd się biorą cykle?
Agent dodaje opcję „dodaj do ulubionych”. Potrzebuje typu Product, importuje go z entities/product. Następnie należy osadzić przycisk ulubionych w karcie produktu, a agent importuje features/favorites bezpośrednio do entities/product/ui/ProductCard.tsx. Rezultatem jest cykl: esencja zależy od cechy, cecha od esencji. W czasie wykonywania objawia się to jako undefined dla zaimportowanej wartości podczas inicjalizacji modułu, a podczas montażu jako nieprzewidywalna kolejność fragmentów.
FSD rozwiązuje ten problem za pomocą jednej zasady: moduł może importować tylko z warstw położonych bezpośrednio pod nim, a plasterki tej samej warstwy nie wiedzą o sobie.
Warstwy i kierunek zależności
app → инициализация, провайдеры, глобальные стили pages → композиция страниц widgets → крупные самостоятельные блоки (шапка, лента, карточка с действиями) features → пользовательские действия (добавить в избранное, авторизоваться) entities → бизнес-сущности (product, user, order) shared → UI-кит, утилиты, api-клиент, конфиг; без бизнес-логики
Import jest dozwolony tylko od góry do dołu: widgets może używać features, entities, shared; entities – tylko shared. shared nie importuje niczego z powyższych warstw.
Przykład ulubionych został rozwiązany poprzez kompozycję na wyższym poziomie: ProductCard z entities zajmuje miejsce actions, a widgets/product-list przekazuje tam przycisk z features/favorites.
[[VB_1_KOD]]
Publiczne API plasterków
Każdy plasterek eksportuje tylko to, co jest zadeklarowane w jego index.ts:
// entities/product/index.ts
export { ProductCard } from "./ui/ProductCard";
export type { Product } from "./model/types";
export { getProduct } from "./api/getProduct";Importowanie @/entities/product/ui/ProductCard z pominięciem index.ts jest zabronione. Pozwala to na zmianę wewnętrznej struktury plasterka bez wpływu na konsumentów.
Kiedy podmioty muszą się o sobie dowiedzieć
Order zawiera Product, a typ zamówienia odnosi się do rodzaju produktu. W takich przypadkach FSD ma notację @x – osobne publiczne API dla konkretnego sąsiada:
// 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 }[] };Zależność ta jest widoczna i ograniczona do typów. Jeśli logika zacznie przepływać przez @x, jest to sygnał, że byty należy połączyć lub połączyć w shared.
Router aplikacji Next.js i FSD
Foldery app i pages w FSD mają taką samą nazwę jak routing w Next.js. Zalecana opcja: routing Next.js pozostaje w katalogu głównym app/, warstwy FSD znajdują się w src/, a pliki tras reeksportują tylko strony:
[[VB_4_KOD]]
Automatyczne sprawdzenie
Agent złamie zasady bez sprawdzenia przy pierwszej okazji. Te trzy instrumenty uzupełniają się wzajemnie.
Steiger - oficjalny linter FSD, sprawdza strukturę, publiczne API i kierunek importu:
[[VB_5_KOD]]
ESLint z import/no-restricted-paths uniemożliwia importowanie warstw bezpośrednio w edytorze:
// 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"] },
],
}],
},
},
];Zakaz importu krzyżowego w obrębie jednej warstwy (features/a → features/b) sprawdza Steiger; Strefy ESLint nie wyrażają tego bez wyszczególnienia każdego wycinka.
madge znajduje już istniejące pętle w projekcie:
npx madge --circular --extensions ts,tsx --ts-config tsconfig.json src
import/no-cycle w dużym projekcie znacznie spowalnia linting; można go uruchomić tylko w CI, pozostawiając strefy w edytorze.
Reguła agenta
- Слои: app > pages > widgets > features > entities > shared. Импорт только вниз. - Слайсы одного слоя не импортируют друг друга. Связь — через композицию на слое выше. - Импорт из слайса только через его index.ts. - Типы соседней сущности — только через entities/<name>/@x/<consumer>.ts. - После изменений запусти npx steiger ./src и исправь все ошибки.
Gdy FSD jest niepotrzebne
W przypadku strony docelowej, panelu administracyjnego na kilkanaście ekranów lub prototypu, FSD dodaje więcej folderów niż jest to przydatne. Wystarczy oddzielić components, lib i app i dodać import/no-cycle. Metodologia się opłaca, gdy nad kodem pracuje kilka osób lub agentów w tym samym czasie, a funkcji jest więcej niż dwa tuziny.