JavaScript Full-stackClean va Onion arxitektura: dependency rule, Entity va DTO farqi va pragmatik chegara
JavaScript Full-stack · 36-qism. Arxitektura va system design

Clean va Onion arxitektura: dependency rule, Entity va DTO farqi va pragmatik chegara

21 daqiqa13/44-dars

Qisqacha: Clean va Onion arxitektura — hexagonal g'oyasining qatlamli ko'rinishi: markazda biznes obyektlari (entities), ularning atrofida use case'lar, keyin adapterlar, eng chetda freymvork va baza. Hammasini bitta qoida boshqaradi — dependency rule: import faqat ichkariga qarab yo'naladi. Bu darsda shu qoidani loyihaning vazifalar moduliga qo'llab, buzilishlarni sanaymiz. Ularning har biri — xato emas, narxi yozilgan ongli tanlov. Qoidani qachon to'liq bajarish over-engineering bo'lishini ham hisoblaymiz.

Bu darsda

  • Clean arxitekturaning to'rt doirasini va Onion qatlamlarini loyihadagi fayllarga joylaysiz.
  • Dependency rule buzilishini import ro'yxatidan avtomatik topadigan model yozasiz.
  • Bitta vazifaning uch ko'rinishini — Entity, DTO va ORM modeli — farqlaysiz va ularni nega aralashtirmaslik kerakligini tushuntirasiz.
  • Loyihadagi uchta ongli buzilishni narxi bilan tahlil qilasiz va import grafi ko'rmaydigan aylanma yo'lni topasiz.
  • "To'liq Clean" qachon over-engineering bo'lishini hisob-kitob bilan asoslaysiz.

Oldin bilishingiz kerak: Hexagonal arxitektura (Ports and Adapters), Qatlamli arxitektura: controller → service → repository, Zod va turni sxemadan chiqarish, Xato javoblari: Problem Details.

1. Nega bu kerak?

Hexagonal arxitektura darsida webhook obunalarini ikki qismga — ichkari va tashqariga — ajratdik. Ichkarida yana bo'linish bor edi: domen/ (qoida), ilova/ (use case va portlar). Bu ichki bo'linish tasodif emas. Uni ikki mashhur maktab nomlagan: Onion (Jeffrey Palermo, 2008) va Clean Architecture (Robert Martin, 2012).

Ikkalasini ham ko'p loyihalarda "papka shabloni" sifatida ko'rasiz: domain/, application/, infrastructure/, presentation/. Lekin papka nomlari arxitektura emas. Arxitekturani bitta qoida belgilaydi: qaysi fayl qaysi faylni import qilishi mumkin. Papkalar to'g'ri nomlanib, importlar teskari yo'nalsa — bu faqat nom.

Bu darsda nazariyani qisqa ko'rib, keyin o'lchaymiz: vazifalar modulidagi 15 fayl qoidaga qanchalik bo'ysunadi? Natija: buzilishlar ikki manbadan chiqadi va ikkalasi ham kanonda ataylab qoldirilgan. Nega — darsning asosiy qismi. Import grafi ko'rmaydigan yana bir aylanma yo'l ham topiladi — u esa ongli tanlov emas, tarixdan qolgan.

Hayotiy o'xshatish: piyoz (onion). Ichki qatlam tashqi qatlamni bilmaydi va unga tayanmaydi — tashqi qatlamni archib tashlasangiz, ichkarisi butun qoladi. Tashqi qatlam esa ichkini o'rab turadi va unga tegadi. Qobiqni almashtirish mumkin, yurakni emas.

2. Clean arxitektura: to'rt doira

2.1 Doiralar

Robert Martin Clean arxitekturani to'rtta ichma-ich doira bilan chizgan:

Doira Nima yashaydi Webhook tajribasida
Entities korxona darajasidagi qoidalar domen/obuna.ts
Use cases ilovaga xos ssenariylar ilova/obunalar.ts, ilova/portlar.ts
Interface adapters ma'lumotni o'girish: controller, ombor adapterlar/*
Frameworks & drivers Nest, Express, pg, Zod node_modules

Entities (biznes obyektlari) — ilovadan ham uzoq yashaydigan qoidalar. "Bitta egasida ko'pi bilan 5 ta webhook" — mahsulot qoidasi. U web ilovada ham, Telegram botda ham, admin skriptda ham bir xil.

Use cases (foydalanish ssenariylari) — aniq ilovaning ishlari: "obuna yarat: URL'ni tekshir, sir ber, qulf ichida qo'sh". Ssenariy entity qoidalarini chaqiradi va tartibni belgilaydi.

Interface adapters (interfeys adapterlari) — ichkari va tashqari tillari orasidagi tarjimon. Controller HTTP so'rovini use case argumentlariga aylantiradi. Ombor Obuna obyektini SQL qatoriga aylantiradi.

Frameworks and drivers — eng tashqi qatlam: Nest, Express, Postgres drayveri, Zod. Martin buni "tafsilot" deydi. Tafsilot muhim emas degani emas — uni almashtirish mumkin degani.

Doiralar soni qat'iy emas. Martin maqolasida o'zi "Faqat to'rt doirami?" deb so'raydi va "yo'q, doiralar sxematik" deb javob beradi. Kerak bo'lsa doira qo'shiladi yoki ikkitasi birlashadi. O'zgarmaydigan yagona narsa — keyingi bo'limdagi qoida.

2.2 Dependency rule

Butun sxemani bitta jumla boshqaradi: manba kodidagi bog'liqliklar faqat ichkariga yo'nalishi mumkin. Ichki doiradagi kod tashqi doiradagi hech narsaning nomini bilmaydi — na klass, na funksiya, na tur.

Amalda bu import yo'nalishi: domen/obuna.ts hech narsani import qilmaydi; ilova/obunalar.ts faqat domen/ va o'z portlarini; adapterlar esa ichkaridagi hamma narsani. Teskari strelka — domen/ dan adapterlar/ ga — qoida buzilishi.

Ma'lumot esa ikki tomonga oqadi: so'rov tashqaridan ichkariga keladi, javob ichkaridan tashqariga chiqadi. Qoida ma'lumot oqimi haqida emas, kod bog'liqligi haqida. Ichkari tashqariga javob qaytarishi uchun uning nomini bilishi shart emas — u o'zi e'lon qilgan tur va portdan foydalanadi. Bu SOLID 2: LSP, ISP, DIP darsidagi bog'liqlik inversiyasi.

Tekshirib ko'ring: Use case natijasini HTTP javobiga aylantirish kerak. Use case res.status(201).json(…) ni o'zi chaqirsa, qaysi qoida buziladi va qanday tuzatiladi?

Javob

Dependency rule: use case doirasidagi kod eng tashqi doiradagi Express'ning Response turini biladi. Tuzatish — use case oddiy qiymat qaytaradi ({ obuna, sir }), controller esa uni 201 va JSON'ga aylantiradi. Hexagonal darsidagi 2-mashqda aynan shu ishni kiruvchi adapter qilgan edi.

2.3 Use case chegarasi: kiruvchi va chiquvchi model

Martin kitobida use case chegarasi yana bitta qatlam bilan chiziladi. Controller use case'ga kiruvchi model (input model) beradi — oddiy obyekt, HTTP'siz. Use case natijani chiquvchi model (output model) sifatida qaytaradi. Keyin presenter (taqdim etuvchi) uni ekranga yoki JSON'ga mos ko'rinishga keltiradi.

Webhook tajribasida bu qatlamlar alohida yozilmadi, lekin ularning izi bor:

Clean atamasi Webhook tajribasida
kiruvchi model yarat(egasi, url, hodisalar) argumentlari
chiquvchi model { obuna, sir } qiymati
presenter yozilmagan kiruvchi adapter: 201 va JSON

Klass emas, oddiy argument va qaytgan qiymat. Bu ham Clean — faqat ixcham. Kitobdagi har bo'lakni alohida klass qilib yozish shart emas. Shart bitta: use case HTTP'ni ham, JSON shaklini ham bilmasin.

3. Onion arxitektura

3.1 Qatlamlar

Jeffrey Palermo Onion arxitekturani Clean'dan to'rt yil oldin tasvirlagan. Qatlamlari:

  • Domain model — biznes obyektlari va qiymatlari;
  • Domain services — bir nechta obyektga tegadigan qoidalar;
  • Application services — ssenariylar, tranzaksiya chegarasi;
  • Infrastructure va UI — eng tashqi qobiq: baza, HTTP, testlar.

Palermo bitta muhim detalni alohida aytadi. Ombor (repository) interfeyslari domen modeli atrofidagi ichki qatlamda turadi. Ularning SQL'li bajarilishi esa tashqi qobiqda. Hexagonal arxitektura darsidagi ObunaOmbori porti va Pg adapteri — aynan shu bo'linish.

Onion'ning Clean'dan asosiy farqi — nomlar va bitta urg'u. Palermo infratuzilmani (bazani) UI bilan bir qatlamga qo'ydi. An'anaviy qatlamli sxemada esa baza eng pastda, hamma narsa unga tayanadi. Onion bu piramidani ag'darib, bazani chetga chiqardi.

3.2 Uch maktab — bitta g'oya

flowchart TB
  subgraph T["tashqi: Nest, Express, pg, Zod"]
    subgraph A["adapterlar: controller, ombor"]
      subgraph U["use case: ObunaXizmati, portlar"]
        E["entities: Obuna, yangiObuna"]
      end
    end
  end

Diagrammada qutilar bir-birining ichida. Ichki quti tashqi qutining mavjudligini bilmaydi. Hexagonal, Onion va Clean — bir xil rasmning uch xil chizilishi:

Maktab Necha qism Urg'usi
Hexagonal ichkari va tashqari portlar, almashtiriladigan adapter
Onion 4 qatlam baza — markaz emas, chet
Clean 4 doira dependency rule nomi va ta'rifi

Kursda bu nomlarni bir-biriga qarshi qo'ymaymiz. Ularning umumiy qismini olamiz: domen markazda, bog'liqlik ichkariga, freymvork chetda.

4. O'lchov: vazifalar modulida dependency rule

4.1 Fayllarni doiralarga joylash

vazifalar modulida 15 fayl. Ularni doiralarga quyidagicha joyladik:

Doira Fayllar
0 — entities vazifa.ts
1 — use cases ombor.ts (port), royxat-mantiq.ts, vazifalar.service.ts
2 — adapterlar controller'lar, sxema.ts, sorov.ts, beshta ombor, tinglovchi
3 — freymvork @nestjs/*, nestjs-cls, zod, pg, modul fayli

Bitta ehtiyot: umumiy/xatolar.ts ni 2-doiraga qo'ydik. Sababi keyinroq — undagi xatolar HTTP holat kodini biladi.

4.2 Tekshiruvchi model

Endi har importni tekshiramiz: manba doirasi nishon doirasidan kichik bo'lsa — ichkaridan tashqariga strelka, ya'ni buzilish. Ma'lumot — webhook tajribasidan to'rtta fayl va vazifalar dan to'rtta fayl, haqiqiy importlardan:

js
const doira = {
  "domen/obuna.ts": 0, "ilova/portlar.ts": 1,
  "ilova/obunalar.ts": 1, "adapterlar/pg-ombor.ts": 2,
  "vazifa.ts": 0, "ombor.ts": 1, "royxat-mantiq.ts": 1,
  "vazifalar.service.ts": 1, "sxema.ts": 2, "pg-ombor.ts": 2,
  "umumiy/xatolar.ts": 2, "zod": 3, "pg": 3,
  "@nestjs/common": 3, "@nestjs/event-emitter": 3,
  "nestjs-cls": 3,
};

// [loyiha, fayl, import, faqat tur?]
const importlar = [
  ["webhook", "ilova/portlar.ts", "domen/obuna.ts", true],
  ["webhook", "ilova/obunalar.ts", "domen/obuna.ts", false],
  ["webhook", "ilova/obunalar.ts", "ilova/portlar.ts", true],
  ["webhook", "adapterlar/pg-ombor.ts", "pg", true],
  ["webhook", "adapterlar/pg-ombor.ts", "ilova/portlar.ts", true],
  ["vazifalar", "vazifa.ts", "zod", true],
  ["vazifalar", "vazifa.ts", "sxema.ts", true],
  ["vazifalar", "ombor.ts", "vazifa.ts", true],
  ["vazifalar", "royxat-mantiq.ts", "ombor.ts", true],
  ["vazifalar", "vazifalar.service.ts", "@nestjs/common", false],
  ["vazifalar", "vazifalar.service.ts", "@nestjs/event-emitter",
    false],
  ["vazifalar", "vazifalar.service.ts", "nestjs-cls", false],
  ["vazifalar", "vazifalar.service.ts", "umumiy/xatolar.ts", false],
  ["vazifalar", "vazifalar.service.ts", "ombor.ts", true],
  ["vazifalar", "pg-ombor.ts", "pg", false],
  ["vazifalar", "pg-ombor.ts", "vazifa.ts", false],
];

for (const loyiha of ["webhook", "vazifalar"]) {
  const bular = importlar.filter((x) => x[0] === loyiha);
  const buzilish = bular.filter(([, f, n]) =>
    doira[f] <= 1 && doira[f] < doira[n]);
  console.log(`${loyiha}: ${bular.length} import, ` +
    `${buzilish.length} buzilish`);
  for (const [, f, n, tur] of buzilish) {
    console.log(`  ${f} → ${n}${tur ? " (faqat tur)" : ""}`);
  }
}

Konsolda:

text
webhook: 5 import, 0 buzilish
vazifalar: 11 import, 6 buzilish
  vazifa.ts → zod (faqat tur)
  vazifa.ts → sxema.ts (faqat tur)
  vazifalar.service.ts → @nestjs/common
  vazifalar.service.ts → @nestjs/event-emitter
  vazifalar.service.ts → nestjs-cls
  vazifalar.service.ts → umumiy/xatolar.ts

Webhook tajribasi — toza: beshta importning hammasi ichkariga yoki yonma-yon. vazifalar da oltita buzilish bor, lekin ular ikki manbadan chiqadi: entity fayli vazifa.ts va use case fayli vazifalar.service.ts. Ro'yxat to'liq emas — har fayldan tanlangan importlar. Lekin ikkala manba ham haqiqiy.

Kod haqida: doira[f] <= 1 — faqat ikki ichki doira tekshiriladi. Adapterlar freymvorkdan foydalanishi mumkin: Martin ta'rifiga ko'ra SQL va HTTP aynan adapter qatlamida yashaydi. doira[f] < doira[n] — manba ichkariroqda, nishon tashqariroqda. "..." + — uzun satrni ikki qatorga bo'lish.

4.3 Natijani halol o'qish

Model jadvali bizning joylashtirishimiz. royxat-mantiq.ts ni 0-doiraga qo'ysak, u ham buzilish bo'lardi: u ombor.ts dagi Filtr va Saralash turlarini oladi. Biz uni use case doirasiga qo'ydik, chunki ro'yxatni filtrlash va sahifalash — ilova ssenariysi, biznes qoidasi emas. Boshqa odam boshqacha joylashtirishi mumkin.

Bu muhim saboq: dependency rule'ni avtomatik tekshirish uchun avval har faylning doirasini yozib qo'yish kerak. Papka nomi buni berishi mumkin (domen/, ilova/), lekin vazifalar modulida doiralar papka bilan emas, fayl nomi bilan ajratilgan. Shuning uchun linter qoidasini yozish ham qiyinroq: Coupling, cohesion va modul chegaralari darsidagi ESLint qoidasi papka bo'yicha ishlaydi.

Amalda uchta yo'l bor. Birinchisi — papkalar: vazifalar/domen/, vazifalar/ilova/, vazifalar/adapterlar/. Linter qoidasi oddiy, lekin har modulda uch-to'rt papka paydo bo'ladi va kichik modul uchun bu ortiqcha. Ikkinchisi — fayl nomi qo'shimchasi: *.entity.ts, *.usecase.ts, *.adapter.ts. Nest loyihalarida *.controller.ts, *.service.ts qo'shimchalari allaqachon shu ishni qisman bajaradi. Uchinchisi — maxsus vosita sozlamasi: eslint-plugin-boundaries'da har element turi naqsh bilan e'lon qilinadi va ruxsat etilgan yo'nalishlar ro'yxati yoziladi (biz sinamadik).

Qaysi yo'l bo'lmasin, qoida avval yozilgan kelishuv bo'lishi kerak, keyin vosita. Kelishuvsiz linter faqat shovqin chiqaradi.

5. Bitta vazifa, bir necha ko'rinish

5.1 ORM modeli, qator va entity

Clean arxitekturaning eng amaliy saboqlaridan biri: bitta narsa — bir nechta ko'rinish. vazifalar-api da bitta vazifa kamida to'rt xil shaklda yashaydi:

Ko'rinish Qayerda Maydonlar
Prisma modeli schema.prisma 15 ta + 6 bog'lanish
SQL qatori (VazifaQatori) pg-ombor.ts 7 ta, snake_case, Date
Entity (Vazifa) vazifa.ts 8 ta, ISO satr, teglar
Kiruvchi DTO (YangiVazifa) sxema.ts 2 ta: matn, bajarildi

ORM modeli — jadvalning aniq nusxasi: ustuvorlik, muddat, ota_id, izohlar_soni, qidiruv ustuni (tsvector) va boshqalar. Entity esa faqat qoidalar va API ko'radigan maydonlarni oladi. teglar — bazada alohida jadvalda, entity'da esa matndan hisoblanadigan maydon.

DTO (Data Transfer Object, ma'lumot uzatish obyekti) — chegara orqali o'tadigan shakl. Kiruvchi DTO "mijoz nima yubora oladi" degan savolga javob beradi. id, versiya, yaratildi unda yo'q: ularni mijoz bermaydi.

5.2 Tarjimon funksiya

Qatorni entity'ga aylantiradigan funksiya — interface adapter'ning yuragi (pg-ombor.ts, qatorga bo'lindi):

ts
function vazifa(q: VazifaQatori): Vazifa {
  return {
    id: q.id,
    matn: q.matn,
    bajarildi: q.bajarildi,
    // teglar matndan — xotira ombori bilan aynan bir xil qoida
    teglar: teglariniOl(q.matn),
    yaratildi: q.yaratilgan_vaqt.toISOString(),
    yangilandi: q.yangilangan_vaqt.toISOString(),
    tartib: q.tartib,
    versiya: q.versiya,
  };
}

Uch ish bitta joyda: nomlarni o'zgartirish (yaratilgan_vaqt → yaratildi), turni o'zgartirish (Date → ISO satr), hisoblash (teglar). Agar ertaga ustun nomi o'zgarsa — faqat shu funksiya o'zgaradi. Entity va undan foydalanadigan hamma kod bilmaydi ham.

Shu funksiyaning nusxasi Prisma omborida ham bor. Ikki adapter — ikki tarjimon, bitta entity. Ombor shartnoma testi (Repository naqshi va qatlamlar) ikkalasining natijasi bir xil ekanini tekshiradi.

5.3 Nega aralashtirmaslik kerak

ORM modelini to'g'ridan API javobi qilib qaytarish — eng ko'p uchraydigan qisqa yo'l. Natijasi:

  • ochirilganVaqt, qidiruv, egasiId kabi ichki maydonlar mijozga chiqadi;
  • ustun nomi o'zgarsa — API buziladi;
  • BigInt JSON'ga aylanmaydi (TypeError: Do not know how to serialize a BigInt).

Teskarisi ham xavfli: kiruvchi DTO'ni to'g'ridan bazaga yozish. Mijoz egasiId yoki versiya yuborsa, ular jim yozilib ketishi mumkin — bu mass assignment hujumi. vazifalar-api sxemalari z.strictObject bilan yozilgan: noma'lum maydon — 400 (Zod va Standard Schema NestJS'da).

Tekshirib ko'ring: Vazifa entity'si API javobi sifatida ham ishlatiladi — alohida "javob DTO"si yo'q. Bu qaysi xavfni qoldiradi?

Javob

Entity'ga yangi maydon qo'shilsa, u avtomatik API javobiga ham chiqadi. Masalan, ichki egasi maydoni qo'shilsa — u mijozga ham ketadi. Kanon bu xavfni qabul qilgan: Vazifa turi ataylab faqat ommaviy maydonlardan iborat, ichki maydonlar (egasi_id, ochirilgan_vaqt) entity'ga kirmaydi. Narxi — kelishuv qoidasi kodda emas, odamlar xotirasida. Katta jamoada alohida javob DTO'si arzonroq bo'lardi.

6. Uchta ongli buzilish va bitta aylanma yo'l

O'lchov ikki manbani ko'rsatdi. Ularni uchta qarorga ajratamiz, keyin o'lchov ko'rmagan to'rtinchi holatni ko'ramiz.

6.1 Entity turlari Zod sxemasidan

vazifa.ts boshida:

ts
import type { z } from "zod";
import type {
  OzgarishSxemasi, ToliqVazifaSxemasi, YangiVazifaSxemasi,
} from "./sxema.ts";

export type YangiVazifa = z.output<typeof YangiVazifaSxemasi>;

Entity doirasi tashqi kutubxonaning (Zod) va adapter faylining nomini biladi. Toza Clean bo'yicha YangiVazifa turi vazifa.ts da qo'lda yozilishi, sxema esa unga moslashishi kerak edi.

Kanon nega bunday qilmadi? Fayl boshidagi izohda javob bor: "tur qo'lda takrorlanmaydi". Qo'lda yozilgan tur va Zod sxemasi — bitta bilimning ikki nusxasi. Biri o'zgarsa, ikkinchisi jim eskiradi. Asosiy tamoyillar: DRY, KISS, YAGNI, kompozitsiya darsidagi DRY bu yerda dependency rule'dan ustun qo'yildi.

Narxi qanchalik katta? Import import type — JS'ga o'girilganda o'chadi. Ish vaqtida entity Zod'ni yuklamaydi. Zod'ni boshqa kutubxonaga almashtirsangiz — vazifa.ts dagi uch qator o'zgaradi. Qaror arzon, foyda aniq.

6.2 Use case'da HTTP holat kodli xato

vazifalar.service.ts limit oshganda KonfliktXatosi tashlaydi — bu IlovaXatosi ning 409 holatli vorisi. Use case HTTP tilida gapiryapti. Webhook tajribasida esa domen ObunaLimitiXatosi tashlardi — holat kodsiz.

Kanon nega HTTP'li xatolarni tanladi? Loyihaning hamma kirish yo'li — HTTP. Telegram bot va MCP serveri ham API orqali ishlaydi. Xato bir marta yaratiladi va Problem Details filtri (Xato javoblari: Problem Details) uni to'g'ridan javobga aylantiradi. Xaritalash qatlami yo'q — kod kam.

Narxi: ertaga navbat ishchisi VazifalarService.yarat() ni chaqirsa, u "409" ni oladi. Ishchi uchun 409 ma'nosiz — u "ro'yxat to'lgan" degan faktni kutadi. Ishchida xato.kod === "royxat-toldi" tekshiruvi buni yumshatadi: kod mashina o'qiydigan nom sifatida hamma kanalda ishlaydi.

6.3 Use case'da freymvork

VazifalarService uchta freymvork paketini biladi: @Injectable() dekoratori, EventEmitter2 va ClsService. Dekorator — faqat metama'lumot. Lekin ClsService dan so'rov egasini olish use case'ni Nest'ning so'rov kontekstiga bog'laydi.

Modular monolit va hexagonal arxitektura NestJS'da darsida buni "o'lchovli qaror" degandik. Endi narxini aniqroq aytamiz. Bu xizmatni Nest'siz chaqirib bo'lmaydi: unit testlar ClsService ning soxta nusxasini beradi (NestJS unit testlari). Yutug'i — har metodga egasi argumentini uzatish shart emas, xavfsizlik konteksti (RLS egasi) bitta joydan keladi.

6.4 Aylanma yo'l: muddat use case'ni chetlab o'tadi

Import o'lchovi ko'rmaydigan yana bir holat bor. Vazifaning muddati PUT /v1/vazifalar/:id/muddat orqali qo'yiladi. Bu marshrut vazifalar modulida emas, navbat modulida. U VazifalarService ni chaqirmaydi — to'g'ridan SQL yozadi (bo'lak):

text
UPDATE vazifalar SET muddat = $3
 WHERE id = $1 AND egasi_id = $2 AND ochirilgan_vaqt IS NULL

Fayl boshidagi izoh sababini aytadi: API'dagi Vazifa turida muddat yo'q (25–28-qismlar shartnomasi), shuning uchun u alohida resurs qilingan. Telegram bot ham shu ustunga o'zi yozadi.

Clean nuqtai nazaridan bu — adapter boshqa modulning entity'siga use case'siz tegishi. Natijasi kodda ko'rinadi: vazifalar ombori har yozuvda egasi qatorini qulflaydi va ro'yxat versiyasini oshiradi. Muddat yozuvida bu ikkalasi yo'q. Bu xatomi? Kanon testlari yashil va muddat ro'yxat tartibiga ta'sir qilmaydi. Lekin ertaga "muddati o'tgan vazifani bajarib bo'lmaydi" degan qoida paydo bo'lsa, u ikki joyda yozilishi kerak bo'ladi.

Bu ongli qaror emas, tarixiy qatlam: ustun 26-qismda paydo bo'lgan, API shartnomasi esa avvalroq qotgan. Bunday joylarni topishning yagona yo'li — import grafi emas, jadval bo'yicha qidiruv: "vazifalar jadvaliga kim yozadi?". Bu savolni Mikroservislar: dekompozitsiya va ma'lumot egaligi darsida butun loyiha uchun o'lchaymiz.

7. Over-engineering xavfi: hisob-kitob

"To'liq Clean" vazifalar moduli uchun nimani talab qilardi? Martin kitobidagi sxema bo'yicha har use case uchun: kiruvchi port (interfeys), kiruvchi model, chiquvchi model, interactor (bajaruvchi) va presenter (natijani ko'rinishga aylantiruvchi). Ya'ni har ssenariyga besh bo'lak.

VazifalarService da to'qqizta ochiq metod — to'qqizta use case: royxat, teglar, ol, yarat, yangila, almashtir, almashtirHammasi, toplamYarat, ochir. Hisob:

text
9 use case × 5 bo'lak = 45 ta tur yoki klass
hozir: 1 xizmat klassi + 3 kiruvchi tur (Zod'dan) + 1 entity

Bu sinalmagan taxmin — haqiqiy son bir oz kam bo'lishi mumkin: ba'zi modellar umumiy bo'ladi. Lekin tartib aniq: o'nlab yangi tur, har biri bir-ikki qatorli tarjima bilan. Webhook tajribasida uchta use case uchun o'lchangan narx +54 % qator edi — va u yerda presenter ham, alohida modellar ham yo'q edi.

Foyda nima bo'lardi? Use case'lar Nest'siz testlanardi. Lekin vazifalar qoidalari kam: limit, versiya, bajarildi o'tishi. Ular allaqachon ombor shartnoma testlari va Vitest bilan qamrab olingan. Ko'p qoidasiz CRUD modul uchun to'liq Clean — qog'oz ko'chirish.

Pragmatik chegara shunday: dependency rule'ni domen qoidasi yashaydigan joyda qat'iy tuting, qolgan joyda — o'lchab qaror qiling. Qachon qat'iyroq kerak:

  • domen qoidalari ko'p va murakkab (to'lov, tarif, rejalashtirish);
  • bir nechta kirish kanali bor va ular HTTP orqali emas (navbat ishchisi, CLI, boshqa xizmat);
  • jamoa katta va kelishuvni linter saqlashi kerak.

jamoa capstone'ida birinchi shart bajariladi: billing (tarif, obuna holatlari, limitlar) — haqiqiy domen qoidalari. Shuning uchun dizayn hujjati to'lov uchun port tanlagan, vazifalar moduli uchun esa yo'q.

Tekshirib ko'ring: Jamoangizda 6 dasturchi, ilovada 40 ta endpoint, ularning 35 tasi oddiy CRUD, 5 tasi to'lov va tarif bilan bog'liq. "Hamma joyda Clean" va "hech qayerda" o'rtasida qanday chegara chizasiz?

Javob

To'lov va tarif moduliga to'liq qatlamlar: entity, use case, portlar, adapterlar — chunki u yerda qoidalar ko'p va provayderlar almashadi. 35 ta CRUD endpoint — oddiy controller → xizmat → ombor, dependency rule faqat qiymat importlari uchun linter bilan. Chegara modul bo'yicha chiziladi, butun loyiha bo'yicha emas. Bu qarorni ADR qilib yozing (Arxitektura qarorlari: ADR va C4 diagrammalar) — aks holda yangi dasturchi bitta modulni ko'rib, hamma joyni shunday qiladi.

8. Ko'p uchraydigan xatolar

8.1 Papka nomini arxitektura deb bilish

domain/ papkasidagi fayl @prisma/client ni import qilsa, papka nomi hech narsani himoya qilmaydi. Arxitektura — import yo'nalishi.

8.2 ORM modelini hamma joyga uzatish

Prisma turi controller javobigacha borsa, ichki maydonlar chiqadi va ustun nomi API'ga aylanadi. Chegarada tarjimon funksiya bo'lsin.

8.3 Har qatlamga bir xil DTO nusxasi

CreateTaskDto, CreateTaskCommand, CreateTaskInput — uchta bir xil tur. Farqi bo'lmasa, bitta yetadi. Ko'rinishlar faqat farq qilganda ajratiladi: maydonlar, nomlar yoki turlar boshqa bo'lsa.

8.4 Dependency rule'ni turlarga ham qat'iy qo'llash

import type ish vaqtida yo'q. Uni taqiqlash ko'pincha takror tur yozishga olib keladi — bu DRY buzilishi. Avval qiymat importlarini tartibga keltiring.

8.5 Buzilishni sababsiz qoldirish

Ongli buzilish bilan tasodifiy buzilishning farqi — yozilgan sabab. vazifa.ts boshidagi izoh shu vazifani bajaradi. Izohsiz qolgan har buzilish keyingi dasturchi uchun "bu yerda qoida yo'q" degan signal.

8.6 Faqat importga qarash

Import grafi toza bo'lishi mumkin, lekin modul boshqa modulning jadvaliga to'g'ridan SQL yozadi. muddat marshruti shunday: u vazifalar dan hech narsa import qilmaydi, lekin uning jadvalini o'zgartiradi. Chegarani tekshirishda kod bog'liqligi ham, ma'lumot bog'liqligi ham qaralsin.

9. Mashqlar

Mashqlar kurs/mashqlar/36/13-clean-onion/ da. 2- va 3-mashq yechimlari Node 24.21.0 da tekshirilgan (biz ishga tushirdik).

1-mashq (oson): bo'shliqlarni to'ldiring

  • Clean arxitekturaning eng ichki doirasi —
  • Bog'liqlik faqat ichkariga yo'nalishi haqidagi qoida — dependency
  • Chegara orqali o'tadigan ma'lumot shakli —
  • Onion arxitekturada baza qaysi qatlamda —
  • vazifalar.service.ts dagi to'qqizta use case uchun "to'liq Clean" taxminan nechta bo'lak talab qiladi —
Yechim
  • entities — biznes obyektlari va qoidalar.
  • rule — import faqat ichkariga.
  • DTO — Data Transfer Object; masalan YangiVazifa.
  • infrastructure — UI bilan birga eng tashqi qobiqda.
  • 45 — 9 × 5; sinalmagan taxmin.

2-mashq (o'rta): qatlam xaritasidan tekshiruvchi

Darsdagi model fayl nomlarini qo'lda joylashtirdi. Endi papka nomidan aniqlang: domen/ — 0, ilova/ — 1, adapterlar/ va kirish/ — 2, paket nomi (/ bilan boshlanmaydigan va .ts bilan tugamaydigan) — 3. buzilishlar(importlar) funksiyasi [fayl, import] juftlarini olib, ichkaridan tashqariga yo'nalganlarini qaytarsin. Darsdagidek faqat 0 va 1 qatlam tekshiriladi: adapter paketdan foydalanishi mumkin. Kichik loyiha: to'rt qatlam, oltita import. Har buzilishni chiqaring va oxirida soni.

Ishora: split("/")[0] — birinchi papka (Kesish, bo'lish va to'ldirish). Paket nomi .ts bilan tugamaydi — endsWith(".ts") yetarli.

Yechim
js
const QATLAM = { domen: 0, ilova: 1, adapterlar: 2, kirish: 2 };

function qatlam(yol) {
  if (!yol.endsWith(".ts")) return 3; // paket
  return QATLAM[yol.split("/")[0]];
}

function buzilishlar(royxat) {
  return royxat.filter(([f, n]) =>
    qatlam(f) <= 1 && qatlam(f) < qatlam(n));
}

const importlar = [
  ["ilova/tolov.ts", "domen/pul.ts"],
  ["domen/pul.ts", "decimal.js"],
  ["adapterlar/payme.ts", "ilova/portlar.ts"],
  ["ilova/tolov.ts", "adapterlar/payme.ts"],
  ["kirish/tolov.controller.ts", "ilova/tolov.ts"],
  ["kirish/tolov.controller.ts", "@nestjs/common"],
];

const b = buzilishlar(importlar);
for (const [f, n] of b) console.log(`${f} → ${n}`);
console.log(`${b.length} buzilish`);

Konsolda:

text
domen/pul.ts → decimal.js
ilova/tolov.ts → adapterlar/payme.ts
2 buzilish

Ikkala buzilish har xil og'irlikda. ilova/tolov.ts → adapterlar/payme.ts — haqiqiy muammo: use case Payme'ni nomma-nom biladi, Click qo'shilsa use case o'zgaradi. Tuzatish — port. domen/pul.ts → decimal.js — munozarali: aniq hisob kutubxonasi domenga kerak bo'lishi mumkin. Ko'p jamoalar bunday "standart kutubxona darajasidagi" paketlarga istisno beradi — xuddi vazifa.ts dagi Zod turlari kabi. Qoida qaysi biri ekanini aytmaydi — buni siz yozib qo'yasiz.

3-mashq (qiyin): uch ko'rinish tarjimoni

Ikki tarjimon yozing. entityga(qator) SQL qatorini entity'ga aylantirsin: yaratilgan_vaqt (Date) → yaratildi (ISO satr), teglar — matndagi #so'z lardan (kichik harf, takrorsiz), egasi_id va ochirilgan_vaqt entity'ga kirmasin. javobga(entity) entity'ni API javobiga aylantirsin: hamma maydon + etag — " belgisi bilan o'ralgan versiya ("3"). Bitta qator bilan sinang va ikkala natijani JSON.stringify bilan chiqaring.

Ishora: teglar uchun matchAll(/#(\p{L}+)/gu) va new Set (Set). toISOString() — Date ni ISO satrga aylantiradi.

Yechim
js
function entityga(q) {
  const teglar = [...new Set(
    [...q.matn.matchAll(/#(\p{L}+)/gu)]
      .map((m) => m[1].toLowerCase()))];
  return {
    id: q.id,
    matn: q.matn,
    bajarildi: q.bajarildi,
    teglar,
    yaratildi: q.yaratilgan_vaqt.toISOString(),
    versiya: q.versiya,
  };
}

function javobga(v) {
  return { ...v, etag: `"${v.versiya}"` };
}

const qator = {
  id: 7, egasi_id: 1, matn: "Non olish #bozor #Bozor #uy",
  bajarildi: false, versiya: 3, ochirilgan_vaqt: null,
  yaratilgan_vaqt: new Date("2026-11-09T05:00:00Z"),
};

const v = entityga(qator);
console.log(JSON.stringify(v));
console.log(JSON.stringify(javobga(v)));
console.log("egasi_id" in v, "ochirilgan_vaqt" in v);

Konsolda:

text
{"id":7,"matn":"Non olish #bozor #Bozor #uy","bajarildi":false,"teglar":["bozor","uy"],"yaratildi":"2026-11-09T05:00:00.000Z","versiya":3}
{"id":7,"matn":"Non olish #bozor #Bozor #uy","bajarildi":false,"teglar":["bozor","uy"],"yaratildi":"2026-11-09T05:00:00.000Z","versiya":3,"etag":"\"3\""}
false false

#Bozor va #bozor bitta teg bo'ldi: avval kichik harfga, keyin Set. Ichki maydonlar entity'ga o'tmadi — in ikkalasi uchun false. etag JSON'da "\"3\"" ko'rinishida: qo'shtirnoq satrning bir qismi, JSON uni ekranlaydi. HTTP sarlavhasida u "3" bo'lib chiqadi. Loyihadagi tarjimon soddalashtirilgan: haqiqiy teg qoidasi raqam, _ va apostrofni ham qabul qiladi.

10. Real ishda

  • Katta korporativ loyihalarda (bank, sug'urta, logistika) Clean yoki Onion papka shabloni ko'p uchraydi. Ko'pincha shablon bor, qoida esa linter bilan tekshirilmaydi — natijada papkalar to'g'ri, importlar aralash. Ishga kirganda birinchi savol: "chegaralarni nima saqlaydi?"
  • NestJS ekotizimida @nestjs/cqrs va DDD shablonlari Clean qatlamlarini ishlatadi (CQRS moduli). Ularni CRUD modulga olib kirishdan oldin uch savolni bering.
  • Mobil va frontend — Clean g'oyasi u yerda ham: React komponenti API mijozini emas, "hook" yoki "servis" portini biladi.
  • Intervyu savollari: "Clean va hexagonal farqi?", "Dependency rule nima?", "Entity va DTO farqi?", "Qachon Clean'ni tanlamaysiz?". Oxirgisiga hisob bilan javob — 9 use case × 5 bo'lak — kuchli taassurot qoldiradi.

Xulosa

  • Clean (4 doira) va Onion (4 qatlam) — hexagonal g'oyasining qatlamli ko'rinishi; yuragi — dependency rule: import faqat ichkariga.
  • Dependency rule'ni tekshirish uchun avval har faylning doirasi yozilishi kerak; papka nomi yetarli bo'lmasligi mumkin.
  • vazifalar modulida buzilishlar ikki manbadan: entity turlari Zod'dan (DRY uchun, faqat tur) va use case'da freymvork hamda HTTP'li xatolar.
  • Bitta vazifa — to'rt ko'rinish: Prisma modeli (15 maydon), SQL qatori (7), entity (8), kiruvchi DTO (2); ular orasida tarjimon funksiyalar.
  • Import grafi hamma narsani ko'rsatmaydi: muddat marshruti vazifalar dan hech narsa import qilmaydi, lekin uning jadvaliga to'g'ridan yozadi va egasi qulfini chetlab o'tadi — bu ma'lumot bog'liqligi, uni jadval bo'yicha qidirib topish kerak.
  • To'liq Clean vazifalar uchun ~45 bo'lak talab qilardi — kam qoidali CRUD modul uchun over-engineering; qat'iylik domen qoidalari ko'p joyda kerak.

Keyingi dars: DDD strategik: ubiquitous language, bounded context — jamoa loyihasi uchun umumiy til lug'atini tuzamiz va bir so'zning uch xil ma'nosini kontekstlarga ajratamiz.

Manbalar

36-qism. Arxitektura va system design · 13-dars yakunlandi

Clean va Onion arxitektura: dependency rule, Entity va DTO farqi va pragmatik chegara

21 daqvaqt
0belgi
Keyingi dars: DDD strategik: ubiquitous language, bounded context va context map — jamoa loyihasida
Telegram'da
Darsda xato koʻrdingizmi?

Izohlar · 0