JavaScript Full-stackArxitektura qarorlari: ADR va C4 diagrammalar bilan jamoa dizaynini yozish
JavaScript Full-stack · 36-qism. Arxitektura va system design

Arxitektura qarorlari: ADR va C4 diagrammalar bilan jamoa dizaynini yozish

24 daqiqa32/44-dars

Qisqacha: ADR — bitta muhim qaror haqida qisqa yozuv: kontekst, qaror, muqobillar, oqibatlar. C4 — tizimni to'rt darajada chizish usuli: kontekst, konteynerlar, komponentlar, kod. Ikkalasi birga ishlaydi: diagramma "nima qayerda", ADR "nega aynan shunday" degan savolga javob beradi. Bu darsda jamoa capstone'i uchun yozilgan yettita ADR va uch darajali C4'ni o'qiymiz, keyin o'zingiznikini shu shablon bilan yozasiz.

Bu darsda

  • ADR qachon kerak va qachon ortiqcha ekanini ajratasiz.
  • Yaxshi ADR'ning to'rt belgisini bilasiz: raqamli kontekst, haqiqiy muqobillar, narx va qayta ko'rish sharti.
  • ADR holatlari va "almashtirildi" zanjirini tushuntirasiz, ularni skript bilan tekshirasiz.
  • C4 modelining kontekst, konteyner va komponent darajalarini Mermaid'da chizasiz.
  • jamoa uchun o'z docs/ papkangizni boshlaysiz: ADR'lar va C4.

Oldin bilishingiz kerak: Jamoada muloqot: sinxron va asinxron (ADR shabloni), Jamoadagi yangi loyihaga kirish (arxitektura xaritasi), Dasturiy arxitektura va trade-off, API gateway, BFF va service mesh.

1. Nega bu kerak?

Oldingi o'ttiz bitta darsda vazifalar-api ustida o'lchadik: kesh, yuk taqsimlagich (load balancer), replika, saga, ID turlari. Har o'lchovdan bitta xulosa chiqdi. Masalan, "bitta nusxa soniyasiga 393 so'rov beradi" yoki "uuidv4 bilan INSERT bigint'dan ikki barobar sekin".

Endi 38-qismda yangi loyiha boshlanadi — jamoa. Bu jamoalar uchun pullik vazifalar xizmati: bir nechta jamoa, rollar, taklif, obuna. Kodi hali yo'q. Lekin bir qancha qarorlar allaqachon kerak. Bitta server yoki ko'p? Har jamoaga alohida baza yoki umumiy? Sessiya yoki JWT?

Bu qarorlar xulosalari bilan birga yozilmasa, uch narsa bo'ladi. Birinchidan, olti oydan keyin o'zingiz "nega shunday qilgan edim?" deb so'raysiz. Ikkinchidan, yangi jamoadosh har qarorni qayta bahsga qo'yadi. Uchinchidan, sharoit o'zgarganda qaysi qarorni qayta ko'rish kerakligini hech kim bilmaydi.

Hayotiy o'xshatish: uy qurilishining loyiha papkasi. Unda ikki xil hujjat bor. Chizmalar — qaysi xona qayerda, quvur qayerdan o'tadi. Tushuntirish xati — nega poydevor chuqurroq (yer osti suvi yaqin), nega tom tekis emas (qor ko'p). Chizma — C4, tushuntirish xati — ADR. Biri ikkinchisisiz chala.

2. ADR: qarorning yozuvi

2.1 Eslatma

ADR shablonini Jamoada muloqot darsida ko'rgansiz: sarlavha (fe'l bilan), holat, sana, qatnashchilar, keyin to'rt bo'lim — Kontekst, Qaror, Ko'rib chiqilgan muqobillar, Oqibatlar. vazifalar-api da birinchi ADR — LLM modellari uchun alohida circuit breaker. U yerda ADR muloqot vositasi edi: qaror chatda yo'qolmasin.

Bu darsda ADR'ga arxitektor ko'zi bilan qaraymiz. Savol endi "qanday yoziladi" emas, "qachon yoziladi va qanday qilib foydali bo'ladi".

2.2 Qachon ADR yoziladi

Trade-off tafakkuri darsidagi sinovni eslang: qarorni bir yildan keyin o'zgartirsak, nechta fayl, jadval va foydalanuvchiga ta'sir qiladi? ADR — aynan shu sinovdan "qimmat" bo'lib chiqqan qarorlar uchun.

Qaror ADR kerakmi Nega
bitta server yoki ko'p ha deploy, zaxira, SLO o'zgaradi
jamoalar ma'lumotini ajratish usuli ha har jadval, har so'rov
ID turi ha URL, API, indekslar
funksiya nomi, papka ichidagi fayl yo'q bitta PR bilan o'zgaradi
kutubxonaning minor versiyasi yo'q CHANGELOG yetadi

Yana bitta belgi: muqobil haqiqatan bormi? Agar boshqa variantni hech kim jiddiy taklif qilmasa, ADR yozish shart emas. ADR — tanlov bo'lgan joyda tanlovning izi.

2.3 jamoa ning yetti qarori

Kanon tajribasida (IlmHamroh, 2026-11) jamoa uchun yettita ADR yozildi. Har biri shu qismdagi bitta o'lchovga tayanadi:

ADR Qaror Asosiy dalil
0001 bitta VPS, modular monolit 1 nusxa — 393 so'rov/s; yuk ~3 so'rov/s
0002 umumiy baza, jamoa_id + RLS IDOR sinovida RLS ikkinchi qatlam bo'ldi
0003 server sessiyasi, JWT emas darhol chiqish va bloklash kerak
0004 to'lov: webhook — haqiqat manbai imzosiz webhook buyurtmani "to'landi" qildi
0005 outbox + BullMQ, Kafka emas Streams'da 38 xabar tasdiqlanmay qoldi
0006 ichida bigint, tashqarida UUIDv7 INSERT 2.6 / 3.9 / 5.5 s
0007 kesh faqat o'lchov bilan kesh readiness'ni aldagan edi

Dalillar ustuniga qarang: birorta ham "yaxshi amaliyot shunday" yo'q. Har birida raqam yoki haqiqiy voqea. Raqamlarning manbasi: Load balancing, IDOR, To'lov xavfsizligi, Servislararo aloqa, Vaqt, tartib va ID, Trade-off tafakkuri (readiness) va Kesh qatlamlari darslari.

2.4 Bitta ADR'ni yaqindan o'qiymiz

ADR-0001 dan bo'laklar. Telefon uchun qatorlar bo'lindi; kanon matnidagi dars raqamlari dars nomi bilan almashtirildi. O'qiyotganda uch joyga qarang: Kontekstdagi raqamlar, "Narxi" qatori va "Qayta ko'rish sharti".

text
# 0001. jamoa ni bitta VPS'da modular monolit
#       sifatida chiqaramiz

- Holat: qabul qilingan
- Sana: 2026-11-09

## Kontekst
Jamoa — 1 dasturchi. Kutilgan yuk: 1-yil oxirida
~200 faol jamoa, ~2 000 foydalanuvchi, cho'qqida
~3 so'rov/s (o'rtacha 0.3). vazifalar-api bitta
jarayonda bir nusxada yuzlab so'rov/s beradi
(Load balancing darsidagi o'lchov).

## Oqibatlar
- Yaxshi: bitta tranzaksiya (to'lov + obuna holati),
  oddiy debugging, arzon.
- Narxi: bitta server — yagona nosozlik nuqtasi.
- Qayta ko'rish sharti: cho'qqi > 200 so'rov/s yoki
  billing modulining deploy chastotasi qolganlardan
  keskin farq qilsa — modul chegarasi bo'yicha ajratish.

Bu ADR'da yaxshi ADR'ning to'rt belgisi bor.

  1. Kontekstda raqam. "Yuk kichik" emas, "cho'qqida ~3 so'rov/s". Raqam bo'lsa, qaror tekshiriladigan bo'ladi.
  2. Haqiqiy muqobillar. Jadvalda mikroservislar, Kubernetes va PaaS bor — har birining afzalligi ham yozilgan. Faqat kamchilik yozilgan muqobil — "somon odam" (strawman): uni yiqitish uchun qo'yilgan.
  3. Narx ochiq. "Yagona nosozlik nuqtasi" — qarorning eng og'riqli tomoni, yashirilmagan.
  4. Qayta ko'rish sharti. "200 so'rov/s dan oshsa" — qachon bu ADR eskiradi. Bu shart bo'lmasa, qaror abadiy qoida bo'lib qoladi.

To'rtinchisi eng kam uchraydi va eng foydalisi. Evolyutsion arxitektura darsida bunday shartlarni avtomatik tekshiriladigan qilamiz.

Tekshirib ko'ring: ADR-0001 kontekstidagi "~3 so'rov/s" raqami qayerdan olingan?

Javob

Halol javob: kanon hujjatida bu raqamning formulasi yo'q. ADR "hisob-kitob" faylini havola qiladi, lekin u faylda jamoa bo'limi yo'q. Bu — hujjatdagi bo'shliq. Taxminiy hisob-kitob darsida bu raqamni faraz va formula bilan qayta tiklaymiz va tekshiramiz. Qoida: ADR'dagi har raqamning manbasi bo'lsin — o'lchov fayli yoki formula.

2.5 Holat va hayot sikli

ADR'ning to'rt holati bor:

stateDiagram-v2
  [*] --> taklif
  taklif --> qabul: PR merge
  taklif --> bekor: rad etildi
  qabul --> almashtirilgan: yangi ADR
  almashtirilgan --> [*]
  bekor --> [*]

Diagrammada qabul — "qabul qilingan", bekor — "bekor qilingan". Asosiy qoida: qabul qilingan ADR o'zgartirilmaydi. Qaror o'zgarsa — yangi ADR yoziladi, eskisining holati "0009 bilan almashtirilgan" bo'ladi. Shunda tarix saqlanadi: kim, qachon va nima uchun fikrini o'zgartirgani ko'rinadi.

Mayda tuzatish (imlo, buzilgan havola) — mumkin. Qarorning mazmunini o'zgartirish — yo'q.

jamoa da ikkita ADR hali "taklif": 0006 (ID) va 0007 (kesh). Nega? Ikkalasi ham kod yozilmasdan oldin tasdiqlanishi shart emas. ID turi birinchi migratsiyada, kesh esa birinchi o'lchovda hal bo'ladi. "Taklif" holati — "yo'nalish shu, lekin oxirgi so'z hali aytilmagan" degani.

2.6 ADR ro'yxatini skript bilan tekshirish

ADR'lar ko'paygach, ikki xato paydo bo'ladi: holat noto'g'ri yoziladi ("qabul" va "qabul qilingan" aralashadi) va "almashtirilgan" ADR yo'q raqamga ishora qiladi. Ikkalasini kichik skript ushlaydi. Chiqishda ikki qatorga qarang: bugungi ro'yxat va bir yildan keyingi faraziy ro'yxat.

js
const HOLATLAR = ["taklif", "qabul qilingan", "bekor qilingan",
  "almashtirilgan"];

const adrlar = [
  { n: 1, nom: "bitta VPS, monolit", holat: "qabul qilingan" },
  { n: 2, nom: "multi-tenant: RLS", holat: "qabul qilingan" },
  { n: 3, nom: "sessiya cookie, JWT emas", holat: "qabul qilingan" },
  { n: 4, nom: "to'lov: webhook manba", holat: "qabul qilingan" },
  { n: 5, nom: "outbox + BullMQ", holat: "qabul qilingan" },
  { n: 6, nom: "bigint + UUIDv7", holat: "taklif" },
  { n: 7, nom: "kesh faqat o'lchov bilan", holat: "taklif" },
];

function tekshir(royxat) {
  const xatolar = [];
  const bor = new Set(royxat.map((a) => a.n));
  for (const a of royxat) {
    if (!HOLATLAR.includes(a.holat)) {
      xatolar.push(`${a.n}: noma'lum holat "${a.holat}"`);
    }
    if (a.holat === "almashtirilgan" && !bor.has(a.ornida)) {
      xatolar.push(`${a.n}: o'rnini bosgan ADR yo'q`);
    }
  }
  return xatolar;
}

console.log("bugun:", tekshir(adrlar));

// faraz: bir yildan keyin ID qarori qayta ko'rildi
const keyin = adrlar.map((a) => a.n === 6
  ? { ...a, holat: "almashtirilgan", ornida: 9 } : a);
keyin.push({ n: 8, nom: "Redis kesh", holat: "qabul" });
console.log("keyin:", tekshir(keyin));

Konsolda:

text
bugun: []
keyin: [ "6: o'rnini bosgan ADR yo'q", `8: noma'lum holat "qabul"` ]

Bugungi yettita ADR toza. Ikkinchi qism — faraz: 0006 "0009 bilan almashtirilgan" deb belgilandi, lekin 0009 hali yozilmagan; 0008 da esa holat qisqartirib yozilgan. Ikkalasi ham ushlandi.

Node massivni ko'rsatganda satr ichida ' bo'lsa, uni backtick bilan o'raydi — shuning uchun ikkinchi xato boshqacha qo'shtirnoqda. Haqiqiy loyihada bu skript ADR fayllarining birinchi qatorlarini o'qiydi va CI'da ishlaydi. Bu docs-as-code g'oyasi: hujjat ham kod kabi tekshiriladi.

2.7 ADR qayerda yashaydi

  • docs/adr/NNNN-qisqa-nom.md — kod bilan bitta repoda. Kod o'zgarsa, ADR shu PR'da yangilanadi.
  • Raqam ketma-ket va qayta ishlatilmaydi. Bekor qilingan 0004 ham o'z raqamini saqlaydi.
  • 0000-shablon.md — nusxa olish uchun.
  • Kod izohidan ADR'ga havola: // ADR-0005: hodisa outbox orqali. Kodni o'qigan odam "nega" ni topadi.

Wiki yoki Confluence'dagi ADR ham ishlaydi. Lekin kod bilan birga review qilinmaydi va tez eskiradi. Shuning uchun kursda — repoda.

Tekshirib ko'ring: Jamoadosh ADR-0003 (sessiya cookie) ni ochib, "Qaror" bo'limiga "mobil ilova uchun JWT ham" deb qo'shib qo'ydi. Nima noto'g'ri?

Javob

Qabul qilingan ADR'ning mazmuni o'zgartirildi. Endi tarix yo'qoldi: qaror qachon va nega kengaygani ko'rinmaydi. To'g'ri yo'l — yangi ADR (masalan, "0008. Mobil ilova uchun token"), u 0003 ga havola qiladi. Agar yangi qaror eskisini to'liq bekor qilsa, 0003 holati "0008 bilan almashtirilgan" bo'ladi. Qisman kengaytirsa — 0003 o'z kuchida, 0008 unga qo'shimcha.

2.8 ADR review: beshta savol

ADR "taklif" holatida PR bilan keladi. Review qiluvchi kod emas, fikrni tekshiradi. Beshta savol yetarli:

  1. Kontekstdagi raqamning manbasi bormi? O'lchov fayli, formula yoki voqea havolasi.
  2. Muqobillar adolatlimi? Har birida kamida bitta haqiqiy afzallik yozilganmi?
  3. Narx kimga tushadi? Dasturchiga, foydalanuvchiga yoki serverga — aniq aytilganmi?
  4. Qachon qayta ko'riladi? Raqamli yoki aniq hodisali shart bormi?
  5. Qaytarish qanchaga tushadi? Bir haftalikmi yoki bir yillikmi — qaror qanchalik "qimmat"?

Beshinchi savol qaror tezligini belgilaydi. Qaytarish arzon bo'lsa, uzoq muhokama shart emas: tanlang, o'lchang, kerak bo'lsa almashtiring. Qaytarish qimmat bo'lsa (RLS yoki ID turi kabi), bir hafta muhokama ham arzon.

2.9 Natijani halol o'qish: raqam to'g'ri ko'chirilganmi

Birinchi savol kanon tajribasida haqiqiy xatoni ushladi. ADR-0006 ning birinchi qoralamasini ko'ring. Unda: "Hamma joyda UUIDv7 — indeks bigint'dan ~40 % katta". Vaqt, tartib va ID darsidagi o'lchovda PK indeksi bigint uchun 11 MB, uuidv7 uchun 15 MB edi. Hisoblaymiz: 15 / 11 ≈ 1.36, ya'ni ~36 % katta.

"40 %" — yaxlitlangan, lekin bir tomonga: rad etilgan variantni biroz yomonroq ko'rsatadi. Bu holda xulosa o'zgarmaydi — farq baribir sezilarli. Lekin odat xavfli: muqobillar jadvalidagi raqamlar har gal "bizning tanlov foydasiga" yaxlitlansa, ADR targ'ibot hujjatiga aylanadi. Review'dan keyin ADR'da shunday yozildi: "36 % katta (o'lchov: 15 MB va 11 MB)". Qoida: raqamni o'lchovdagidek yozing, foizni yoniga qo'ying — o'quvchi o'zi tekshira olsin.

E'tibor bering: bu tuzatish "taklif" holatidagi ADR'da qilindi. Qabul qilinmagan ADR'ni tahrirlash mumkin — u hali muhokama ostida.

Shu ADR'da yana bir yaxshi tafsilot bor: "UUIDv7 dagi vaqt — tartib uchun EMAS". O'lchovda soati bir soat orqada qolgan tugun yaratgan id tartibda birinchi bo'lib qolgan edi. ADR bu topilmani qoidaga aylantirgan: biznes vaqti alohida ustunda. Mana shunday — o'lchov, keyin qaror, keyin qoida.

2.10 Chala ADR'ni beshta savoldan o'tkazamiz

Beshta savolni bitta to'liq misolda ko'ramiz. Jamoadosh Jasur shunday qoralama ochdi:

text
# 0009. Redis kesh qo'shamiz

- Holat: taklif

## Kontekst
Sayt sekin ishlayapti.

## Qaror
Vazifalar ro'yxatini Redis'da keshlaymiz.

## Oqibatlar
Sayt tezlashadi.

Har savolni ketma-ket beramiz:

Savol Qoralamada Nima kerak
raqam manbasi "sekin" — raqam yo'q p95 qancha, qaysi endpoint, qaysi o'lchov
muqobillar bo'lim umuman yo'q indeks, so'rovni tuzatish, HTTP kesh
narx yozilmagan eskirgan ma'lumot, invalidatsiya kodi
qayta ko'rish yo'q "p95 50 ms dan past bo'lsa — keshni olib tashlash"

Beshinchi savol — "qaytarish qanchaga tushadi?" Kesh qo'shish va olib tashlash arzon, shuning uchun bu ADR'da uzoq muhokama shart emas. Lekin bitta narsa majburiy: o'lchov. Trade-off tafakkuri darsida kesh readiness tekshiruvini aldagan edi: baza o'chiq, /health/ready esa 200. Shuning uchun jamoa ning ADR-0007 si aynan "kesh faqat o'lchov bilan" deydi.

Nima bo'ldi? Qoralama "nima qilamiz" ni aytdi, lekin "nega", "nimaning o'rniga" va "qanchaga" ni aytmadi. Review'dan keyin uchala savolga javob bor — endi bu e'lon emas, tekshiriladigan qaror.

3. C4: tizimni to'rt darajada chizish

3.1 Nega oddiy "quti va strelka" yetmaydi

Jamoadagi yangi loyihaga kirish darsida vazifalar-api ning birinchi diagrammasini chizgansiz. Bunday diagrammaning muammosi — hamma narsa bitta rasmda: foydalanuvchi, nginx, controller, jadval, Redis kaliti. Bunday rasmni mijoz ham, yangi dasturchi ham tushunmaydi.

C4 modeli — Simon Brown taklif qilgan usul: tizimni xaritadagidek kattalashtirib chizish. Har darajada boshqa auditoriya va boshqa savol:

Daraja Savol Kim uchun
1. Kontekst tizim kim bilan gaplashadi hamma, biznes ham
2. Konteyner qaysi ilovalar va bazalar dasturchi, DevOps
3. Komponent konteyner ichida qaysi modullar shu konteyner dasturchisi
4. Kod klasslar, funksiyalar odatda chizilmaydi

C4'dagi konteyner — alohida ishga tushadigan yoki ma'lumot saqlaydigan birlik: SPA, API jarayoni, baza, navbat. U Docker konteyneri bilan bir xil narsa emas, garchi ko'pincha mos kelsa ham. Masalan, Postgres — bitta C4 konteyneri, lekin uni Docker'siz ham o'rnatish mumkin.

To'rtinchi daraja amalda chizilmaydi: kodning o'zi uning eng aniq rasmi. jamoa hujjatida ham uchta daraja bor.

Asosiy diagrammalardan tashqari, C4 yordamchi diagrammalarni ham taklif qiladi: tizimlar landshafti, dinamik (ketma-ketlik) va deployment diagrammalari. Ketma-ketlikni siz Mermaid sequenceDiagram bilan ko'p chizgansiz.

3.2 1-daraja: tizim konteksti

Kanon 01-c4.md dagi birinchi diagramma (aynan):

flowchart LR
  egasi["Jamoa egasi<br/>(to'laydi, a'zo taklif qiladi)"]
  azo["Jamoa a'zosi<br/>(vazifa bilan ishlaydi)"]
  admin["Platforma admini<br/>(qo'llab-quvvatlash)"]
  jamoa(["jamoa<br/>jamoalar uchun vazifalar SaaS"])
  tolov["To'lov provayderi<br/>(Payme / Click / Stripe)"]
  pochta["SMTP provayderi<br/>(taklif, tasdiq xatlari)"]
  tg["Telegram Bot API<br/>(eslatmalar)"]
  google["Google OIDC<br/>(kirish)"]
  egasi -->|"obuna, a'zolar, sozlamalar (HTTPS)"| jamoa
  azo -->|"vazifalar, izohlar (HTTPS, SSE)"| jamoa
  admin -->|"bloklash, yordam (HTTPS, 2FA)"| jamoa
  jamoa -->|"to'lov sahifasi, webhook (imzoli)"| tolov
  tolov -->|"to'lov hodisasi (webhook)"| jamoa
  jamoa -->|"xat (SMTP, STARTTLS)"| pochta
  jamoa -->|"xabar (HTTPS)"| tg
  jamoa -->|"OIDC (PKCE)"| google

Markazdagi yumaloq quti — bizning tizim, bitta quti. Ichida nima borligi bu darajada muhim emas. Chapda — odamlar (rollar), o'ngda — tashqi tizimlar. Har strelkada ikki narsa yozilgan: nima o'tadi va qanday (protokol).

Bu diagrammadan nimalarni o'qish mumkin:

  • Uchta rol bor. Admin 2FA bilan kiradi — demak, admin uchun alohida xavfsizlik talabi bor.
  • To'lov provayderi bilan ikki tomonlama aloqa: biz sahifaga yo'naltiramiz, u webhook yuboradi. Bu ADR-0004 ning sababi.
  • To'rtta tashqi tizim — to'rtta "tashqi nosozlik nuqtasi". Har biri o'chsa nima bo'lishini runbook aytishi kerak.

3.3 2-daraja: konteynerlar

Endi jamoa qutisini ochamiz:

flowchart TB
  subgraph mijoz["Brauzer / telefon"]
    web["web — React 19 SPA (Vite)<br/>statik fayllar"]
  end
  subgraph vps["VPS (Docker Compose, bitta server — ADR-0001)"]
    nginx["nginx — TLS, CSP, rate limit,<br/>statik web, /v1 → api"]
    api["api — NestJS 12 (Node 24)<br/>REST /v1, SSE; stateless, 2 nusxa"]
    ishchi["ishchi — BullMQ consumer<br/>outbox relay, xat, webhook, billing"]
    db[("Postgres 18<br/>tenant_id + RLS (ADR-0002)")]
    redis[("Redis 8<br/>sessiya keshi, cheklagich, BullMQ")]
    s3[("S3-mos ombor<br/>fayl ilovalari")]
  end
  web -->|"HTTPS"| nginx
  nginx -->|"HTTP 127.0.0.1"| api
  api -->|"SQL (vazifalar_api roli, RLS)"| db
  api -->|"RESP"| redis
  api -->|"presigned URL"| s3
  ishchi -->|"SQL (outbox, BYPASSRLS yo'q — tenant bo'yicha)"| db
  ishchi -->|"navbat"| redis
  ishchi -->|"SMTP / HTTPS"| tashqi["tashqi: SMTP, Telegram, to'lov provayderi"]
  tashqi -->|"webhook"| nginx

Strelkalardagi qisqa nomlar oldingi qismlardan tanish. Eslatma uchun: SSE — serverdan brauzerga uzluksiz xabar oqimi; RESP — Redis'ning o'z protokoli; presigned URL — fayl omboriga vaqtinchalik ruxsatli havola, fayl API orqali o'tmaydi; BYPASSRLS — Postgres rolining RLS'ni chetlab o'tish huquqi.

Diagrammani yuqoridan pastga o'qing. Brauzer faqat nginx bilan gaplashadi. nginx ichkariga 127.0.0.1 orqali uzatadi — API tashqariga ochiq emas. API va ishchi — bitta koddan ikki jarayon (33-qismdagi ishchi.ts kabi). Ma'lumot uchta joyda: Postgres, Redis, fayl ombori.

Ikki narsaga e'tibor bering:

  1. Diagrammada ADR raqamlari bor. "bitta server — ADR-0001", "RLS (ADR-0002)". Diagramma "nima", ADR "nega" — ular bir-biriga havola qiladi.
  2. Strelkada xavfsizlik tafsiloti bor: "BYPASSRLS yo'q", "vazifalar_api roli". Konteyner darajasida qaysi rol bilan ulanish — arxitektura qarori, chunki IDOR darsida ko'rganingizdek, superuser bilan ulangan ilova RLS'ni chetlab o'tadi.

Bitta kamchilik ham bor: diagrammada "2 nusxa" yozilgan, lekin ikki nusxa orasidagi balanslash ko'rinmaydi. Bu ataylab: nusxalar soni deployment diagrammasining ishi.

Tekshirib ko'ring: Nega diagrammada tashqi qutisidan nginx'ga strelka bor, API'ga emas?

Javob

To'lov provayderining webhook'i ham oddiy HTTPS so'rov: u internetdan keladi va avval nginx'ga tushadi (TLS, tezlik cheklovi). API to'g'ridan-to'g'ri ochiq emas. Agar diagrammada strelka API'ga chizilsa, o'quvchi "API internetga ochiq" deb o'ylaydi — bu noto'g'ri va xavfli taxmin.

3.4 3-daraja: api ning komponentlari

Uchinchi daraja faqat api konteyneri uchun chizilgan:

flowchart LR
  subgraph api["api (modular monolit — ADR-0001)"]
    auth["auth<br/>sessiya, OIDC, 2FA"]
    tenant["jamoalar<br/>tenant, a'zolik, rollar, taklif"]
    vazifa["vazifalar<br/>vazifa, izoh, teg, fayl"]
    billing["billing<br/>tarif, obuna, limitlar, invoice"]
    bildir["bildirishnomalar<br/>email, telegram, SSE"]
    umumiy["umumiy (shared kernel)<br/>xatolar, tekshir, log, RLS yordamchisi"]
  end
  vazifa -->|"tenant konteksti (CLS)"| tenant
  vazifa -->|"limit so'rovi (port)"| billing
  billing -->|"hodisa: obuna.ozgardi (outbox)"| bildir
  tenant -->|"hodisa: azo.taklif_qilindi"| bildir
  auth --> umumiy
  tenant --> umumiy
  vazifa --> umumiy
  billing --> umumiy

Bu daraja Coupling va cohesion darsining natijasini rasmga aylantiradi. umumiy — hamma unga bog'liq, u hech kimga bog'liq emas. Modullar bir-biriga faqat port yoki hodisa orqali murojaat qiladi. Chegara qoidasi kanon hujjatida yozilgan: modul boshqa modulning ichki fayllarini import qilmaydi — faqat index.ts yoki hodisa. Bu qoida ESLint bilan majburlanadi, xuddi vazifalar-api dagi umumiy qoidasi kabi.

O'lchovdan kelgan sabab: vazifalar-api da 22 ta modul jufti ikki tomonlama bog'liq edi. jamoa da bu boshidan yopiladi — keyin tozalash qimmatroq.

Strelka turlariga qarang. Uzluksiz strelka bilan "tenant konteksti" va "limit so'rovi" — sinxron chaqiruv. "hodisa: …" — asinxron, outbox orqali (Event-driven arxitektura). Bitta diagrammada ikki xil aloqa — strelka yozuvi ularni farqlaydi.

3.5 Biz shunday xato qildik: diagramma noto'g'ri ADR'ga ishora qilgan

Kanon 01-c4.md ning birinchi versiyasida bu diagrammaning subgraph sarlavhasi api (modular monolit — ADR-0003) edi. ADR-0003 esa sessiya cookie haqida. Modular monolit — ADR-0001. Xato review'da topildi va hujjatda tuzatildi; yuqoridagi diagramma — tuzatilgan versiya.

Kichik xato, lekin ibratli. Diagramma va ADR alohida fayllarda yashaydi, ular orasidagi havola hech narsa bilan tekshirilmaydi. ADR'lar qayta raqamlansa yoki yangisi qo'shilsa, bunday havolalar jim eskiradi. Ikkita chora bor:

  • havolada raqam bilan birga qisqa nom: ADR-0001 (modular monolit) — xato ko'zga tashlanadi;
  • skript: diagrammadagi har ADR-NNNN uchun fayl borligini va uning sarlavhasida kalit so'z borligini tekshirish. Design doc, runbook va postmortem darsida shunday havola tekshiruvchisini yozamiz.

3.6 Diagramma kod sifatida

Kanon diagrammalari Mermaid'da — matn fayli. Afzalliklari:

  • Git diff'da ko'rinadi: "nginx → api strelkasiga 127.0.0.1 qo'shildi".
  • PR'da review qilinadi, xuddi kod kabi.
  • Kurs sayti ham, GitHub ham uni rasmga aylantiradi.

Kamchiligi: joylashuvni boshqarish qiyin. Mermaid tugunlarni o'zi joylashtiradi, katta diagramma chalkash chiqadi. Shuning uchun har darajada 12 tadan kam quti — bu ham telefon uchun, ham tushunish uchun yaxshi chegara.

Mermaid'da C4 uchun maxsus sintaksis ham bor (C4Context, C4Container). Kanon oddiy flowchart ni tanladi: u hamma joyda bir xil chiziladi va o'quvchi uni allaqachon biladi. Boshqa vositalar — Structurizr DSL (Simon Brown'ning o'z vositasi) va PlantUML — bitta modeldan bir nechta diagramma chiqaradi. Katta tizimda bu foydali; jamoa uchun ortiqcha.

4. ADR va C4 birga: o'qish tartibi

Yangi odam jamoa/docs/ ni qanday o'qiydi:

flowchart LR
  R[README] --> RFC[RFC-0001]
  RFC --> K[C4: kontekst]
  K --> C[C4: konteyner]
  C --> A[ADR'lar]
  C --> M[C4: komponent]
  M --> D[DDD lug'ati]

Avval RFC — "nima qilyapmiz va nega". Keyin C4 kattalashtirib boradi. Har qutida ADR raqami — "bu yerda qaror bor, o'qing". Komponent darajasidan keyin umumiy til lug'ati (DDD strategik darsida yozilgan 02-ddd.md).

Kanon jamoa-dizayn/README.md aynan shu tartibni jadval bilan beradi. Fayllar: RFC-0001-jamoa-mvp.md, 01-c4.md, 02-ddd.md, adr/0001–0007, runbook.md. RFC va runbook — keyingi darsda.

4.1 Uch hujjat — uch vazifa

Boshida bu hujjatlar bir-biriga o'xshab ko'rinadi. Farqi — vaqt va hajmda:

Hujjat Nimani aytadi Qachon o'zgaradi
ADR bitta qaror va uning sababi hech qachon (yangisi yoziladi)
C4 diagramma tizim hozir qanday tuzilgan har tuzilma o'zgarishida
RFC (design doc) katta ish rejasi, ko'p qaror birga muhokama tugaguncha
ARXITEKTURA.md yangi odam uchun xarita vaqti-vaqti bilan

ADR — tarix: u o'tmishdagi qarorni o'sha kungi bilim bilan saqlaydi. C4 esa — bugungi holat, u doim yangilanib turadi. Shuning uchun diagrammada eski qutini "tarix uchun" qoldirmang: tarix ADR'larda.

vazifalar-api da to'rttalasining namunasi bor: docs/adr/0001-har-modelga-alohida-breaker.md, docs/ARXITEKTURA.md (Mermaid diagrammalari bilan), docs/talablar/takrorlanuvchi-vazifalar.md (talab hujjati). jamoa ning RFC'si — yangi tur, uni keyingi darsda o'qiymiz.

4.2 Diagramma qachon yangilanadi

Oddiy qoida: PR yangi konteyner, yangi tashqi tizim yoki modullar orasida yangi aloqa qo'shsa — C4 shu PR'da yangilanadi. Review qiluvchi buni so'raydi: "Redis'ga yangi navbat qo'shildi — konteyner diagrammasida bormi?".

Komponent darajasi tezroq eskiradi, chunki modullar tez-tez o'zgaradi. Shuning uchun uni faqat eng muhim konteyner (api) uchun chizing. Kontekst darajasi esa yillar davomida deyarli o'zgarmaydi — uni bir marta yaxshilab chizish yetadi.

5. Loyiha qadami: jamoa/docs/

38-qismda jamoa yangi repo bo'ladi. Hujjatni hozir boshlang — kod yo'q paytda qaror arzon.

  1. Repo ildizida docs/adr/ papka va 0000-shablon.md (Jamoada muloqot darsidagi shablon).
  2. Yettita ADR. Kanondagilarni ko'chirmang — o'z qarorlaringizni yozing. Masalan, siz Stripe'siz faqat Payme'ni tanlashingiz mumkin; unda ADR-0004 boshqacha bo'ladi. Har kontekstda kamida bitta raqam (shu qism darslaridan), har muqobilda afzallik ham.
  3. docs/01-c4.md — uch daraja. Har strelkada nima va qanday; har qarorli qutida ADR raqami va qisqa nomi.
  4. «ADR ro'yxatini skript bilan tekshirish» bo'limidagi tekshiruvni scripts/adr-tekshir.mjs qiling: u docs/adr/*.md dan raqam va holatni o'qisin.

Commit xabari, masalan: docs(adr): jamoa uchun 0001–0007 va C4 diagrammalar.

6. Ko'p uchraydigan xatolar

6.1 Har narsaga ADR

Kutubxona patch versiyasi, papka nomi — ADR emas. ADR'lar ko'payib ketsa, muhimlari ularning orasida yo'qoladi va hech kim o'qimaydi.

6.2 Qaror qabul qilingandan keyin yozish

"Kodni yozdik, endi ADR yozib qo'yamiz" — muqobillar jadvali sun'iy chiqadi. ADR qarordan oldin, "taklif" holatida yoziladi va PR'da muhokama qilinadi.

6.3 Raqamsiz kontekst

"Yuk katta bo'lishi mumkin" — tekshirib bo'lmaydi. "Cho'qqida ~3 so'rov/s, formulasi …" — tekshiriladi va qayta ko'rish shartiga aylanadi.

6.4 Qabul qilingan ADR'ni tahrirlash

Qaror o'zgarsa — yangi ADR va "almashtirilgan" holati. Eskisini o'chirish yoki qayta yozish tarixni yo'q qiladi.

6.5 Bitta diagrammada hamma daraja

Foydalanuvchi, jadval va Redis kaliti bitta rasmda — hech kimga foydasiz. Har auditoriyaga o'z darajasi.

6.6 Yozuvsiz strelka

A --> B — nima o'tadi? Sinxronmi? Qaysi protokol? Kanondagi komponent diagrammasida ham to'rtta shunday strelka bor — ular umumiy ga. Bu yerda ma'nosi aniq ("import qiladi"), lekin qoida sifatida yozuvsiz strelkani qoldirmang. 3-mashqda ularni skript bilan topasiz.

6.7 Texnologiyasiz konteyner

"Backend", "Database" deb yozilgan qutilar hech narsa aytmaydi. Konteyner darajasida texnologiya va versiya muhim: "Postgres 18", "NestJS 12 (Node 24)", "Redis 8". Kanon diagrammasidagi har qutida shunday. Versiya o'zgarsa (masalan, Postgres 19 ga ko'chish), bu ham diagrammada ko'rinadi va ehtimol yangi ADR talab qiladi.

6.8 Diagrammada sirli qisqartmalar

"BFF", "GW", "SVC-2" — siz bilasiz, yangi odam bilmaydi. Qisqartma kerak bo'lsa, diagramma ostida izohlar ro'yxati (legend) bering. C4 muallifi ham har diagrammaga kalit (legend) qo'yishni tavsiya qiladi: qaysi shakl odam, qaysi biri baza, uzluksiz va uzuq chiziq nimani anglatadi.

7. Mashqlar

Mashqlar kurs/mashqlar/36/32-adr-c4/ da. 2- va 3-mashq yechimlari Node 24.21.0 da tekshirilgan (biz ishga tushirdik).

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

  • Qabul qilingan ADR o'zgarsa, yangi ADR yoziladi, eskisining holati —
  • C4'ning tizim kim bilan gaplashishini ko'rsatadigan birinchi darajasi —
  • jamoa da ikki holati hali "taklif" bo'lgan ADR'lardan biri — ID yoki
  • ADR-0001 qaysi cho'qqi yukda qayta ko'riladi (so'rov/s) —
  • Odatda chizilmaydigan C4 darajasi —
Yechim
  • almashtirilgan — "NNNN bilan almashtirilgan" deb, yangi raqam bilan.
  • kontekst — tizim bitta quti, atrofida odamlar va tashqi tizimlar.
  • kesh — ADR-0007; ikkinchisi ADR-0006 (ID).
  • 200 — undan oshsa, modul chegarasi bo'yicha ajratish ko'riladi.
  • kod — kodning o'zi eng aniq rasm.

2-mashq (o'rta): ADR bo'limlarini tekshirish

tekshirADR(md) funksiyasini yozing. U ADR matnini olib uch narsani qaytarsin: sarlavha # NNNN. (to'rt raqam, nuqta, bo'shliq) bilan boshlanadimi, **Sana:** qatori bormi va to'rt majburiy bo'limdan qaysilari yo'q. Quyidagi qoralamada sinang (u ataylab chala).

Ishora: ^## (.+)$ naqshi gm bayroqlari bilan har ## sarlavhani topadi, matchAll hammasini qaytaradi (Regex amaliyotda).

text
# 0008. Fayllarni S3-mos omborda saqlaymiz

- **Holat:** taklif

## Kontekst
Fayl ilovalari 50 MB gacha, jamoa 200 ta.

## Qaror
Presigned URL bilan to'g'ridan-to'g'ri yuklash.

## Oqibatlar
Server fayl trafigini ko'rmaydi.
Yechim
js
const KERAK = ["Kontekst", "Qaror", "Ko'rib chiqilgan muqobillar",
  "Oqibatlar"];

const qoralama = `# 0008. Fayllarni S3-mos omborda saqlaymiz

- **Holat:** taklif

## Kontekst
Fayl ilovalari 50 MB gacha, jamoa 200 ta.

## Qaror
Presigned URL bilan to'g'ridan-to'g'ri yuklash.

## Oqibatlar
Server fayl trafigini ko'rmaydi.`;

function tekshirADR(md) {
  const bolimlar = [...md.matchAll(/^## (.+)$/gm)].map((m) => m[1]);
  const yoq = KERAK.filter((b) => !bolimlar.includes(b));
  const sarlavha = /^# (\d{4})\. /.test(md);
  const sana = /\*\*Sana:\*\*/.test(md);
  return { yoq, sarlavha, sana };
}

const n = tekshirADR(qoralama);
console.log(`raqamli sarlavha: ${n.sarlavha}, sana: ${n.sana}`);
console.log(`yo'q bo'limlar: ${n.yoq.join(", ") || "-"}`);

Konsolda:

text
raqamli sarlavha: true, sana: false
yo'q bo'limlar: Ko'rib chiqilgan muqobillar

Qoralamada ikki kamchilik bor: sana yo'q va muqobillar jadvali yo'q. Ikkinchisi muhimroq: muqobilsiz ADR — qaror emas, e'lon. m bayrog'isiz ^ faqat butun matn boshini bildiradi va bitta ham bo'lim topilmasdi.

3-mashq (qiyin): yozuvsiz strelkalar

Mermaid flowchart matnidan strelkalarni ajratib oling. A -->|"yozuv"| B va A --> B shakllarini tushuning. Ikki natija chiqaring: yozuvsiz strelkalar ro'yxati va eng ko'p kiruvchi strelkasi bor tugun. Kanon komponent diagrammasidagi sakkizta strelkada sinang.

Ishora: bitta regex ikki shaklni ham ushlay oladi — yozuv qismini (?:…)? bilan ixtiyoriy qiling. Hisoblash uchun Map, tartiblash uchun toSorted (Nusxa bilan o'zgartirish).

Yechim
js
const diagramma = `
  vazifa -->|"tenant konteksti (CLS)"| tenant
  vazifa -->|"limit so'rovi (port)"| billing
  billing -->|"hodisa: obuna.ozgardi (outbox)"| bildir
  tenant -->|"hodisa: azo.taklif_qilindi"| bildir
  auth --> umumiy
  tenant --> umumiy
  vazifa --> umumiy
  billing --> umumiy`;

const QIRRA = /^\s*(\w+)\s*-->(?:\|"([^"]*)"\|)?\s*(\w+)\s*$/;

function tahlil(matn) {
  const yozuvsiz = [];
  const kiruvchi = new Map();
  for (const qator of matn.split("\n")) {
    const m = qator.match(QIRRA);
    if (!m) continue;
    const [, dan, yozuv, ga] = m;
    if (!yozuv) yozuvsiz.push(`${dan} -> ${ga}`);
    kiruvchi.set(ga, (kiruvchi.get(ga) ?? 0) + 1);
  }
  return { yozuvsiz, kiruvchi };
}

const { yozuvsiz, kiruvchi } = tahlil(diagramma);
console.log(`yozuvsiz strelkalar: ${yozuvsiz.length}`);
console.log(yozuvsiz.join(", "));
const top = [...kiruvchi].toSorted((a, b) => b[1] - a[1])[0];
console.log(`eng ko'p kiruvchi: ${top[0]} (${top[1]})`);

Konsolda:

text
yozuvsiz strelkalar: 4
auth -> umumiy, tenant -> umumiy, vazifa -> umumiy, billing -> umumiy
eng ko'p kiruvchi: umumiy (4)

To'rtta yozuvsiz strelkaning hammasi umumiy ga — va umumiy eng ko'p kiruvchi tugun. Bu Coupling va cohesion darsidagi Ca (kiruvchi bog'liqlik) ning diagrammadagi ko'rinishi: ko'p modul bog'liq bo'lgan joy barqaror bo'lishi kerak. Tavsiya: bu strelkalarga ham yozuv qo'shing, masalan "import (xatolar, log)". Regex faqat oddiy nomli tugunlarni tushunadi — A["…"] --> B kabi qatorlarni o'tkazib yuboradi; haqiqiy vosita uchun Mermaid'ning o'z tahlilchisi kerak.

8. Real ishda

  • Ochiq loyihalar. Ko'p ochiq loyihalarda docs/adr/ yoki docs/decisions/ papkasi bor. ADR shablonlari va vositalari to'plami — adr.github.io.
  • Thoughtworks Technology Radar "lightweight ADR" amaliyotini 2017–2018 yillarda "Adopt" (qo'llang) halqasiga qo'ygan. Hozirgi nashrda bu yozuv ko'rsatilmaydi, lekin oxirgi bahosi — "Adopt" (2018-yil may).
  • Arxitektura review. Katta kompaniyalarda yangi servis ADR va C4 konteyner diagrammasisiz review'dan o'tmaydi.
  • Intervyu. System design intervyusida birinchi chiziladigan narsa — aslida C4 konteyner diagrammasi: mijoz, yuk taqsimlagich, servislar, baza, kesh. Buni System design metodi darsida qilamiz.

Xulosa

  • ADR — qimmat va muqobili bor qaror uchun; mayda tanlovlar uchun emas.
  • Yaxshi ADR: kontekstda raqam, haqiqiy muqobillar, ochiq narx va qayta ko'rish sharti.
  • Qabul qilingan ADR o'zgartirilmaydi — yangisi yoziladi, eskisi "almashtirilgan".
  • C4 — to'rt daraja: kontekst, konteyner, komponent, kod; har biri o'z auditoriyasi uchun.
  • Diagramma va ADR bir-biriga havola qiladi; havolani skript tekshirmasa, u eskiradi (C4 ning birinchi versiyasidagi ADR-0003 xatosi).

Keyingi dars: Design doc (RFC), runbook va postmortem yozish — jamoa ning RFC'sini bo'lim-bo'lim o'qiymiz va hujjatlar orasidagi havolalarni skript bilan tekshiramiz.

Manbalar

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

Arxitektura qarorlari: ADR va C4 diagrammalar bilan jamoa dizaynini yozish

24 daqvaqt
0belgi
Keyingi dars: Design doc (RFC), runbook va postmortem: jamoa hujjatlarini yozish va tekshirish
Telegram'da
Darsda xato koʻrdingizmi?

Izohlar · 0