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

FSD w Next.js bez cyklicznych importów: warstwy, publiczne API i automatyczna weryfikacja

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

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.

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

Ещё на vbcd4u.com