JavaScript Full-stackQatlamli arxitektura: controller → service → repository va uning chegaralari
JavaScript Full-stack · 36-qism. Arxitektura va system design

Qatlamli arxitektura: controller → service → repository va uning chegaralari

22 daqiqa11/44-dars

Qisqacha: Qatlamli arxitektura backend'ni vazifasiga ko'ra qatlamlarga bo'ladi: taqdimot (HTTP), ilova (biznes amallari), ma'lumot (saqlash). Asosiy qoida — bog'liqlik faqat pastga. Bu eng keng tarqalgan boshlang'ich arxitektura va vazifalar-api ning vazifalar moduli uning darslikdagi namunasi. Lekin o'lchov boshqa manzarani ko'rsatdi. 15 controller'dan 8 tasi SQL'ni o'zi yozadi yoki tranzaksiyani o'zi ochadi. Ulardan 6 tasida xizmat qatlami umuman yo'q. Login handler'i ikki faktorli kirish qarorini o'zi qabul qiladi. Vazifa modeli esa anemik. Har biri — narxi bor tanlov.

Bu darsda

  • To'rt qatlamni (taqdimot, ilova, domen, ma'lumot) va ularning mas'uliyatini aniqlaysiz.
  • Qat'iy va erkin qatlam qoidasini farqlaysiz va importlardan buzilishni topasiz.
  • Loyihadagi controller'larni o'lchab, qatlamlarni chetlab o'tishni sanaysiz.
  • "Semiz controller"ni taniysiz va qoidani xizmatga ko'chirasiz.
  • Anemik modelning qachon maqbul, qachon xavfli ekanini aytasiz.

Oldin bilishingiz kerak: Ma'lumotga kirish patternlari, Loyiha papka tuzilmasi, Controller'lar va route dekoratorlari, Repository naqshi va qatlamlar.

1. Nega bu kerak?

25-qismda Express'da birinchi marta marshrut.ts, xizmat.ts va ombor.ts ga bo'lingan kod yozgan edingiz (Repository naqshi va qatlamlar darsida uni Nest shaklida ko'rdik). O'shanda bu "toza kod" qoidasi edi. Endi savol arxitektura darajasida: qatlamlar butun loyihada qanchalik saqlangan, qayerda chetlab o'tilgan va bu chetlab o'tish qancha turadi?

Qatlamli arxitektura uch sababga ko'ra birinchi tanlov bo'ladi:

  • tushunish oson: yangi dasturchi "HTTP qayerda, qoida qayerda, SQL qayerda" savoliga darhol javob topadi;
  • almashtirish: ombor almashadi, xizmat va controller o'zgarmaydi. vazifalar-api da bu besh marta bo'lgan;
  • test: xizmatni xotira ombori bilan, controller'ni xizmat dublyori bilan sinash mumkin.

Lekin qatlamlarning narxi ham bor. Har amal uchta faylda, har qatlam chegarasida tur o'girish, oddiy CRUD uchun esa "faqat uzatuvchi" xizmat metodlari. Ma'lumotga kirish patternlari darsida SQL chaqiruvlarining atigi 35 foizi ombor klasslarida ekanini ko'rdik. Bu dars o'sha natijani controller tomondan ochadi.

Hayotiy o'xshatish: restoran. Ofitsiant (controller) buyurtmani oladi va oshpazga beradi. Oshpaz (xizmat) qaysi taom qanday tayyorlanishini biladi. Omborchi (repository) mahsulotni beradi. Ofitsiant omborga o'zi kirib go'sht olib chiqsa, tez bo'ladi. Lekin endi omborchi nima yetishmasligini bilmaydi, oshpaz esa retseptning bir qismi ofitsiantda ekanini bilmaydi.

2. To'rt qatlam va qoidalar

2.1 Qatlamlar

Klassik qatlamli arxitektura to'rt qatlamni ajratadi:

Qatlam Mas'uliyati vazifalar-api da
taqdimot (presentation) HTTP: yo'l, status, sarlavha, cookie, kirish tekshiruvi *.controller.ts, guard'lar, pipe'lar
ilova (application) biznes amallari, tranzaksiya chegarasi, hodisalar VazifalarService, auth/xizmat.ts
domen (domain) tushunchalar va qoidalar vazifa.ts (tur va teg qoidasi), royxat-mantiq.ts
ma'lumot (data) saqlash: SQL, fayl, kesh omborlar, umumiy/rls.ts

Kichik loyihalarda ilova va domen ko'pincha bitta qatlam bo'ladi. vazifalar-api da ham shunday: domen qoidalarining ko'pi xizmatda, bir qismi esa bazada (trigger'lar). Bu haqida — anemik model bo'limida.

2.2 Qat'iy va erkin qoida

Ikki xil qatlam qoidasi bor:

  • qat'iy (strict layering): har qatlam faqat o'zidan bitta pastdagi qatlamga murojaat qiladi. Controller → xizmat → ombor. Controller ombordan o'tib ketolmaydi.
  • erkin (relaxed layering): har qatlam o'zidan pastdagi istalgan qatlamga murojaat qila oladi. Controller to'g'ridan omborga yoki SQL'ga ham borishi mumkin.

Ikkalasida ham bitta qoida umumiy: yuqoriga yo'q. Ombor controller'ni import qilmaydi, xizmat Response obyektini bilmaydi. Qat'iy qoida almashtirish va testni osonlashtiradi. Erkin qoida esa oddiy amallar uchun ortiqcha qatlamlarni olib tashlaydi.

Ikki qoidani importlar ro'yxatida tekshiradigan kichik model yozamiz. Qatlam fayl nomidan aniqlanadi. Importlar vazifalar-api dagi haqiqiy juftliklardan olingan:

js
// qatlamlar: yuqoridan pastga
const QATLAM = { taqdimot: 0, ilova: 1, malumot: 2 };

function qatlam(fayl) {
  if (fayl.endsWith(".controller.ts")) return "taqdimot";
  if (/service|xizmat|markaz/.test(fayl)) return "ilova";
  return "malumot";
}

// importlar: kim → kimni (kanondagi haqiqiy juftliklar)
const importlar = [
  ["vazifalar.controller.ts", "vazifalar.service.ts"],
  ["vazifalar.service.ts", "ombor.ts"],
  ["webhook.controller.ts", "rls.ts"],
  ["fayl.controller.ts", "rls.ts"],
  ["auth.controller.ts", "xizmat.ts"],
  ["pg-ombor.ts", "outbox.ts"],
];

function tekshir(juftlar, qatiy) {
  const buzilish = [];
  for (const [a, b] of juftlar) {
    const farq = QATLAM[qatlam(b)] - QATLAM[qatlam(a)];
    if (farq < 0) buzilish.push(`${a} -> ${b}: yuqoriga`);
    else if (qatiy && farq > 1) {
      buzilish.push(`${a} -> ${b}: qatlam sakrab`);
    }
  }
  return buzilish;
}

for (const qatiy of [true, false]) {
  const b = tekshir(importlar, qatiy);
  const nom = qatiy ? "qat'iy" : "erkin";
  console.log(`${nom}: ${b.length} ta buzilish`);
  for (const x of b) console.log(`  ${x}`);
}

Konsolda:

text
qat'iy: 2 ta buzilish
  webhook.controller.ts -> rls.ts: qatlam sakrab
  fayl.controller.ts -> rls.ts: qatlam sakrab
erkin: 0 ta buzilish

Bir xil kod, ikki xil hukm. Qat'iy qoidada webhook va fayl controller'lari xizmat qatlamini sakrab o'tadi. Erkin qoidada esa ular to'g'ri: pastga qarab murojaat qilyapti, yuqoriga emas. Demak birinchi qaror — jamoa qaysi qoidani tanlaydi. Usiz "qatlam buzilgan" degan bahs ma'nosiz. QATLAM lug'ati raqam beradi va farq ishorasi yo'nalishni ko'rsatadi: manfiy — yuqoriga, 1 dan katta — sakrash. Model soddalashtirilgan: kanonda domen qatlami alohida emas va qatlam fayl nomidan taxminan aniqlanadi.

Kanon qaysi qoidani tanlagan? Hech qayerda yozilmagan. Kod esa ikkalasini ham aks ettiradi: vazifalar — qat'iy, 29-qism integratsiyalari — erkin. Bu keyingi bo'limdagi o'lchovning asosiy natijasi.

2.3 Tranzaksiya chegarasi qaysi qatlamda

Qatlamli arxitekturaning klassik javobi: tranzaksiya chegarasi — ilova qatlamida. Xizmat bitta biznes amalini bajaradi va u qaysi yozuvlar birga bo'lishini biladi. Ombor esa faqat "qanday yozish"ni biladi.

vazifalar-api da bu javob qisman bajariladi. Vazifalar modulida tranzaksiya ombor ichida ochiladi: har ombor metodi o'z #tranzaksiyada ini chaqiradi. Ma'lumotga kirish patternlari darsida buning natijasini ko'rdik: VazifalarService.yarat dagi soni va yarat ikki alohida tranzaksiyada va ular orasida poyga bor. Xizmat chegarani belgilay olmaydi, chunki ombor interfeysida "tranzaksiya" tushunchasi yo'q.

Integratsiya controller'larida esa teskari holat: egasiSifatida(pool, egasi, async (c) => …) controller metodida ochiladi va bir nechta SQL shu birlikka kiradi. Webhook obunasi yaratishda advisory lock, sanash va INSERT bitta tranzaksiyada — poyga yo'q. Ya'ni qatlam qoidasi buzilgan joyda tranzaksiya chegarasi to'g'ri, qoida saqlangan joyda esa noto'g'ri.

Bu paradoks emas, qatlamlarning haqiqiy narxi. Tranzaksiyani xizmatga olib chiqish uchun ombor interfeysi uni qabul qilishi kerak — masalan, Tranzaksiyalar NestJS'da darsidagi CLS bilan @Transactional(). Kanon bu yo'lni sinagan, lekin vazifalar-api ga kiritmagan. Bitta ombor metodi bitta amal bo'lgan holatlarda ichki tranzaksiya yetarli edi.

3. O'lchov: 15 controller

3.1 Natija

src/ dagi har *.controller.ts uchun sanadik: bo'sh bo'lmagan qatorlar, marshrutlar (@Get, @Post …; 405 uchun @All hisoblanmaydi), to'g'ridan SQL chaqiruvlari (.query(), tranzaksiya ochish (egasiSifatida() va xizmat klassiga bog'liqlik (Node 24.21.0, biz ishga tushirdik; skript mashq papkasida). Har qatorda ikki ustunga qarang: SQL va xizmat. "SQL bor, xizmat yo'q" — qatlam sakrab o'tilgan joy:

text
ai/ai.controller.ts: qator 152, marshrut 4, SQL 0, egasiSifatida 0, xizmat ha
auth/admin.controller.ts: qator 51, marshrut 3, SQL 2, egasiSifatida 0, xizmat ha
auth/auth.controller.ts: qator 320, marshrut 24, SQL 1, egasiSifatida 0, xizmat ha
auth/ichki.controller.ts: qator 36, marshrut 1, SQL 0, egasiSifatida 0, xizmat yo'q
auth/mfa.controller.ts: qator 161, marshrut 9, SQL 0, egasiSifatida 0, xizmat ha
bildirishnoma/bildirishnoma.controller.ts: qator 123, marshrut 6, SQL 7, egasiSifatida 4, xizmat yo'q
eksport/eksport.controller.ts: qator 37, marshrut 3, SQL 0, egasiSifatida 0, xizmat ha
email/obuna.controller.ts: qator 47, marshrut 2, SQL 1, egasiSifatida 0, xizmat yo'q
fayl/fayl.controller.ts: qator 182, marshrut 7, SQL 7, egasiSifatida 11, xizmat yo'q
navbat/navbat.controller.ts: qator 43, marshrut 1, SQL 1, egasiSifatida 1, xizmat yo'q
realtime/oqim.controller.ts: qator 21, marshrut 1, SQL 0, egasiSifatida 0, xizmat yo'q
telegram/telegram.controller.ts: qator 35, marshrut 3, SQL 2, egasiSifatida 2, xizmat yo'q
vazifalar/teglar.controller.ts: qator 24, marshrut 1, SQL 0, egasiSifatida 0, xizmat ha
vazifalar/vazifalar.controller.ts: qator 163, marshrut 9, SQL 0, egasiSifatida 0, xizmat ha
webhook/webhook.controller.ts: qator 84, marshrut 4, SQL 7, egasiSifatida 4, xizmat yo'q
controller'lar 15, marshrutlar 78
to'g'ridan SQL yoki tranzaksiya bor: 8 controller, 50 marshrut

Usul matnli: "xizmat" — konstruktorda …Service yoki …Xizmati turi yoki .xizmat maydoni. SQL soni — .query( qatorlari, haqiqiy so'rovlar emas.

3.2 Natijani halol o'qish

Oxirgi qatordagi "8 controller, 50 marshrut" raqami chalg'itadi. U auth.controller.ts ning 24 marshrutini ham qamraydi, holbuki u yerda bitta SQL bor. Controller'larni uch guruhga ajratish to'g'riroq:

Guruh Controller'lar Marshrutlar Belgisi
yupqa vazifalar, teglar, eksport, mfa, ai + ichki, oqim 28 SQL yo'q; oxirgi ikkitasi xizmatsiz, lekin bitta yo'lli va SQL'siz
xizmat bor, lekin SQL ham auth, admin 27 1–2 ta to'g'ridan so'rov
SQL'li, xizmatsiz fayl, bildirishnoma, webhook, telegram, navbat, obuna 23 SQL va tranzaksiya controller'da

Uchinchi guruhda 6 controller (obuna ni ham qo'shganda). Ular 29-qismda Express'da yozilgan va 30-qismda Nest'ga ko'chirilgan. webhook.controller.ts izohi buni aytadi: "SQL o'zgarmadi". Ko'chirish mexanik bo'lgan: Express handler'i Nest metodiga aylangan, qatlamlar esa qo'shilmagan. fayl.controller.ts da 11 ta tranzaksiya ochiladi. Bu loyihadagi eng "qalin" controller.

Bu xatomi? Erkin qoida nuqtai nazaridan — yo'q. SQL qisqa, RLS egasi bo'yicha himoya qiladi, ombor almashtirilmaydi. Qat'iy qoida nuqtai nazaridan — ha. Bu qoidalarni HTTP'siz testlab bo'lmaydi va boshqa kirish nuqtasidan (CLI, ishchi, AI agent vositasi) qayta ishlatib bo'lmaydi.

Narxning aniq o'lchovi bor. Hexagonal arxitektura darsida kanon webhook obunalarini qatlamlarga ajratib sinagan: fayllar soni 1 dan 5 ga, qatorlar 84 dan 129 ga ko'paygan. Domen testlari esa Postgres'siz, 6.50–7.69 soniya o'rniga 123–177 millisekundda o'tgan. Kanon buni loyihaga kiritmagan: bitta dasturchi va bitta baza uchun narx foydadan katta deb hisoblagan. Batafsil — o'sha darsda.

flowchart TB
  subgraph T[taqdimot]
    VC[vazifalar, teglar, eksport, mfa, ai]
    AC[auth, admin]
    SC[fayl, bildirishnoma, webhook, telegram, navbat, obuna]
  end
  subgraph I[ilova]
    VS[VazifalarService va boshqa xizmatlar]
    AX[auth xizmati]
  end
  subgraph M[ma'lumot]
    O[omborlar]
    R[egasiSifatida va pool]
  end
  VC --> VS --> O
  AC --> AX --> O
  AC -.->|1-2 SQL| R
  SC -.->|28 SQL, 22 tranzaksiya| R

Uzluksiz strelka — qat'iy qoida bo'yicha yo'l, uzuq strelka — qatlamni sakrab o'tish. Diagrammadagi raqamlar o'lchovdan: uchinchi guruh controller'larida 28 ta SQL chaqiruvi va 22 ta tranzaksiya. Bu .query( qatorlari va egasiSifatida( chaqiruvlari soni.

Tekshirib ko'ring: Ertaga AI agenti uchun "webhook obunasini yarat" vositasi kerak bo'ldi (MCP — AI agentiga ilova amallarini "vosita" sifatida beradigan protokol, MCP server yozish). Hozirgi webhook.controller.ts bilan nima qilasiz?

Javob

Obuna yaratish qoidalari — URL tekshiruvi (SSRF), 5 ta limit, advisory lock, sir yaratish — hammasi controller metodida. Ikki yo'l bor: vosita ichki HTTP so'rov yuborsin (qo'shimcha tarmoq qatlami va auth muammosi) yoki qoidalarni nusxalash (DRY buzilishi, bir xil poyga ikki joyda). To'g'ri yo'l — aynan shu paytda qoidalarni xizmatga (ObunaXizmati) chiqarish. Ikkinchi kirish nuqtasi paydo bo'lishi — qatlamni ajratishning eng kuchli dalili. Qat'iy qatlamlarni oldindan qurish shart emas, lekin bu kun kelganini tanish kerak.

3.3 Sakrashning xavfsizlik to'ri: RLS

Qatlamni sakrab o'tgan controller xavfli tuyuladi: egalik tekshiruvi kimda? Kanonda bu savolga ikki qavatli javob bor. Birinchi qavat — SQL'ning o'zi: webhook so'rovlarida har doim WHERE foydalanuvchi_id = $1 bor. Ikkinchi qavat — baza: egasiSifatida tranzaksiya boshida set_config('ilova.foydalanuvchi_id', …) ni qo'yadi va Row Level Security siyosati begona qatorlarni umuman ko'rsatmaydi (Row Level Security).

Ya'ni controller WHERE ni unutsa ham, baza begona obunani qaytarmaydi. Kanonning hexagonal tajribasida buning teskari tasdig'i bor. Port adapterida RLS sozlamasining nomi xato yozilgan (app.egasi, kanondagi ilova.foydalanuvchi_id o'rniga). RLS hamma qatorni yashirgan va 20 ta INSERT ning hammasi rad etilgan — "yopiq sukut" ishlagan.

Bu xavfsizlikda chuqur himoya (defense in depth) deb ataladi. Erkin qatlamli loyihada u ayniqsa muhim: qoidalar ko'p joyga tarqalganda, eng muhim kafolatni barcha yo'llar o'tadigan eng pastki qatlam — baza beradi. Lekin bu kafolat faqat egalik uchun. Limit, SSRF tekshiruvi va sir yaratish kabi biznes qoidalarini RLS himoya qilmaydi. Ular controller'da qoladi va boshqa kirish nuqtasida qayta yozilishi kerak.

3.4 Qatlamlar va test tezligi

Qatlamlarning eng sezilarli foydasi kundalik ishda — testda ko'rinadi. Ikki modulni solishtiraylik.

Vazifalar (qat'iy qatlamlar). VazifalarService ni xotira ombori bilan sinash mumkin: Postgres ham, HTTP ham kerak emas. Ombor xulqi esa alohida — shartnoma testi bilan har implementatsiyada. Controller testlari xizmatni tayyor holda oladi. Natijada qoida o'zgarsa, eng tez testlar birinchi qizaradi.

Webhook obunalari (qatlamsiz). Limit yoki SSRF qoidasini sinashning yagona yo'li — Nest ilovasi, haqiqiy Postgres va HTTP so'rov. Kanon o'lchovida webhook-api.test.ts ning uchta testi 6.50–7.69 soniya oladi. Xuddi shu qoidalar hexagonal tajribada xotira adapteri bilan 123–177 millisekundda sinalgan.

Bitta modul uchun 7 soniya katta emas. Lekin vazifalar-api ning to'liq Vitest to'plami 4.4.0 da 198 soniya oladi. Bunday vaqtning katta qismi aynan bazaga tayangan testlardan keladi. Qatlamsiz modullar ko'paygan sari to'plam sekinlashadi. Dasturchi esa testni kamroq yurgiza boshlaydi. Bu qatlamlarning sezilmaydigan, lekin haqiqiy narxi: tez fikr-mulohaza halqasi yo'qoladi.

Teskari tomoni ham bor. Bazaga tayangan test haqiqiy SQL, RLS va trigger'larni ham tekshiradi. Xotira adapteri esa ularni ko'rmaydi. Repository va SQL'ni testlash darsida pg-mem migratsiyalarning birortasini ham o'tkazmagan edi. Shuning uchun qatlamli loyihada ham baza testlari kerak — faqat ular kamroq va faqat ombor qatlamida.

4. Semiz controller

4.1 Belgilar

Semiz controller (fat controller) — biznes qarorlarini o'zi qabul qiladigan controller. Uning belgilari:

  • metodda HTTP'ga aloqasi yo'q if lar: "ikki faktor yoqilganmi", "parol to'g'rimi";
  • bitta metod bir nechta xizmat yoki ombordan ma'lumot yig'ib, natijani o'zi hal qiladi;
  • xuddi shu qoida boshqa kirish nuqtasida (CLI, ishchi) kerak bo'lsa, nusxalanadi.

Controller'ning to'g'ri ishi: kirishni o'qish va tekshirish, xizmatni chaqirish va natijani HTTP javobiga aylantirish. Qoida esa xizmatda bo'lishi kerak.

4.2 kirish handler'i

auth.controller.ts dagi login metodi (qatorlar qisqartirildi):

ts
async kirish(@Body(…) body: Kirish, @Req() req, @Res(…) res) {
  const f = await this.#xizmat.kirish(body, mijoz(req));
  await this.d.cheklagich.tozala(`kirish-hisob:${body.email}|…`);
  if (await this.d.mfa.ombor.yoqilganmi(f.id)) {
    this.d.mfa.kutish.qoy(res, { f: f.id, e: body.eslabQol });
    await this.#xizmat.hodisa({ tur: "kirish_mfa_kutilmoqda", … });
    return { mfa: "kerak" };
  }
  await this.auth.sessiyaBer(req, res, f, body.eslabQol);
  return { foydalanuvchi: f };
}

Parol tekshiruvi xizmatda (this.#xizmat.kirish). Lekin keyingi uch qaror controller'da: muvaffaqiyatdan keyin cheklov hisobini tozalash, ikki faktor kerakmi va jurnalga qaysi hodisa yozilishi. Ikki faktor qarori — xavfsizlik qoidasi. U kirish dan tashqari OTP orqali kirishda (otpKirish) va Telegram orqali kirishda ham kerak bo'lishi mumkin. Hozir esa u faqat parol bilan kirish handler'ida.

Bu kanonda topilgan farq bilan tasdiqlanadi. otpKirish, telegram va OIDC qaytish (oidcQaytish) metodlari ham sessiya beradi, lekin ularda mfa.ombor.yoqilganmi tekshiruvi yo'q. Xizmat (auth/xizmat.ts) ham ikki faktorni tekshirmaydi. Ya'ni ikki faktorli himoyani yoqgan foydalanuvchi SMS kodi, Telegram yoki Google orqali ikkinchi faktorsiz kiradi. Bu xavfsizlik nuqtai nazaridan ongli qaror bo'lishi mumkin: SMS kodi va Telegram o'zi "egalik" faktori. Fail-open va fail-closed qismidagi kabi qarorlar odatda izohda yoziladi. Bu yerda esa izoh topilmadi. Biz buni kodni o'qib aniqladik, jonli so'rov bilan sinamadik. Saboq arxitekturaviy: qoida controller'da bo'lsa, u har kirish yo'lida alohida yoziladi. Natijada qaysi yo'lda bor, qaysida yo'q ekanini faqat o'qib bilasiz.

Xizmatga ko'chirilgan variant natija turini qaytaradi: { tur: "mfa" } yoki { tur: "sessiya", f }. Controller esa faqat HTTP'ga o'giradi. 3-mashqda shu bo'linishni yozasiz.

4.3 Controller'dagi SQL: hisobni o'chirish

Ikkinchi misol — hisobniOchir. Unda parolni qayta tekshirish (parolTekshir), jurnalga yozish va baza funksiyasini chaqirish bor: this.d.pool.query("SELECT hisob_anonimlashtir($1)", …). Tuzilmaviy patternlar darsida buni "teshikli fasad" sifatida ko'rgan edik. Qatlam nuqtai nazaridan bu taqdimotdan ma'lumot qatlamiga sakrash. Amalning o'zi esa jiddiy: shaxsiy ma'lumotlarni qaytarib bo'lmaydigan anonimlashtirish (Ma'lumot saqlash muddati, arxivlash va anonimlashtirish).

Kanon nega shunday qilgan? Asosiy mantiq baza funksiyasida (sql/302). Controller faqat uni chaqiradi va funksiya vazifalar_auth roli bilan ishlaydi. Qoidaning o'zi bazada himoyalangan. Bu ham bitta qatlam tanlovi: "qoida bazada" (stored procedure) — ilova qatlamlaridan o'tmaydigan, lekin hamma kirish nuqtasi uchun bir xil himoya.

4.4 Controller'ni yupqalash tartibi

Semiz yoki SQL'li controller'ni xizmatga ajratish xavfli ish emas, lekin tartib muhim. Kanon tajribalaridan kelib chiqqan qadamlar:

  1. Avval xarakteristik test. Xarakteristik test (characterization test) — kod "qanday bo'lishi kerak"ni emas, hozir qanday ishlayotganini qotirib qo'yadigan test. Uning vazifasi — refaktoringdan keyin xulq o'zgarmaganini isbotlash. Hozirgi xulqni HTTP darajasida qotiring: statuslar, javob tanasi, limit va poyga holati (masalan, 20 parallel POST → 5 ta obuna). Dasturiy arxitektura nima darsidagi regressiya usuli: test eski kodda yashil bo'lishi kerak.
  2. Qoidani ko'chiring, SQL'ni emas. Birinchi qadamda xizmat SQL'ni egasiSifatida orqali o'zi chaqirsin. Ombor interfeysi keyinroq, faqat kerak bo'lsa.
  3. Natija turi. Xizmat HTTP xatosini emas, natija turini qaytarsin ({ tur: "limit" }). HTTP'ga controller aylantiradi.
  4. URL va javob shakli o'zgarmaydi. Mijozlar uchun bu refaktoring ko'rinmas bo'lishi kerak — buni 1-qadamdagi test tekshiradi.

Bu tartib bilan har qadam alohida commit va har biri testdan o'tadi. Butun modulni bir PR'da "qatlamlarga" ajratish esa katta diff va katta xavf.

5. Anemik model

5.1 Vazifa — faqat ma'lumot

vazifa.ts dagi Vazifa — faqat maydonlari bor tur: id, matn, bajarildi, teglar, yaratildi, yangilandi, tartib, versiya. Metodi yo'q. Qoidalar boshqa joylarda:

Qoida Qayerda
1000 tadan ko'p vazifa yo'q VazifalarService.yarat
matn 1–100 belgi Zod sxemasi va bazadagi CHECK
versiya har o'zgarishda +1 baza trigger'i
yangi vazifa ro'yxat oxiriga (tartib) baza trigger'i
teglar matndan teglariniOl (domen funksiyasi) va baza trigger'i

Martin Fowler bunday modelni anemik domen modeli (anemic domain model) deb ataydi va anti-naqsh deb biladi. Uning fikricha, obyekt o'z qoidalarini o'zi bilishi kerak: vazifa.bajar(), vazifa.matniniOzgartir(…).

5.2 Bu yerda nega maqbul

Lekin vazifalar-api ning anemik modeli ongli tanlov va uning uchta sababi bor:

  • Qoidalar kam va oddiy. Vazifada 2–3 holat bor (Xulq patternlari darsida State klasslari kerak emasligini ko'rdik). Har qoida bir qatorlik.
  • Kafolat bazada. Versiya va tartib trigger'lari har qanday yozuv yo'lida ishlaydi: API, psql va migratsiyada. Ilova obyektidagi qoida faqat ilova orqali yozilganda ishlaydi. Narxi ham bor: Postgres'siz omborlarda (xotira, fayl) trigger yo'q, shuning uchun XotiraOmbori versiya va tartib qoidasini JS'da qayta yozgan. Bitta qoida ikki joyda, ularning mosligini esa shartnoma testi tekshiradi (SOLID 2).
  • Besh ombor. Boy domen obyekti har omborda (xotira, fayl, Prisma) bir xil tiklanishi kerak bo'lardi. Oddiy tur esa structuredClone bilan nusxalanadi va JSON bo'lib keshga tushadi.

Anemik model qachon xavfli? Qoidalar ko'p va bir-biriga bog'liq bo'lganda. Masalan, to'lov: "qaytarish faqat 14 kun ichida", "qisman qaytarish summasi asl summadan oshmasin", "bekor qilingan to'lovni qaytarib bo'lmaydi". Bunday qoidalar xizmatlarga sochilsa, ulardan biri albatta qaysidir yo'lda unutiladi — ikki faktor tekshiruvi bilan bo'lgani kabi. Bunday domenlar uchun boy model, aggregate va invariantlar kerak. Bu DDD taktik darsining mavzusi.

Tekshirib ko'ring: Mahsulot jamoasi yangi qoida so'radi: "bajarilgan vazifaning matnini o'zgartirib bo'lmaydi". Uni qayerga yozasiz — xizmatga, bazaga yoki Vazifa obyektiga?

Javob

Uchala variantning narxi har xil. Xizmatda (VazifalarService.yangila) — eng tez, lekin almashtirHammasi va toplamYarat yo'llarida ham alohida tekshirish kerak, aks holda qoida chetlab o'tiladi. Bazada (trigger yoki CHECK bilan) — hamma yo'lda ishlaydi, lekin xotira va fayl omborlarida JS'da takrorlanadi, xato matni esa bazadan keladi. Obyektda (vazifa.matniniOzgartir()) — modelni boyitish boshlanadi. Bitta qoida uchun bu ortiqcha, beshinchi qoidada esa o'zini oqlaydi. Kanonning hozirgi uslubiga eng mosi — bazada cheklov va shartnoma testiga bitta yangi test, shunda besh omborning hammasi qoidani bajarishga majbur bo'ladi.

6. Loyihangizda tekshiring

Kod bu darsda o'zgarmaydi: kanon tajribasida o'lchov qilindi, qarorlar yozildi. O'z nusxangizda:

  1. Qoidani tanlang va yozing. docs/ARXITEKTURA.md ga bitta qator: "qatlamlar — erkin; controller ombor yoki egasiSifatida ni chaqirishi mumkin, agar amal bitta jadvalda va boshqa kirish nuqtasi yo'q bo'lsa". Yoki qat'iy qoida. Muhimi — yozilgan bo'lsin.
  2. Lint bilan majburlang. Coupling, cohesion va modul chegaralari darsida umumiy/ uchun ESLint qoidasi yozgan edik. Xuddi shu usul bilan, masalan, src/vazifalar/*.controller.ts uchun pg va umumiy/rls.ts importini taqiqlang. Shunda vazifalar moduli qat'iy qoladi.
  3. Ikki faktor yo'llari. Sessiya beradigan har yo'lni (kirish, otpKirish, telegram, OIDC qaytishi, passkey) ro'yxat qiling. Har biri uchun "ikki faktor tekshiriladimi, tekshirilmasa — nega?" savoliga javob yozing.

7. Ko'p uchraydigan xatolar

7.1 Qoidani tanlamasdan bahslashish

"Bu controller qatlamni buzyapti" — qaysi qoida bo'yicha? Qat'iy va erkin qoida bir xil kodga turli hukm beradi.

7.2 Faqat uzatuvchi xizmatlar

royxat(s) { return this.ombor.royxat(s); } kabi metodlar qat'iy qoidaning narxi. VazifalarService da ham ular bor (royxat, teglar). Ko'p bo'lsa, erkin qoida arzonroq.

7.3 Xavfsizlik qarorini controller'da

Ikki faktor, ruxsat, limit — har kirish yo'lida takrorlanadi va bittasi unutiladi. Xizmatda yoki guard'da bitta joyda.

7.4 Mexanik ko'chirish

Express'dan Nest'ga (yoki boshqa freymvorkka) o'tishda fayl shakli o'zgaradi, qatlamlar esa qo'shilmaydi. Ko'chirish — qatlamlarni qayta ko'rish uchun yaxshi payt.

7.5 Anemik modelni avtomatik xato deb bilish

Kam qoidali CRUD uchun anemik model va baza cheklovlari sodda va ishonchli. Boy model qoidalar ko'payganda kerak.

8. Mashqlar

Mashqlar kurs/mashqlar/36/11-qatlamli/ da. 2- va 3-mashq yechimlari Node 24.21.0 da tekshirilgan (biz ishga tushirdik). Controller o'lchovi skripti ham shu papkada.

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

  • Har qatlam faqat bitta pastdagi qatlamga murojaat qiladigan qoida — qoida
  • Biznes qarorlarini o'zi qabul qiladigan controller — controller
  • Faqat maydonlari bor, qoidalarsiz domen obyekti — model
  • fayl.controller.ts da ochiladigan tranzaksiyalar soni —
  • Vazifa versiyasini +1 qiladigan joy — baza 'i
Yechim
  • qat'iy — strict layering; erkin qoidada pastdagi istalgan qatlam.
  • semiz — fat controller: kirish dagi ikki faktor qarori.
  • anemik — Vazifa turi; qoidalar xizmat va bazada.
  • 11 — egasiSifatida( chaqiruvlari.
  • trigger — har yozuv yo'lida ishlaydi.

2-mashq (o'rta): controller'larni guruhlash

O'lchov natijasidan yettita controller berilgan: marshrutlar, SQL chaqiruvlari va tranzaksiyalar soni. Har controller uchun "SQL zichligi"ni hisoblang: (SQL + tranzaksiya) / marshrut. 0 bo'lsa — yupqa, 1 dan kichik — aralash, aks holda — SQL'li. Controller'larni guruhlab chiqaring.

Ishora: Map.groupBy(royxat, fn) — massivni funksiya qaytargan kalit bo'yicha guruhlaydi (Loyiha papka tuzilmasi darsidagi kabi). at(-1) — oxirgi element.

Yechim
js
// o'lchov natijasi: controller → [marshrutlar, SQL, egasiSifatida]
const olchov = {
  "auth/auth.controller.ts": [24, 1, 0],
  "auth/mfa.controller.ts": [9, 0, 0],
  "vazifalar/vazifalar.controller.ts": [9, 0, 0],
  "fayl/fayl.controller.ts": [7, 7, 11],
  "bildirishnoma/bildirishnoma.controller.ts": [6, 7, 4],
  "webhook/webhook.controller.ts": [4, 7, 4],
  "auth/admin.controller.ts": [3, 2, 0],
};

function turi([marshrut, sql, tranz]) {
  const zichlik = (sql + tranz) / marshrut;
  if (zichlik === 0) return "yupqa";
  if (zichlik < 1) return "aralash";
  return "SQL'li";
}

const guruh = Map.groupBy(Object.entries(olchov), ([, m]) => turi(m));
for (const [t, royxat] of guruh) {
  const nomlar = royxat.map(([f]) => f.split("/").at(-1));
  console.log(`${t} (${royxat.length}): ${nomlar.join(", ")}`);
}

Konsolda:

text
aralash (2): auth.controller.ts, admin.controller.ts
yupqa (2): mfa.controller.ts, vazifalar.controller.ts
SQL'li (3): fayl.controller.ts, bildirishnoma.controller.ts, webhook.controller.ts

Guruhlar tartibi — Map ga birinchi kirgan kalit tartibida: birinchi yozuv auth.controller.ts (aralash) bo'lgani uchun aralash birinchi. Zichlik — qo'pol ko'rsatkich. auth.controller.ts da 24 marshrutga bitta SQL — 0.04, lekin u loyihadagi eng katta controller va unda semiz metodlar bor. Raqam qayerga qarashni aytadi, xulosani esa kodni o'qib chiqarasiz.

3-mashq (qiyin): semiz controller'ni yupqalash

Login qoidasini xizmatga ko'chiring. kirishXizmati({ tekshirParol, mfaYoqilgan }) funksiya qaytarsin. U body ni oladi va natija turini qaytaradi: xato, mfa yoki sessiya. HTTP haqida hech narsa bilmaydi. kirishController(xizmat) esa natijani [status, javob] ga aylantiradi. Uch holatni sinab ko'ring.

Ishora: natija turi — diskriminatsiyalangan birlashma (Discriminated union va to'liqlik tekshiruvi): tur maydoni bo'yicha shoxlash. Bog'liqliklarni parametr bilan berish — funksional DI (DI va IoC konteyner).

Yechim
js
// xizmat: login qoidasi — HTTP'ni bilmaydi, natija turini qaytaradi
function kirishXizmati({ tekshirParol, mfaYoqilgan }) {
  return (body) => {
    const f = tekshirParol(body.email, body.parol);
    if (f === undefined) return { tur: "xato" };
    if (mfaYoqilgan(f.id)) return { tur: "mfa", id: f.id };
    return { tur: "sessiya", f };
  };
}

// controller: natija turi → HTTP javob (yupqa)
function kirishController(xizmat) {
  return (body) => {
    const n = xizmat(body);
    if (n.tur === "xato") return [401, "Email yoki parol noto'g'ri"];
    if (n.tur === "mfa") return [200, { mfa: "kerak" }];
    return [200, { foydalanuvchi: n.f.email }];
  };
}

const hisoblar = new Map([
  { id: 1, email: "ali@example.uz", parol: "a1" },
  { id: 2, email: "vali@example.uz", parol: "v2" },
].map((h) => [h.email, h]));
const xizmat = kirishXizmati({
  tekshirParol: (e, p) => {
    const h = hisoblar.get(e);
    return h?.parol === p ? h : undefined;
  },
  mfaYoqilgan: (id) => id === 2,
});
const ctrl = kirishController(xizmat);

for (const body of [
  { email: "ali@example.uz", parol: "a1" },
  { email: "vali@example.uz", parol: "v2" },
  { email: "ali@example.uz", parol: "xato" },
]) {
  const [holat, javob] = ctrl(body);
  console.log(holat, JSON.stringify(javob));
}

Konsolda:

text
200 {"foydalanuvchi":"ali@example.uz"}
200 {"mfa":"kerak"}
401 "Email yoki parol noto'g'ri"

Endi ikki faktor qarori bitta funksiyada. OTP yoki Telegram bilan kirish uchun yangi xizmat ham xuddi shu mfaYoqilgan ni chaqiradi yoki uni ataylab chaqirmaydi — bu farq bitta joyda ko'rinadi. Xizmatni HTTP'siz testlash mumkin: kirishXizmati(...)({ … }) to'g'ridan natija turini qaytaradi. Model soddalashtirilgan: parol oddiy satr bilan solishtirildi, haqiqiy kodda argon2 va vaqt bo'yicha bir xil javob kerak (Parolni xavfsiz saqlash).

9. Real ishda

  • Ko'p jamoalar qatlamli arxitekturadan boshlaydi va bu to'g'ri. Muammo uni tanlashda emas, qoidani yozmaslikda: bir necha oydan keyin loyihada uch xil uslub bo'ladi.
  • Freymvork shabloni (nest g resource) controller, service va DTO'ni avtomatik yaratadi. Bu qat'iy qatlamlarni sukut qiladi. Kerak bo'lmasa, oddiy amal uchun xizmat yozmaslik ham qaror (Nest CLI va loyiha tuzilmasi).
  • Arxitektura testlari. dependency-cruiser yoki ESLint no-restricted-imports bilan qatlam qoidasi CI'da tekshiriladi. Qoida yozilmasa, birinchi shoshilinch tuzatish uni buzadi.
  • Keyingi qadam — hexagonal va clean arxitektura. Ular qatlamlarni "ichki-tashqi" ko'rinishga aylantiradi: domen markazda, baza va HTTP esa tashqi adapter (Hexagonal arxitektura).
  • Intervyu savollari: "Controller'da biznes mantiq bo'lsa nima bo'ladi?", "Anemik model — anti-naqshmi?", "Strict va relaxed layering farqi?". Kuchli javob o'z loyihangizdagi raqam bilan: nechta controller qatlamni sakrab o'tadi va nega.

Xulosa

  • To'rt qatlam: taqdimot, ilova, domen, ma'lumot. Umumiy qoida — yuqoriga yo'q. Qat'iy qoida bitta pastga, erkin qoida esa istalgan pastga ruxsat beradi.
  • Bir xil kod ikki qoidada ikki hukm oladi: webhook va fayl controller'lari qat'iy qoidada sakraydi, erkin qoidada esa to'g'ri.
  • O'lchov: 15 controller, 78 marshrut. 7 tasi yupqa, 2 tasi aralash, 6 tasi SQL'li va xizmatsiz. Uchinchi guruh 29-qismda yozilib, 30-qismda mexanik ko'chirilgan.
  • Semiz controller: kirish ikki faktor qarorini o'zi qabul qiladi, otpKirish va telegram da esa bu tekshiruv yo'q va izohda sababi yozilmagan.
  • Anemik Vazifa ongli tanlov: qoidalar kam, kafolat bazada, besh ombor. Qoidalar ko'p domenda boy model kerak.
  • Keyingi qadam — qoidani yozish va lint bilan majburlash.

Keyingi dars: Hexagonal arxitektura (Ports and Adapters) — webhook obunalarini port va adapterlarga ajratamiz: +4 fayl va +54 % qator evaziga domen testlari Postgres'siz, millisekundlarda o'tadi.

Manbalar

  • Martin Fowler — Patterns of Enterprise Application Architecture (2002), 1-bob: Layering; Service Layer
  • Martin Fowler — AnemicDomainModel: https://martinfowler.com/bliki/AnemicDomainModel.html (2003; tekshirildi, 2026-11 — Fowler uni "anti-pattern" deb ataydi)
  • Frank Buschmann va boshq. — Pattern-Oriented Software Architecture, Vol. 1 (1996) — Layers naqshi, strict va relaxed layering
  • Mark Richards — Software Architecture Patterns (O'Reilly, 2015), 1-bob: Layered Architecture
  • Kurs tajribasi (IlmHamroh, 2026-11): vazifalar-api 4.4.0 — 15 controller o'lchovi (marshrutlar, SQL, egasiSifatida), auth.controller.ts dagi kirish, otpKirish, telegram, hisobniOchir metodlari, vazifa.ts; hexagonal tajriba raqamlari — kanon natijalari. Skript va mashq yechimlari — biz ishga tushirdik (Node 24.21.0, 2026-11-09).
36-qism. Arxitektura va system design · 11-dars yakunlandi

Qatlamli arxitektura: controller → service → repository va uning chegaralari

22 daqvaqt
0belgi
Keyingi dars: Hexagonal arxitektura (Ports and Adapters): webhook obunalarini yadroga ajratish va narxini o'lchash
Telegram'da
Darsda xato koʻrdingizmi?

Izohlar · 0