Next.js-da tsiklik importlarsiz FSD: qatlamlar, ommaviy API va avtomatik tekshirish
Tsikllar qayerdan keladi?
Agent "sevimlilarga qo'shish" funksiyasini qo'shadi. Unga Product turi kerak, uni entities/product dan import qiladi. Keyin mahsulot kartasiga sevimlilar tugmasini joylashtirishingiz kerak va agent features/favorites ni bevosita entities/product/ui/ProductCard.tsx ga import qiladi. Natijada aylanma bo‘ladi: mohiyat xususiyatga, xususiyat mohiyatga bog‘liq. Ishlash vaqtida bu modulni ishga tushirish vaqtida import qilingan qiymat uchun undefined sifatida va yig'ilishda qismlarning oldindan aytib bo'lmaydigan tartibi sifatida namoyon bo'ladi.
FSD buni bitta qoida bilan hal qiladi: modul faqat o'zidan pastdagi qatlamlardan import qilishi mumkin va bir xil qatlamning bo'laklari bir-biri haqida bilishmaydi.
Qatlamlar va bog'liqliklar yo'nalishi
app → инициализация, провайдеры, глобальные стили pages → композиция страниц widgets → крупные самостоятельные блоки (шапка, лента, карточка с действиями) features → пользовательские действия (добавить в избранное, авторизоваться) entities → бизнес-сущности (product, user, order) shared → UI-кит, утилиты, api-клиент, конфиг; без бизнес-логики
Import qilish faqat yuqoridan pastgacha ruxsat etiladi: widgets features, entities, shared dan foydalanishi mumkin; entities - faqat shared. shared yuqoridagi qatlamlardan hech narsani import qilmaydi.
Sevimlilar misoli yuqori darajadagi kompozitsiya bilan hal qilinadi: entities dan ProductCard actions o'rnini oladi va widgets/product-list u yerga features/favorites dan tugmani uzatadi.
// 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} />} />);
}Umumiy tilim API
Har bir boʻlak faqat index.ts da eʼlon qilingan narsani eksport qiladi:
// entities/product/index.ts
export { ProductCard } from "./ui/ProductCard";
export type { Product } from "./model/types";
export { getProduct } from "./api/getProduct";@/entities/product/ui/ProductCard ni chetlab oʻtib, index.ts ni import qilish taqiqlangan. Bu iste'molchilarga ta'sir qilmasdan tilimning ichki tuzilishini o'zgartirishga imkon beradi.
Ob'ektlar bir-birlari haqida bilishlari kerak bo'lganda
Order tarkibida Product mavjud va buyurtma turi mahsulot turiga tegishli. Bunday holatlar uchun FSD @x belgisiga ega - ma'lum bir qo'shni uchun alohida umumiy 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 }[] };Bu munosabatlar ko'rinadi va turlari bilan cheklangan. Agar mantiq @x orqali oqib chiqa boshlasa, bu ob'ektlarni shared ga birlashtirish yoki umumiylashtirish kerakligi haqidagi signaldir.
Next.js App Router va FSD
FSDdagi app va pages papkalari Next.js marshrutlash bilan bir xil nomga ega. Tavsiya etilgan variant: Next.js marshrutlash ildizida app/ qoladi, FSD qatlamlari src/ ichida qoladi va marshrut fayllari faqat sahifalarni qayta eksport qiladi:
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 RouterAvtomatik tekshirish
Agent birinchi imkoniyatda tekshirmasdan qoidalarni buzadi. Uchta asbob bir-birini to'ldiradi.
Steiger - rasmiy FSD linteri, strukturani, ommaviy APIni va import yo'nalishini tekshiradi:
npx steiger ./src
ESLint import/no-restricted-paths bilan toʻgʻridan-toʻgʻri muharrirda qatlamlarni import qilishni oldini oladi:
// 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"] },
],
}],
},
},
];Bir qatlam ichida o'zaro importni taqiqlash (features/a → features/b) Shtayger tomonidan tekshiriladi; ESLint zonalari buni har bir bo'lakni ro'yxatga kiritmasdan bildirmaydi.
madge loyihada allaqachon mavjud bo'lgan tsikllarni topadi:
npx madge --circular --extensions ts,tsx --ts-config tsconfig.json src
import/no-cycle yirik loyihada liniyani sezilarli darajada sekinlashtiradi; uni muharrirda zonalar qoldirib, faqat CI da ishga tushirish mumkin.
Agent qoidasi
- Слои: app > pages > widgets > features > entities > shared. Импорт только вниз. - Слайсы одного слоя не импортируют друг друга. Связь — через композицию на слое выше. - Импорт из слайса только через его index.ts. - Типы соседней сущности — только через entities/<name>/@x/<consumer>.ts. - После изменений запусти npx steiger ./src и исправь все ошибки.
FSD kerak bo'lmaganda
Ochilish sahifasi, o'nlab ekranlar uchun boshqaruv paneli yoki prototip uchun FSD foydali bo'lganidan ko'ra ko'proq papkalarni qo'shadi. components, lib va app ni ajratib, import/no-cycle ni kiritish kifoya. Metodologiya bir vaqtning o'zida bir nechta odam yoki agentlar kod ustida ishlaganda va yigirmadan ortiq xususiyatlar mavjud bo'lganda o'z samarasini beradi.