चक्रीय आयात के बिना नेक्स्ट.जेएस में एफएसडी: परतें, सार्वजनिक एपीआई और स्वचालित सत्यापन
साइकिलें कहां से आती हैं?
एजेंट "पसंदीदा में जोड़ें" सुविधा जोड़ता है। इसे Product प्रकार की आवश्यकता है, यह इसे entities/product से आयात करता है। फिर आपको उत्पाद कार्ड में एक पसंदीदा बटन एम्बेड करना होगा, और एजेंट features/favorites को सीधे entities/product/ui/ProductCard.tsx में आयात करता है। परिणाम एक चक्र है: सार विशेषता पर निर्भर करता है, विशेषता सार पर। रनटाइम में यह मॉड्यूल आरंभीकरण के दौरान आयातित मूल्य के लिए undefined के रूप में और असेंबली में टुकड़ों के अप्रत्याशित क्रम के रूप में प्रकट होता है।
एफएसडी इसे एक नियम से हल करता है: एक मॉड्यूल केवल अपने से नीचे की परतों से ही आयात कर सकता है, और एक ही परत के स्लाइस एक दूसरे के बारे में नहीं जानते हैं।
निर्भरता की परतें और दिशा
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} />} />);
}सार्वजनिक स्लाइस एपीआई
प्रत्येक स्लाइस केवल वही निर्यात करता है जो उसके 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 नोटेशन है - एक विशिष्ट पड़ोसी के लिए एक अलग सार्वजनिक एपीआई:
// 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 में समान रूप से रखा जाना चाहिए।
नेक्स्ट.जेएस ऐप राउटर और एफएसडी
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स्वचालित जाँच
एजेंट पहले अवसर पर बिना जांच किए नियम तोड़ देगा। तीनों उपकरण एक दूसरे के पूरक हैं।
स्टीगर - आधिकारिक एफएसडी लिंटर, संरचना, सार्वजनिक एपीआई और आयात की दिशा की जांच करता है:
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) स्टीगर द्वारा जांचा गया है; ESLint ज़ोन प्रत्येक स्लाइस को सूचीबद्ध किए बिना इसे व्यक्त नहीं करते हैं।
मैज प्रोजेक्ट में पहले से मौजूद लूप ढूंढता है:
npx madge --circular --extensions ts,tsx --ts-config tsconfig.json src
import/no-cycle एक बड़े प्रोजेक्ट पर लाइनिंग काफी धीमी हो जाती है; इसे संपादक में जोन छोड़कर केवल सीआई में ही चलाया जा सकता है।
एजेंट शासन
- Слои: app > pages > widgets > features > entities > shared. Импорт только вниз. - Слайсы одного слоя не импортируют друг друга. Связь — через композицию на слое выше. - Импорт из слайса только через его index.ts. - Типы соседней сущности — только через entities/<name>/@x/<consumer>.ts. - После изменений запусти npx steiger ./src и исправь все ошибки.
जब एफएसडी अनावश्यक हो
एक लैंडिंग पृष्ठ, एक दर्जन स्क्रीन के लिए व्यवस्थापक पैनल या एक प्रोटोटाइप के लिए, एफएसडी उपयोगी से अधिक फ़ोल्डर जोड़ता है। यह components, lib और app को अलग करने और import/no-cycle को शामिल करने के लिए पर्याप्त है। जब कई लोग या एजेंट एक ही समय में कोड पर काम करते हैं और दो दर्जन से अधिक विशेषताएं होती हैं तो कार्यप्रणाली फायदेमंद होती है।