JavaScript Full-stackHexagonal arxitektura (Ports and Adapters): webhook obunalarini yadroga ajratish va narxini o'lchash
JavaScript Full-stack · 36-qism. Arxitektura va system design

Hexagonal arxitektura (Ports and Adapters): webhook obunalarini yadroga ajratish va narxini o'lchash

25 daqiqa12/44-dars

Qisqacha: Hexagonal arxitektura (Ports and Adapters) — biznes qoidalari markazda yashaydi va tashqi dunyoni faqat port (interfeys) orqali ko'radi. Baza, HTTP va freymvork — almashtiriladigan adapterlar. Bu darsda vazifalar-api dagi webhook obunalarini shu ko'rinishga keltiramiz: domen, port, use case va ikkita adapter. Natija o'lchandi: domen testlari bazasiz ~50 marta tezroq, lekin kod 54 % ko'paydi. Shuning uchun bu o'zgarish loyihaga kirmadi — sababini raqam bilan ko'ramiz.

Bu darsda

  • Port, adapter, driving (kiruvchi) va driven (chiquvchi) tomonni loyihadagi aniq fayllar bilan farqlaysiz.
  • Bitta controller ichidagi aralash mas'uliyatlarni domen, use case va adapterlarga ajratasiz.
  • Xotira adapteri bilan bazasiz test yozasiz va uning tezligini haqiqiy o'lchov bilan solishtirasiz.
  • Adapter xatosi domen testida ko'rinmasligini va shartnoma testi nega kerakligini tushuntirasiz.
  • Hexagonal arxitektura qachon o'zini oqlashini va qachon ortiqcha ekanini raqam bilan asoslaysiz.

Oldin bilishingiz kerak: Qatlamli arxitektura: controller → service → repository, Modular monolit va hexagonal arxitektura NestJS'da, Repository naqshi va qatlamlar, Biznes mantiq zaifliklari.

1. Nega bu kerak?

Modular monolit va hexagonal arxitektura NestJS'da darsida hexagonal ko'z bilan loyihani o'qigan edik. U yerda VazifaOmbori — port, beshta ombor — adapter, va bu tuzilma 26–30-qismlarda o'zini ko'rsatgan: saqlash xotiradan Postgres'ga, Express'dan Nest'ga ko'chdi, domen esa o'zgarmadi.

Lekin loyihada hexagonal bo'lmagan joylar ham bor. Eng yorqini — webhook obunalari. webhook.controller.ts bitta faylda hamma narsani qiladi: HTTP so'rovini o'qiydi, Zod bilan tekshiradi, URL'ni SSRF'ga qarshi tekshiradi, sir yaratadi, tranzaksiya ochadi, qulf oladi, limitni sanaydi va SQL yozadi. Hammasi 84 qatorda.

Bu yomonmi? Testlar o'tadi, xato yo'q. Savol boshqacha: "5 tadan ko'p obuna bo'lmaydi" degan qoidani tekshirish uchun nima kerak? Hozir — Nest ilovasi, Postgres va HTTP so'rov. Qoida esa bitta if.

Bu darsda kanon tajribasi shu controllerni hexagonal ko'rinishga keltirdi va uch narsani o'lchadi: fayllar soni, test tezligi, poyga holati. Natijada o'zgarish loyihaga kiritilmadi. Bu darsning eng muhim qismi — nega.

Hayotiy o'xshatish: rozetka va vilka. Devordagi rozetka — port: u "220 volt, ikki teshik" degan shartnoma. Choynak, telefon zaryadlagichi, changyutgich — adapterlar. Uy qurilganda elektrchi qaysi asbob ulanishini bilmaydi. Lekin har xonaga rozetka qo'yish pul turadi. Omborxonaga o'nta rozetka kerak emas.

2. Port va adapter: ikki tomon

2.1 Qisqa takror

Hexagonal arxitektura (Ports and Adapters) — Alistair Cockburn 2005-yilda nomlagan usul. G'oya: ilovaning markazida biznes qoidalari turadi. Markaz tashqi texnologiyani bilmaydi. U faqat portlar orqali gaplashadi.

  • Port — markaz tashqaridan nima kutishini yoki tashqariga nima taklif qilishini aytadigan interfeys.
  • Adapter — portning aniq bajarilishi: Postgres, HTTP controller, xotiradagi massiv.

Olti burchak (hexagon) shaklining ma'nosi yo'q. Cockburn maqolasida shuni aniq yozadi: shakl "oltita soni muhim bo'lgani uchun" emas, port va adapterlarni chizishga joy bo'lishi uchun tanlangan. Muhimi — ichkari va tashqari.

2.2 Driving va driven

Portlar ikki xil bo'ladi. Cockburn ularni "primary" va "secondary" deb ham ataydi, "driving" va "driven" nomlari ham undan. Bu farq ko'pincha unutiladi:

Tomon Kim chaqiradi Webhook misolida
driving (kiruvchi) tashqi dunyo markazni HTTP controller, test
driven (chiquvchi) markaz tashqi dunyoni ombor, sir generatori, URL tekshiruvi

Driving (boshqaruvchi, kiruvchi) adapter markazga buyruq beradi: "obuna yarat". HTTP controller, CLI buyrug'i, navbat ishchisi, test — hammasi driving adapter. Ular uchun port — use case'ning o'zi, ya'ni ObunaXizmati klassining ochiq metodlari.

Driven (boshqariladigan, chiquvchi) adapter markazning iltimosini bajaradi: "egasining obunalarini sana", "yangi sir ber". Ular uchun port — markaz yozgan interfeys. Markaz interfeysni o'zi e'lon qiladi, adapter esa unga moslashadi. Bog'liqlik yo'nalishi shu yerda teskari aylanadi: Postgres kodi markazga bog'liq, markaz Postgres'ga emas. Bu — DIP (bog'liqlik inversiyasi), SOLID 2: LSP, ISP, DIP darsidagi tamoyilning arxitektura darajasidagi ko'rinishi.

flowchart LR
  HTTP["HTTP controller"] --> X["ObunaXizmati"]
  T["test"] --> X
  X --> D["domen: yangiObuna"]
  X --> P{{"port: ObunaOmbori"}}
  X --> S{{"port: SirGenerator"}}
  X --> U{{"port: UrlTekshiruvchi"}}
  P --> PG["Pg adapteri"]
  P --> XO["xotira adapteri"]

Chapda — driving tomon: ular ObunaXizmati ni chaqiradi. O'ngda — driven tomon: uchta port va ombor portining ikki adapteri. Markazdagi klass na HTTP'ni, na Postgres'ni biladi. Strelkalarga qarang: hammasi markazga yoki markaz e'lon qilgan portga qarab boradi.

Tekshirib ko'ring: vazifalar-api da 31-qismdan beri LlmProvayder interfeysi va oltita provayder bor. Bu driving yoki driven port?

Javob

Driven. Markaz (AI xizmati) "menga matn yaratib beradigan narsa kerak" deydi va interfeysni o'zi e'lon qiladi. Groq, Gemini yoki Anthropic adapterlari unga moslashadi. AI xizmatini chaqiradigan HTTP controller va Telegram boti esa driving tomonda.

3. Boshlang'ich holat: bitta faylda yetti ish

Kanondagi webhook.controller.ts ning yarat metodi nimalar qilishini sanaymiz:

Ish Qaysi qatlamga tegishli
req.body ni Zod bilan tekshirish kiruvchi adapter
URL shaklini tekshirish (SSRF) domen qoidasi, lekin kutubxona orqali
sir yaratish (sirYarat()) chiquvchi port
tranzaksiya, RLS, advisory lock chiquvchi adapter
"5 tadan ko'p emas" qoidasi domen
INSERT … RETURNING chiquvchi adapter
201, Location, Cache-Control kiruvchi adapter

Yetti xil ish, uch xil qatlam. Domen qoidasi — bitta qator — SQL'ning o'rtasida turibdi (qisqartirildi):

ts
await c.query("SELECT pg_advisory_xact_lock(…)", [egasi]);
const n = (await c.query(…count(*)…)).rows[0]?.n ?? 0;
if (n >= MAKS_OBUNA) throw new KonfliktXatosi(…);
return (await c.query(`INSERT INTO webhook_obunalari …`)).rows[0];

Qoida xato javobini ham o'zi tanlaydi: KonfliktXatosi — bu HTTP 409. Ya'ni "limitdan oshdi" degan biznes fakti va "mijozga 409 qaytar" degan HTTP qarori bitta joyda. Coupling, cohesion va modul chegaralari tilida bu past ichki birlik (cohesion). Bitta funksiya bir nechta o'zgarish sababiga ega.

4. Markazni ajratish

Kanon tajribasida shu uchta use case (yaratish, ro'yxat, o'chirish) to'rt qismga bo'lindi. Kod kanondan, qatorlar telefon uchun bo'lindi, mazmuni aynan. Quyidagi bloklar bitta kichik loyiha: oxirgi blokdagi test ularni birga ishga tushiradi.

4.1 Domen: sof qoida

ts
// fayl: domen/obuna.ts — sof domen: kutubxona, baza, HTTP yo'q
export const HODISALAR = [
  "vazifa.yaratildi", "vazifa.yangilandi",
  "vazifa.bajarildi", "vazifa.ochirildi",
] as const;
export type Hodisa = (typeof HODISALAR)[number];
export const MAKS_OBUNA = 5;

export type Obuna = {
  id: number;
  egasi: number;
  url: string;
  hodisalar: Hodisa[];
  faol: boolean;
};
export type YangiObuna = Omit<Obuna, "id">;

export class ObunaLimitiXatosi extends Error {
  constructor() {
    super(`Ko'pi bilan ${String(MAKS_OBUNA)} ta webhook`);
    this.name = "ObunaLimitiXatosi";
  }
}

/** Qoida: limitda bo'lsa — rad; hodisalar berilmasa — hammasi */
export function yangiObuna(
  egasi: number,
  url: string,
  mavjudSoni: number,
  hodisalar?: readonly Hodisa[],
): YangiObuna {
  if (mavjudSoni >= MAKS_OBUNA) throw new ObunaLimitiXatosi();
  return {
    egasi, url, faol: true,
    hodisalar: [...(hodisalar ?? HODISALAR)],
  };
}

Faylda birorta import yo'q. ObunaLimitiXatosi oddiy Error dan meros oladi — HTTP holat kodi yo'q. 409 mi yoki boshqa narsami — buni kiruvchi adapter hal qiladi. Telegram botda bu xato "Siz 5 ta webhook qo'shib bo'lgansiz" degan xabarga aylanadi, HTTP'da — 409.

E'tibor bering: domen faqat mavjudSoni ni oladi. U sanashni bilmaydi. Sanash — omborning ishi.

4.2 Portlar: markaz nima kutadi

ts
// fayl: ilova/portlar.ts — chiquvchi portlar: NIMA kerak
import type { Obuna, YangiObuna } from "../domen/obuna.ts";

/** Unit of Work: ichidagi amallar bitta tranzaksiyada
 *  va shu egasi bo'yicha ketma-ket */
export interface ObunaOmbori {
  bittaEgasiUchun<T>(
    egasi: number,
    ish: (o: EgasiObunalari) => Promise<T>,
  ): Promise<T>;
}
export interface EgasiObunalari {
  soni(): Promise<number>;
  qosh(o: YangiObuna, sir: string): Promise<Obuna>;
  royxat(): Promise<Obuna[]>;
  ochir(id: number): Promise<boolean>;
}
export type SirGenerator = () => string;
/** SSRF shakl tekshiruvi — xato bo'lsa throw */
export type UrlTekshiruvchi = (url: string) => void;

Eng qiziq joy — bittaEgasiUchun. Oddiy repository'da soni() va qosh() alohida metodlar bo'lardi. Use case ularni ketma-ket chaqirsa, poyga paydo bo'ladi. Ikki so'rov bir vaqtda "4 ta bor" deb ko'radi va ikkalasi ham qo'shadi. Aynan shu xato Biznes mantiq zaifliklari darsida topilgan edi. Parallel 20 so'rov 20 ta obuna yaratgan, limit esa 5 edi.

Port bu muammoni shartnoma darajasida yechadi: "ish ichidagi hamma amal bitta egasi uchun ketma-ket bajariladi". Qanday — adapter hal qiladi. Bu Unit of Work (ish birligi) naqshi, Ma'lumotga kirish patternlari darsida ko'rgansiz.

SirGenerator va UrlTekshiruvchi — oddiy funksiya turlari. Hamma port klass bo'lishi shart emas. Bitta metodli interfeys o'rniga funksiya turi — TypeScript'da arzonroq va testda qulayroq.

4.3 Use case: orkestr

ts
// fayl: ilova/obunalar.ts — faqat domen va portlarga bog'liq
import { yangiObuna } from "../domen/obuna.ts";
import type { Hodisa, Obuna } from "../domen/obuna.ts";
import type {
  ObunaOmbori, SirGenerator, UrlTekshiruvchi,
} from "./portlar.ts";

export class ObunaXizmati {
  readonly #ombor: ObunaOmbori;
  readonly #sir: SirGenerator;
  readonly #urlTekshir: UrlTekshiruvchi;

  constructor(
    ombor: ObunaOmbori,
    sir: SirGenerator,
    urlTekshir: UrlTekshiruvchi,
  ) {
    this.#ombor = ombor;
    this.#sir = sir;
    this.#urlTekshir = urlTekshir;
  }

  /** sir — faqat shu javobda qaytadi */
  async yarat(
    egasi: number,
    url: string,
    hodisalar?: readonly Hodisa[],
  ): Promise<{ obuna: Obuna; sir: string }> {
    this.#urlTekshir(url);
    const sir = this.#sir();
    return this.#ombor.bittaEgasiUchun(egasi, async (o) => {
      const soni = await o.soni();
      const yangi = yangiObuna(egasi, url, soni, hodisalar);
      return { obuna: await o.qosh(yangi, sir), sir };
    });
  }

  royxat(egasi: number): Promise<Obuna[]> {
    return this.#ombor.bittaEgasiUchun(egasi, (o) => o.royxat());
  }

  ochir(egasi: number, id: number): Promise<boolean> {
    return this.#ombor.bittaEgasiUchun(egasi, (o) => o.ochir(id));
  }
}

yarat ichidagi bitta uzun qator uchta o'zgaruvchiga bo'lindi — mazmuni o'zgarmadi. Use case orkestr vazifasini bajaradi: tartibni belgilaydi (avval URL, keyin sir, keyin qulf ichida sanash va qo'shish), lekin o'zi hech narsani bilmaydi. Na SQL, na HTTP, na Nest dekoratori.

Tartibga qarang: URL tekshiruvi ombordan oldin. Yomon URL bilan tranzaksiya ochilmaydi, qulf olinmaydi. Bu tartib endi testda tekshiriladigan qoida.

Sir ham qulfdan oldin yaratiladi. Sabab — qulf ichidagi vaqtni qisqa tutish. Advisory lock ushlab turilgan har millisoniyada shu egasining boshqa so'rovlari kutadi. Qulf ichida faqat sanash va qo'shish qoladi. Bu qaror kanondagi controllerda ham xuddi shunday edi — hexagonal ko'rinish uni o'zgartirmadi, faqat ko'rinadigan qildi.

Tekshirib ko'ring: Use case ichida this.#sir() ni bittaEgasiUchun ichiga ko'chirsak, testlar yiqiladimi? Xulq qanday o'zgaradi?

Javob

Testlar yiqilmaydi: sir generatori soxta va bir zumda ishlaydi. Xulq ham tashqaridan bir xil. Farq faqat yuk ostida ko'rinadi: haqiqiy sir generatori (randomBytes) qulf ichida ishlasa, qulf biroz uzoqroq ushlanadi. Bunday qarorlarni test emas, kod ko'rib chiqish va o'lchov ushlaydi. Shuning uchun tartib use case'da aniq yozilgan va izohlangan.

4.4 Ikki adapter

Xotira adapteri — test va prototip uchun:

ts
// fayl: adapterlar/xotira-ombor.ts — egasi bo'yicha navbat
import type { Obuna, YangiObuna } from "../domen/obuna.ts";
import type {
  EgasiObunalari, ObunaOmbori,
} from "../ilova/portlar.ts";

export class XotiraObunaOmbori implements ObunaOmbori {
  #qatorlar: Obuna[] = [];
  #keyingi = 1;
  readonly #navbat = new Map<number, Promise<unknown>>();

  bittaEgasiUchun<T>(
    egasi: number,
    ish: (o: EgasiObunalari) => Promise<T>,
  ): Promise<T> {
    const oldingi = this.#navbat.get(egasi) ?? Promise.resolve();
    const natija = oldingi.then(() => ish(this.#korinish(egasi)));
    this.#navbat.set(egasi, natija.catch(() => undefined));
    return natija;
  }

  #korinish(egasi: number): EgasiObunalari {
    const meniki = (q: Obuna) => q.egasi === egasi;
    return {
      soni: () =>
        Promise.resolve(this.#qatorlar.filter(meniki).length),
      qosh: (o: YangiObuna) => {
        const q = { ...o, id: this.#keyingi++ };
        this.#qatorlar.push(q);
        return Promise.resolve(q);
      },
      royxat: () =>
        Promise.resolve(this.#qatorlar.filter(meniki)),
      ochir: (id: number) => {
        const n = this.#qatorlar.length;
        this.#qatorlar = this.#qatorlar.filter(
          (q) => !(q.id === id && q.egasi === egasi));
        return Promise.resolve(this.#qatorlar.length < n);
      },
    };
  }
}

Kanonda egasi filtri har metodda takrorlangan, bu yerda u bitta meniki funksiyasiga chiqarildi — xulq aynan. Asosiy hiyla — #navbat. Har egasi uchun oxirgi ishning Promise i saqlanadi. Yangi ish uning orqasidan zanjirga ulanadi. Shunda bitta egasining ishlari ketma-ket, boshqa egalariniki esa parallel ketadi. .catch(() => undefined) — oldingi ish xato bilan tugasa ham navbat to'xtamasin.

Pg adapteri esa xuddi shu shartnomani Postgres bilan bajaradi (bo'lak, qisqartirildi):

ts
await c.query("BEGIN");
await c.query(
  "SELECT set_config('ilova.foydalanuvchi_id', $1, true)",
  [String(egasi)]);
await c.query(
  "SELECT pg_advisory_xact_lock(hashtext('webhook_obunalari'), $1)",
  [egasi]);
const n = await ish(korinish(c, egasi));
await c.query("COMMIT");

Oxirgi qator 70 belgidan uzun — bu SQL satri, uni bo'lsak so'rov o'zgaradi. Xotiradagi Promise zanjiri va Postgres'dagi advisory lock — bitta shartnomaning ikki bajarilishi. RLS sozlamasi (set_config) va SQL — kanondagi controller bilan bir xil.

4.5 Bazasiz test

ts
// fayl: test/domen.test.ts — baza, HTTP, Nest yo'q
import { test } from "node:test";
import assert from "node:assert/strict";
import { ObunaXizmati } from "../ilova/obunalar.ts";
import { XotiraObunaOmbori } from "../adapterlar/xotira-ombor.ts";
import { MAKS_OBUNA, ObunaLimitiXatosi } from "../domen/obuna.ts";

const xizmat = () => new ObunaXizmati(
  new XotiraObunaOmbori(),
  () => "sir-sinov",
  (u) => {
    if (!u.startsWith("https://")) throw new Error("https kerak");
  },
);

test("limit: 5 tadan keyin rad; boshqa egasi ta'sirlanmaydi",
  async () => {
    const x = xizmat();
    for (let i = 0; i < MAKS_OBUNA; i++) {
      await x.yarat(1, `https://a.example/${String(i)}`);
    }
    await assert.rejects(
      x.yarat(1, "https://a.example/6"), ObunaLimitiXatosi);
    const b = await x.yarat(2, "https://b.example");
    assert.equal(b.obuna.egasi, 2);
  });

test("parallel 20 so'rov — 5 tasi o'tadi", async () => {
  const x = xizmat();
  const n = await Promise.allSettled(
    Array.from({ length: 20 }, (_, i) =>
      x.yarat(1, `https://a.example/${String(i)}`)));
  const otdi = n.filter((r) => r.status === "fulfilled");
  assert.equal(otdi.length, MAKS_OBUNA);
  assert.equal((await x.royxat(1)).length, MAKS_OBUNA);
});

test("URL tekshiruvi ombordan OLDIN", async () => {
  await assert.rejects(
    xizmat().yarat(1, "http://127.0.0.1"), /https kerak/);
});

test("begona obunani o'chirib bo'lmaydi", async () => {
  const x = xizmat();
  const { obuna } = await x.yarat(1, "https://a.example");
  assert.equal(await x.ochir(2, obuna.id), false);
  assert.equal(await x.ochir(1, obuna.id), true);
});

To'rtta test. Hech biri Postgres'ni, Nest'ni yoki HTTP'ni bilmaydi. Sir va URL tekshiruvi — inline yozilgan soxta adapterlar: bitta qatorli funksiyalar. Testni o'zingiz yurgizsangiz, node --test test/domen.test.ts buyrug'i to'rt fayldan iborat loyihani to'g'ridan ishga tushiradi — Node 24 TypeScript turlarini o'zi o'chiradi.

4.6 Kompozitsiya ildizi: kim kimni ulaydi

Markaz adapterlarni bilmaydi. Unda new ObunaXizmati(new PgObunaOmbori(pool), …) qatorini kim yozadi? Javob — kompozitsiya ildizi (composition root): ilova yig'iladigan yagona joy. Modular monolit va hexagonal arxitektura NestJS'da darsida ko'rgansiz: vazifalar-api da bu ombor-yarat.ts va Nest modullari.

Kanon tajribasida bu ulash yozilmadi — kiruvchi adapter yo'q edi. Nest'da u taxminan shunday ko'rinardi (sxema, sinalmagan):

ts
@Module({
  providers: [{
    provide: ObunaXizmati,
    inject: [WEBHOOKLAR],
    useFactory: (o: WebhookSozlamasi) => new ObunaXizmati(
      new PgObunaOmbori(o.pool),
      sirYarat,
      (url) => urlTekshir(url),
    ),
  }],
})
export class WebhookModule {}

Bu yerda Nest faqat chetda ishlaydi. ObunaXizmati da birorta dekorator yo'q — u oddiy klass. Nest'ga uni useFactory orqali tanishtiramiz (Dynamic modullar va DI va IoC konteyner darslaridagi usul). Ertaga ombor almashsa, faqat shu bitta joy o'zgaradi.

Qat'iy hexagonal maktabi aynan shuni talab qiladi: freymvork yelimi markazdan tashqarida. Kanondagi VazifalarService esa @Injectable() dekoratori bilan yozilgan. Bu farqni keyingi darsda dependency rule nuqtai nazaridan o'lchaymiz.

5. O'lchov: nima yutildi, nima to'landi

5.1 Raqamlar

Kanon tajribasida (Windows 11, Node 24.21.0, PostgreSQL 18.6) ikkala variant solishtirildi:

Ko'rsatkich Oldin (controller) Keyin (hexagonal)
fayl / qator (bo'sh qatorsiz) 1 / 84 5 / 129
test vositasi Vitest, Nest + Postgres + HTTP node --test, xotira
test vaqti 6.50–7.69 s (3 test) 123–177 ms (4 test)
parallel 20, limit 5 5 o'tdi xotira: 5, Pg: 5

Har biri bir necha marta yurgizildi: domen testlari 5 marta, Vitest 3 marta. Pg adapterining alohida testi (parallel 20 + RLS) 419–457 ms oldi.

Obuna qoidalari testi: bir yurgizish vaqti (mediana)
  • Nest + Postgres + HTTP (3 test)6 760 ms
  • Pg adapteri (1 test)447 ms
  • xotira adapteri (4 test)138 ms

Manba: Kanon tajribasi (IlmHamroh, 2026-11-09): Vitest 3 marta (6.50/6.76/7.69 s), node --test 5 marta (123–177 ms), Pg adapteri 3 marta (419–457 ms); Windows 11, Node 24.21.0, PostgreSQL 18.6

Mediana: 6 760 ms ga qarshi 138 ms — taxminan 49 marta. Chap ustun bilan o'ng ustun orasidagi farqni ko'z bilan solishtiring.

5.2 Natijani halol o'qish

"50 marta tezroq" — chiroyli raqam. Lekin u nimani o'lchaganini aniq aytish kerak.

Birinchidan, solishtirilgan narsalar teng emas. Vitest chiqishida vaqtning 45–51 % i import — Nest ilovasini va uning bog'liqliklarini yuklash. Testlarning o'zi 43–48 %. Ya'ni sekinlikning yarmi — freymvork yuklanishi. Ikkinchidan, vositalar har xil: Vitest o'z transform bosqichiga ega, node --test esa yo'q.

Demak to'g'ri xulosa: "domen qoidasini tekshirish sikli ~50 marta qisqardi". "Qoida 50 marta tez ishlaydi" emas — qoidaning o'zi ikkala holatda ham bir necha mikrosoniya.

Uchinchidan, hexagonal variant hamma narsani qamramadi. Kiruvchi adapter (yangi controller) yozilmadi — HTTP shakli o'zgarmasligi kerak edi. To'rtinchi marshrut (yetkazishlar ro'yxati) ko'chirilmadi. ochir endi 404 o'rniga false qaytaradi — uni 404 ga aylantirish ham kiruvchi adapterning ishi. Ya'ni to'liq ko'chishda qator soni 129 dan ham ko'p bo'lardi.

Shunga qaramay, bitta natija aniq: poyga himoyasi saqlandi. Ikkala adapter ham 20 parallel so'rovdan aynan 5 tasini o'tkazdi. Port shartnomasi (bittaEgasiUchun) bu kafolatni adapter tanlovidan mustaqil qildi.

Tekshirib ko'ring: Hamkasbingiz "domen testlari 138 ms — demak Postgres testlarini o'chirib tashlasak bo'ladi" dedi. Rozimisiz?

Javob

Yo'q. Xotira adapteri faqat domen va use case'ni tekshiradi. RLS, SQL, advisory lock va tranzaksiya — Pg adapterining ichida, ularni faqat haqiqiy Postgres bilan test tekshiradi. Keyingi bo'limdagi voqea aynan shuni ko'rsatadi: adapter xatosi domen testlarida umuman ko'rinmadi.

6. Biz shunday xato qildik: adapter ichidagi xato

Pg adapterining birinchi versiyasida RLS sozlamasi nomini noto'g'ri yozdik: app.egasi. Loyihada esa siyosatlar ilova.foydalanuvchi_id ni o'qiydi (Row Level Security). Natija:

text
ℹ tests 1 ℹ pass 0 ℹ fail 1 ℹ duration_ms 326.3562   AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:

Tarjimasi: "1 test, o'tdi 0, yiqildi 1 … kutilgan qiymatlar qat'iy teng emas". Nima bo'lgan: RLS siyosati ilova.foydalanuvchi_id ni topmadi va hamma qatorni yashirdi. 20 ta INSERT ning hammasi rad etildi — 0 tasi o'tdi. Test esa 5 ta kutgan edi.

Uch narsaga e'tibor bering.

Birinchi: shu paytda to'rtta domen testi yashil edi. Ular xotira adapteri bilan ishlaydi, RLS'ni bilmaydi. Xato aynan adapterda bo'lgani uchun faqat adapter testi uni ko'rdi.

Ikkinchi: xato "yopiq tomonga" ketdi. RLS sozlama bo'lmasa hech narsani ko'rsatmaydi va hech narsani yozdirmaydi. Bu Fail-open va fail-closed darsidagi "yopiq sukut" ning amaldagi ko'rinishi. Agar siyosat teskari yozilganda — "sozlama yo'q bo'lsa hammasi ko'rinsin" — xato jimgina ma'lumot sizdirardi.

Uchinchi: tuzatish bitta satr bo'ldi va ikkinchi urinishda test uch marta ketma-ket o'tdi. Hexagonal tuzilma xatoni qayerda qidirishni aniq ko'rsatdi: domen testlari yashil, adapter testi qizil — demak muammo adapterda.

Saboq: hexagonal arxitektura integratsiya testlarini yo'qotmaydi. U ularni joyiga qo'yadi. Qoidalar — tez, bazasiz testlarda. Adapter — kam sonli, sekin, lekin haqiqiy baza bilan testda.

7. Port shartnomasi: navbatsiz adapter nima qiladi

bittaEgasiUchun va'dasini bajarmaydigan adapter qanday bo'lardi? Buni paketsiz modelda ko'ramiz. Ikki xil ombor bor: biri navbatsiz, biri egasi bo'yicha navbatli. Use case ikkalasida bir xil:

js
function omborYarat(navbatli) {
  const qatorlar = [];
  let oxirgi = Promise.resolve();
  const korinish = {
    soni: async () => qatorlar.length,
    qosh: async (url) => { qatorlar.push(url); },
  };
  return {
    qatorlar,
    bitta(ish) {
      if (!navbatli) return ish(korinish);
      const natija = oxirgi.then(() => ish(korinish));
      oxirgi = natija.catch(() => undefined);
      return natija;
    },
  };
}

function yarat(ombor, url) {
  return ombor.bitta(async (o) => {
    if ((await o.soni()) >= 5) throw new Error("limit");
    await o.qosh(url);
  });
}

for (const navbatli of [false, true]) {
  const ombor = omborYarat(navbatli);
  const sorovlar = Array.from({ length: 20 }, (_, i) =>
    yarat(ombor, `https://a.example/${i}`));
  const n = await Promise.allSettled(sorovlar);
  const otdi = n.filter((r) => r.status === "fulfilled").length;
  const nom = navbatli ? "navbatli" : "navbatsiz";
  const soni = ombor.qatorlar.length;
  console.log(`${nom}: ${otdi}/20 o'tdi, saqlandi ${soni}`);
}

Konsolda:

text
navbatsiz: 20/20 o'tdi, saqlandi 20
navbatli: 5/20 o'tdi, saqlandi 5

Navbatsiz omborda 20 ta so'rov birdaniga await o.soni() ga yetadi. Hammasi 0 ni ko'radi, chunki hech kim hali qo'shmagan. Keyin hammasi qo'shadi. Navbatli omborda har ish oldingisi tugaguncha kutadi: 6-chisi 5 ni ko'radi va rad etiladi.

Model soddalashtirilgan: bitta egasi, catch siz xato xabari. Lekin u asosiy fikrni ko'rsatadi: use case bir xil, natija esa adapterga qarab 20 yoki 5. Shuning uchun port hujjatidagi izoh ("ketma-ket bajariladi") — bezak emas, shartnoma. Uni har adapter uchun alohida test tekshirishi kerak.

8. Qachon kerak va qachon kerak emas

8.1 Yordam bergan joylar

Loyihada hexagonal naqsh o'zini oqlagan joylar bor. Hammasida bitta umumiy belgi: bir portga bir nechta haqiqiy adapter.

Port Adapterlar Nima uchun
VazifaOmbori xotira, fayl, kesh, pg, Prisma saqlash 25–27-qismlarda almashdi
LlmProvayder oltita provayder narx va limitga qarab almashtirish
Cheklagich Pg, Redis, xotira va boshqalar Redis bor-yo'qligiga qarab

Teskari misol ham bor. SmsProvayder portiga uchta adapter yozilgan: EskizProvayder, PlayMobileProvayder va ehtiyot yo'l uchun ZaxiraliSms o'rami. Lekin kodni qidirsangiz, ishga tushishda faqat Eskiz ulanadi. Qolgan ikkitasi hech qayerda yaratilmaydi — o'lik kod. Port ikkinchi adapter yozishni oson qildi, lekin unga ehtiyoj paydo bo'lmadi. Bu YAGNI'ning jonli namunasi: haqiqiy ikkinchi adapter — o'lchov, yozib qo'yilgan adapter — faqat umid.

jamoa capstone'ining dizayn hujjati ham shu naqshni bitta joyda tanlagan: to'lov provayderi uchun TolovProvayderi porti (Payme, Click, Stripe adapterlari). Sababi — uchta haqiqiy provayder va ularning har biri uchun alohida soxta server bilan shartnoma testi.

8.2 Ongli ravishda qilinmagan joy

Webhook obunalarida esa hexagonal kanonga kiritilmadi. Uch savol bilan (Dasturiy arxitektura nima va trade-off tafakkuri darsidagi kabi):

  • Yutuq: limit qoidasi bazasiz testlanadi; test sikli 6.8 s dan 0.14 s ga qisqaradi.
  • Narx: +4 fayl, qator 84 dan 129 ga (+54 %), yana yozilmagan kiruvchi adapter. Yangi dasturchi bitta marshrutni tushunish uchun besh faylni o'qiydi.
  • Qachon kerak: obunalar uchun ikkinchi saqlash joyi paydo bo'lsa yoki limit qoidasi murakkablashsa (masalan, tarifga bog'liq limit — jamoa da shunday bo'ladi).

Hozir loyihada bitta dasturchi va bitta Postgres. Obunalar boshqa joyga ko'chmaydi. Qoida — bitta if. Uni Vitest testi 7 soniyada tekshiradi va bu test HTTP shaklini ham, RLS'ni ham bir vaqtda qamraydi. Narx foydadan katta.

Bu "hexagonal yomon" degani emas. Bu "hexagonal — asbob, maqsad emas" degani. Asosiy tamoyillar: DRY, KISS, YAGNI, kompozitsiya darsidagi YAGNI bu yerda ham ishlaydi: ikkinchi adapter kerak bo'lmaguncha portning foydasi faqat test tezligida.

Tekshirib ko'ring: jamoa da obuna limiti tarifga bog'liq bo'ladi: bepul — 2 ta, "Jamoa" tarifi — 20 ta. Tarif boshqa modulda (billing). Bu hexagonal variantni qayta ko'rish uchun sababmi?

Javob

Ha. Endi qoida bitta if emas: limit tashqi manbadan keladi. Domen yangiObuna(…, mavjudSoni, limit) ni oladi, use case esa limitni yangi chiquvchi port orqali so'raydi: TarifLimitlari. Testda bu port bitta qatorli funksiya, prod'da — billing modulining ochiq API'si. Ikkinchi adapter (test va billing) paydo bo'ldi — hexagonal foydasi ortdi. "Qachon kerak" shartlaridan biri bajarildi.

9. Freymvorkni almashtirish haqida

Hexagonal arxitekturaning eng ko'p aytiladigan va'dasi — "freymvorkni almashtirsangiz, markaz o'zgarmaydi". Loyihada bu va'da bir marta tekshirilgan: 30-qismda HTTP qatlami Express'dan Nest'ga ko'chdi va vazifa.ts, royxat-mantiq.ts, beshta ombor o'zgarmadi (Modular monolit va hexagonal arxitektura NestJS'da).

Lekin halol bo'laylik: freymvork almashtirish — kam uchraydigan voqea. Ko'p loyihalar bunga hech qachon duch kelmaydi. Kundalik foyda — boshqa joyda: tez testlar, xatoni qidirish joyi aniq, tashqi xizmat almashganda bitta fayl. Hexagonal'ni "bir kun Nest'dan voz kechamiz" deb emas, shu kundalik foydalar uchun tanlang.

10. Ko'p uchraydigan xatolar

10.1 Har klassga interfeys

Port faqat haqiqiy chegara uchun kerak: baza, tashqi API, vaqt, tasodif. teglariniOl(matn) kabi sof funksiyaga interfeys yozish — faqat qo'shimcha fayl. Uni to'g'ridan chaqiring va to'g'ridan testlang.

10.2 Domenda HTTP holat kodi

throw new KonfliktXatosi(…) domen ichida — markaz HTTP'ni bilib qoldi. Domen o'z tilida xato tashlasin (ObunaLimitiXatosi), holat kodini kiruvchi adapter tanlasin.

10.3 Portni adapterga moslab yozish

query(sql: string) metodli "port" — bu Postgres interfeysi, port emas. Port markaz tilida gapiradi: soni(), qosh(). Adapter almashsa port o'zgarishi kerak bo'lsa — u noto'g'ri yozilgan.

10.4 Faqat xotira adapteri bilan testlash

Domen testlari yashil bo'lishi adapter to'g'ri ekanini isbotlamaydi. RLS nomi voqeasini eslang. Har adapterga kamida bitta haqiqiy test.

10.5 Shartnomani faqat izohda qoldirish

"Ketma-ket bajariladi" degan va'da testsiz qolsa, keyingi adapter uni buzadi. Navbatsiz model 20 tadan 20 tasini o'tkazdi. Va'da — testda.

11. Mashqlar

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

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

  • Markaz tashqi dunyodan nima kutishini aytadigan interfeys —
  • HTTP controller va test markazni chaqiradi — ular tomonda
  • Ombor va sir generatori markaz chaqiradigan tomonda —
  • Bir nechta amalni bitta tranzaksiyada bajarishni va'da qiladigan naqsh — Unit of
  • Kanon tajribasida domen testlari bazasiz necha marta tezroq bo'ldi — taxminan marta
Yechim
  • port — masalan ObunaOmbori, SirGenerator.
  • driving — kiruvchi tomon; ular uchun port — use case metodlari.
  • driven — chiquvchi tomon; interfeysni markaz e'lon qiladi.
  • Work — bittaEgasiUchun shu va'dani beradi.
  • 50 — 6 760 ms ga qarshi 138 ms (mediana); farqning yarmi freymvork yuklanishi.

2-mashq (o'rta): kiruvchi adapter

Kanon tajribasida kiruvchi adapter yozilmagan edi. Uning eng muhim ishini o'zingiz yozing: domen xatolarini HTTP javobiga aylantirish. javob(ish) funksiyasi async funksiyani oladi, uni bajaradi va { status, kod } qaytaradi:

  • muvaffaqiyat — 201, kod — "ok";
  • ObunaLimitiXatosi — 409, "webhook-limiti";
  • UrlXatosi — 422, "url-yaroqsiz";
  • boshqa har qanday xato — 500, "ichki-xato".

Use case modeli berilgan: u sanaydi va limitni tekshiradi. Uch xil so'rovni yuboring va natijalarni chiqaring.

Ishora: xato turini instanceof bilan aniqlang (try / catch / finally), try/catch async funksiyada await bilan ishlaydi.

Yechim
js
class ObunaLimitiXatosi extends Error {}
class UrlXatosi extends Error {}

const saqlangan = [];
async function yarat(url) {
  if (!url.startsWith("https://")) throw new UrlXatosi(url);
  if (saqlangan.length >= 5) throw new ObunaLimitiXatosi();
  saqlangan.push(url);
  return { id: saqlangan.length };
}

async function javob(ish) {
  try {
    await ish();
    return { status: 201, kod: "ok" };
  } catch (x) {
    if (x instanceof ObunaLimitiXatosi) {
      return { status: 409, kod: "webhook-limiti" };
    }
    if (x instanceof UrlXatosi) {
      return { status: 422, kod: "url-yaroqsiz" };
    }
    return { status: 500, kod: "ichki-xato" };
  }
}

for (let i = 1; i <= 5; i++) await yarat(`https://a.example/${i}`);
const sorovlar = [
  () => yarat("http://127.0.0.1"),
  () => yarat("https://a.example/6"),
  () => { throw new TypeError("kutilmagan"); },
];
for (const s of sorovlar) {
  const j = await javob(s);
  console.log(j.status, j.kod);
}

Konsolda:

text
422 url-yaroqsiz
409 webhook-limiti
500 ichki-xato

Birinchi so'rov URL tekshiruvida to'xtadi — limitga yetmadi ham. Tartib use case'da belgilangan. Uchinchi so'rov sinxron throw qildi: await ish() uni ham ushlaydi, chunki try ichida chaqirilgan. Domen xatolari HTTP'ni bilmaydi — xaritalash faqat shu funksiyada. Telegram bot uchun boshqa javob yoziladi, domen o'zgarmaydi.

3-mashq (qiyin): adapter shartnoma testi

Bitta shartnoma testi bir nechta adapterni tekshirsin. shartnoma(nom, yarat) funksiyasi yarat() dan yangi ombor oladi va uchta tekshiruvni bajaradi:

  1. "qo'shilgani ro'yxatda" — egasi 1 qo'shadi, royxat(1) da 1 ta;
  2. "begona ko'rinmaydi" — egasi 2 qo'shadi, royxat(1) da 0 ta;
  3. "begonani o'chirmaydi" — egasi 1 qo'shgan obunani egasi 2 o'chira olmaydi (false).

Har adapter uchun nom: o'tdi/3 va yiqilgan tekshiruvlar nomini chiqaring. Ikkita adapter bering: to'g'ri va "nom xatosi" bor adapter — u royxat da egasini noto'g'ri maydon (egasiId) bo'yicha filtrlaydi, xuddi RLS sozlamasi nomi xato bo'lgandagidek.

Ishora: har tekshiruv uchun yangi ombor yarating — testlar bir-biriga ta'sir qilmasin. Tekshiruvlarni { nom, fn } massivida saqlang.

Yechim
js
function togri() {
  const q = [];
  return {
    qosh: (egasi, url) => q.push({ id: q.length + 1, egasi, url }),
    royxat: (egasi) => q.filter((x) => x.egasi === egasi),
    ochir(egasi, id) {
      const i = q.findIndex((x) => x.id === id && x.egasi === egasi);
      if (i < 0) return false;
      q.splice(i, 1);
      return true;
    },
  };
}

function nomXatosi() {
  const o = togri();
  const q = [];
  return {
    ...o,
    qosh(egasi, url) { q.push({ egasi, url }); o.qosh(egasi, url); },
    royxat: (egasi) => q.filter((x) => x.egasiId === egasi),
  };
}

const tekshiruvlar = [
  { nom: "qo'shilgani ro'yxatda", fn(o) {
    o.qosh(1, "https://a.example");
    return o.royxat(1).length === 1;
  } },
  { nom: "begona ko'rinmaydi", fn(o) {
    o.qosh(2, "https://b.example");
    return o.royxat(1).length === 0;
  } },
  { nom: "begonani o'chirmaydi", fn(o) {
    o.qosh(1, "https://a.example");
    return o.ochir(2, 1) === false;
  } },
];

function shartnoma(nom, yarat) {
  const yiqildi = tekshiruvlar
    .filter((t) => !t.fn(yarat()))
    .map((t) => t.nom);
  const otdi = tekshiruvlar.length - yiqildi.length;
  console.log(`${nom}: ${otdi}/${tekshiruvlar.length}`);
  for (const y of yiqildi) console.log(`  yiqildi: ${y}`);
}

shartnoma("to'g'ri", togri);
shartnoma("nom xatosi", nomXatosi);

Konsolda:

text
to'g'ri: 3/3
nom xatosi: 2/3
  yiqildi: qo'shilgani ro'yxatda

"Nom xatosi" adapteri egasiId maydonini o'qiydi, lekin bunday maydon yo'q — undefined === 1 hech qachon rost emas. Ro'yxat doim bo'sh. Qiziq joyi: "begona ko'rinmaydi" tekshiruvi o'tdi. Bo'sh ro'yxat begonani ham ko'rsatmaydi. Faqat ijobiy tekshiruv xatoni tutdi. Kanondagi RLS voqeasi ham shunday edi: "ko'rinmaslik" tekshiruvlari yashil, "5 tasi o'tsin" degan ijobiy tekshiruv qizil. Shartnoma testida doim ikkala yo'nalish bo'lsin: ko'rinishi kerak bo'lgan narsa ko'rinadi va ko'rinmasligi kerak bo'lgani ko'rinmaydi.

12. Real ishda

  • To'lov va SMS integratsiyalari — hexagonal'ning eng tabiiy joyi. Mahalliy bozorda Payme, Click, Uzum kabi provayderlar bir-biriga o'xshamaydi. Port bitta, adapterlar har biri uchun, va har adapterga soxta server bilan shartnoma testi.
  • Testlar sekinlashganda — jamoalar ko'pincha shu yerda hexagonal'ga keladi: CI 20 daqiqa, chunki har qoida Postgres bilan tekshiriladi. Domenni ajratish test vaqtini keskin qisqartiradi.
  • Legacy koddan chiqish — eski freymvorkdagi biznes qoidalarini avval port ortiga yashirib, keyin adapterni almashtirish (Legacy kod va texnik qarz bilan ishlash).
  • Intervyu savollari: "Ports and Adapters nima?", "Driving va driven port farqi?", "Hexagonal arxitekturani qachon tanlamaysiz?". Oxirgi savolga raqamli javob — +54 % kod va bitta saqlash joyi — kuchli dalil.

Xulosa

  • Hexagonal arxitektura: markazda domen va use case, tashqarida adapterlar; ular faqat port orqali gaplashadi.
  • Driving (kiruvchi) adapter markazni chaqiradi, driven (chiquvchi) adapter markaz e'lon qilgan portni bajaradi — bog'liqlik markazga qaraydi.
  • Kanon tajribasi: webhook obunalari 1 fayl / 84 qatordan 5 fayl / 129 qatorga; domen testlari 6.8 s o'rniga 0.14 s; poyga himoyasi ikkala adapterda 5/20.
  • Adapter xatosi (RLS nomi) domen testlarida ko'rinmadi — har adapterga haqiqiy shartnoma testi kerak.
  • O'zgarish loyihaga kirmadi: bitta saqlash joyi va bitta dasturchi uchun narx foydadan katta; ikkinchi adapter paydo bo'lganda qayta ko'riladi.

Keyingi dars: Clean va Onion arxitektura, pragmatik chegara — dependency rule'ni loyihaning vazifalar moduliga qo'llaymiz va qaysi buzilishlar ongli tanlov ekanini ajratamiz.

Manbalar

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

Hexagonal arxitektura (Ports and Adapters): webhook obunalarini yadroga ajratish va narxini o'lchash

25 daqvaqt
0belgi
Keyingi dars: Clean va Onion arxitektura: dependency rule, Entity va DTO farqi va pragmatik chegara
Telegram'da
Darsda xato koʻrdingizmi?

Izohlar · 0