Qatlamli arxitektura: controller → service → repository va uning chegaralari
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-apining 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-apida 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:
// 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:
qat'iy: 2 ta buzilish
webhook.controller.ts -> rls.ts: qatlam sakrab
fayl.controller.ts -> rls.ts: qatlam sakrab
erkin: 0 ta buzilishBir 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:
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 marshrutUsul 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| RUzluksiz 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.tsbilan 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
iflar: "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):
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:
- 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. - Qoidani ko'chiring, SQL'ni emas. Birinchi qadamda xizmat SQL'ni
egasiSifatidaorqali o'zi chaqirsin. Ombor interfeysi keyinroq, faqat kerak bo'lsa. - Natija turi. Xizmat HTTP xatosini emas, natija turini qaytarsin (
{ tur: "limit" }). HTTP'ga controller aylantiradi. - 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,
psqlva migratsiyada. Ilova obyektidagi qoida faqat ilova orqali yozilganda ishlaydi. Narxi ham bor: Postgres'siz omborlarda (xotira, fayl) trigger yo'q, shuning uchunXotiraOmboriversiya 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
structuredClonebilan 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
Vazifaobyektiga?
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:
- Qoidani tanlang va yozing.
docs/ARXITEKTURA.mdga bitta qator: "qatlamlar — erkin; controller ombor yokiegasiSifatidani chaqirishi mumkin, agar amal bitta jadvalda va boshqa kirish nuqtasi yo'q bo'lsa". Yoki qat'iy qoida. Muhimi — yozilgan bo'lsin. - Lint bilan majburlang. Coupling, cohesion va modul chegaralari darsida
umumiy/uchun ESLint qoidasi yozgan edik. Xuddi shu usul bilan, masalan,src/vazifalar/*.controller.tsuchunpgvaumumiy/rls.tsimportini taqiqlang. Shunda vazifalar moduli qat'iy qoladi. - 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.tsda ochiladigan tranzaksiyalar soni —- Vazifa versiyasini +1 qiladigan joy — baza 'i
Yechim
- qat'iy — strict layering; erkin qoidada pastdagi istalgan qatlam.
- semiz — fat controller:
kirishdagi ikki faktor qarori. - anemik —
Vazifaturi; 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
// 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:
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.tsGuruhlar 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
// 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:
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-cruiseryoki ESLintno-restricted-importsbilan 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:
kirishikki faktor qarorini o'zi qabul qiladi,otpKirishvatelegramda esa bu tekshiruv yo'q va izohda sababi yozilmagan. - Anemik
Vazifaongli 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-api4.4.0 — 15 controller o'lchovi (marshrutlar, SQL,egasiSifatida),auth.controller.tsdagikirish,otpKirish,telegram,hisobniOchirmetodlari,vazifa.ts; hexagonal tajriba raqamlari — kanon natijalari. Skript va mashq yechimlari — biz ishga tushirdik (Node 24.21.0, 2026-11-09).
Izohlar · 0
Izoh yozish uchun kiring.