Döngüsel içe aktarmalar olmadan Next.js'de FSD: katmanlar, genel API ve otomatik doğrulama
Döngüler nereden geliyor?
Temsilci “favorilere ekle” özelliğini ekler. Product türüne ihtiyacı var, onu entities/product'dan içe aktarıyor. Daha sonra ürün kartına bir sık kullanılanlar düğmesi yerleştirmeniz gerekir ve aracı, features/favorites'u doğrudan entities/product/ui/ProductCard.tsx'a aktarır. Sonuç bir döngüdür: Öz, özelliğe, özellik de öze bağlıdır. Çalışma zamanında bu, modülün başlatılması sırasında içe aktarılan değer için undefined olarak ve derlemede parçaların öngörülemeyen bir sırası olarak kendini gösterir.
FSD bunu tek bir kuralla çözer: Bir modül yalnızca kendisinin tam altındaki katmanlardan içe aktarabilir ve aynı katmanın dilimleri birbirini bilmez.
Katmanlar ve bağımlılıkların yönü
app → инициализация, провайдеры, глобальные стили pages → композиция страниц widgets → крупные самостоятельные блоки (шапка, лента, карточка с действиями) features → пользовательские действия (добавить в избранное, авторизоваться) entities → бизнес-сущности (product, user, order) shared → UI-кит, утилиты, api-клиент, конфиг; без бизнес-логики
İçe aktarmaya yalnızca yukarıdan aşağıya doğru izin verilir: widgets, features, entities, shared kullanabilir; Yalnızca entities - shared. shared yukarıdaki katmanlardan hiçbir şeyi içe aktarmaz.
Favoriler örneği daha yüksek düzeydeki kompozisyonla çözülür: entities'dan ProductCard, actions yuvasını alır ve widgets/product-list oraya features/favorites'dan bir düğme iletir.
// 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} />} />);
}Genel dilim API'si
Her dilim yalnızca kendi index.ts dosyasında bildirilenleri dışa aktarır:
// entities/product/index.ts
export { ProductCard } from "./ui/ProductCard";
export type { Product } from "./model/types";
export { getProduct } from "./api/getProduct";index.ts'u atlayarak @/entities/product/ui/ProductCard'un içe aktarılması yasaktır. Bu, tüketicileri etkilemeden dilimin iç yapısını değiştirmenize olanak tanır.
Varlıkların birbirleri hakkında bilgi sahibi olması gerektiğinde
Order, Product içerir ve sipariş türü, ürün türüne karşılık gelir. Bu gibi durumlarda FSD, belirli bir komşu için ayrı bir genel API olan @x notasyonuna sahiptir:
// 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 ilişki görünür ve türlerle sınırlıdır. Mantık @x üzerinden akmaya başlarsa, bu, varlıkların shared içinde birleştirilmesi veya ortak hale getirilmesi gerektiğine dair bir sinyaldir.
Next.js Uygulama Yönlendiricisi ve FSD
FSD'deki app ve pages klasörleri Next.js yönlendirmesiyle aynı ada sahiptir. Önerilen seçenek: Next.js yönlendirmesi app/ kökünde kalır, FSD katmanları src/ içinde yaşar ve dosyaları yalnızca yeniden dışa aktarılan sayfaları yönlendirir:
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 RouterOtomatik kontrol
Temsilci ilk fırsatta kontrol etmeden kuralları çiğneyecektir. Üç enstrüman birbirini tamamlıyor.
Steiger - resmi FSD linter, yapıyı, genel API'yi ve içe aktarma yönünü kontrol eder:
npx steiger ./src
import/no-restricted-paths ile ESLint, katmanların doğrudan düzenleyiciye aktarılmasını önler:
// 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 katman (features/a → features/b) içinde çapraz içe aktarmanın yasaklanması Steiger tarafından kontrol edilir; ESLint bölgeleri her dilimi listelemeden bunu ifade etmez.
madge projede zaten var olan döngüleri bulur:
npx madge --circular --extensions ts,tsx --ts-config tsconfig.json src
Büyük bir projedeki import/no-cycle, astarlamayı önemli ölçüde yavaşlatır; bölgeleri düzenleyicide bırakarak yalnızca CI'da çalıştırılabilir.
Aracı kuralı
- Слои: app > pages > widgets > features > entities > shared. Импорт только вниз. - Слайсы одного слоя не импортируют друг друга. Связь — через композицию на слое выше. - Импорт из слайса только через его index.ts. - Типы соседней сущности — только через entities/<name>/@x/<consumer>.ts. - После изменений запусти npx steiger ./src и исправь все ошибки.
FSD gereksiz olduğunda
Bir açılış sayfası, bir düzine ekranın yönetici paneli veya bir prototip için FSD, kullanışlı olduğundan daha fazla klasör ekler. components, lib ve app'yi ayırıp import/no-cycle'u dahil etmeniz yeterlidir. Metodoloji, birkaç kişi veya temsilcinin aynı anda kod üzerinde çalıştığı ve iki düzineden fazla özelliğin bulunduğu durumlarda karşılığını verir.