Към съдържанието
wannacode

Hexagonal и clean architecture

Накратко: Хексагоналната архитектура (ports and adapters) дава на ядрото портове с неговите думи, а адаптерите за базата и външните услуги се включват отвън, затова зависимостите сочат навътре.

Проблем

Тестът, който иска банка

Плащането на поръчка има правила: платена поръчка не се плаща пак, а отказаната не става платена. Ето ядрото, както го е написал първият екип. Само си прави връзката с базата и клиента на доставчика на плащания CardPay:

class Checkout {
  orders = new SqlOrders("db.shop.local");
  provider = new CardPayClient();


  pay(id) {
    const order = this.orders.find(id);
    if (order.paid) return "вече е платена";
    const response = this.provider.charge(order.total * 100, "EUR", id);
    if (response.status !== "APPROVED") return "отказана";
    order.paid = true;
    this.orders.save(order);
    return "платена";
  }
}

Клиентът CardPay и хранилището с SQL са истински класове отвън. В урока тези „отвън“ са сведени до това, което правят в тест: нито база, нито мрежа има.

// Истинските класове отвън. Тук няма нито база, нито мрежа.
class SqlOrders {
  constructor(host) {
    throw new Error("няма връзка с " + host);
  }
}

Тестът на правилото „платена поръчка не се плаща пак“:

try {
  const checkout = new Checkout();
  console.log(checkout.pay("A-7"));
} catch (e) {
  console.log("Тестът пада: " + e.message);
}
Изход
Тестът пада: няма връзка с db.shop.local

Тестът не стига до правилото. Пада на първия ред, защото иска база. Ако имаше база, щеше да поиска мрежа и ключ на CardPay, а всяко пускане щеше да плаща наистина. И още: в ядрото са центовете, "EUR" и "APPROVED", думите на CardPay. Когато магазинът смени доставчика, се пренаписва ядрото.

Идеята

Портове и адаптери

В слоевете домейнът стоеше над данните. Hexagonal architecture (портове и адаптери) отива по-далеч: всичко отвън е еднакво „навън“, и базата, и доставчикът, и екранът. В средата е ядрото с правилата.

  • Порт е интерфейс на ядрото, с неговите думи: „плати тази поръчка за 120 €, кажи да или не“. Портът е на ядрото, не на доставчика;
  • адаптер е клас отвън, който изпълнява порта и превежда. CardPayAdapter превръща 120 € в 12000 цента, вика SDK-то и превежда "APPROVED" в true. Това е шаблонът Adapter, сложен на всяка граница на приложението.

Адаптерите са два вида. Водещите (driving) викат ядрото: контролерът, тестът, командата в конзолата. Водените (driven) ядрото вика през порт: плащането, поръчките, пощата.

Това е DIP за цялото приложение: не за един клас, а за всяка граница. А ядрото получава адаптерите си отвън, в конструктора, както в урока Singleton и Dependency Injection.

Виж го

Ядрото

Двата порта, поръчката и ядрото. Нищо тук не знае за CardPay, SQL или центове:

// Портовете: какво иска ядрото, с неговите думи
//   payments.charge(orderId, euros) връща true или false
//   orders.find(id) връща поръчката, orders.save(order)


// Ядрото: правилата, без нищо отвън
class Checkout {
  constructor(orders, payments) {
    this.orders = orders;
    this.payments = payments;
  }


  pay(id) {
    const order = this.orders.find(id);
    if (order.paid) return "вече е платена";
    const ok = this.payments.charge(id, order.total);
    if (!ok) return "отказана";
    order.paid = true;
    this.orders.save(order);
    return "платена";
  }
}
JavaScript няма интерфейси, затова портовете са коментар: всеки обект с charge(orderId, euros) става. Правилото се пази с внимание и с тестове, не с компилатор.

Виж го

Адаптерите и магазинът

SDK-то на доставчика, както го вижда програмата. Мрежата е заменена със записани отговори, а клиентът печата какво е получил:

// SDK-то на доставчика. Тук мрежата е заменена
// със записани отговори.
class CardPayClient {
  #answers;


  constructor(...answers) {
    this.#answers = answers;
  }


  charge(cents, currency, reference) {
    const status = this.#answers.shift();
    console.log(`  CardPay: ${reference} ${cents} ${currency} → ${status}`);
    return { status };
  }
}

Адаптерът към CardPay, двойникът за теста и поръчките в паметта:

// Адаптерът превежда думите на ядрото към доставчика
class CardPayAdapter {
  constructor(client) {
    this.client = client;
  }


  charge(orderId, euros) {
    const response = this.client.charge(euros * 100, "EUR", orderId);
    return response.status === "APPROVED";
  }
}


// Двойникът за теста: записва и отговаря, както му кажеш
class FakePayments {
  charged = [];


  constructor(approve) {
    this.approve = approve;
  }


  charge(orderId, euros) {
    this.charged.push(`${orderId} ${euros} €`);
    return this.approve;
  }
}


// Поръчките в паметта (в магазина: SqlOrders)
class InMemoryOrders {
  #rows = new Map();


  find(id) {
    return this.#rows.get(id);
  }


  save(order) {
    this.#rows.set(order.id, order);
  }
}

Сглобяването на магазина. Само тук се решава кой адаптер влиза в кой порт:

const orders = new InMemoryOrders();
orders.save({ id: "A-7", total: 120, paid: false });
orders.save({ id: "A-8", total: 40, paid: false });
const client = new CardPayClient("APPROVED", "DECLINED");
const payments = new CardPayAdapter(client);
const checkout = new Checkout(orders, payments);
for (const id of ["A-7", "A-8", "A-7"])
  console.log(`${id}: ${checkout.pay(id)}`);
Изход
  CardPay: A-7 12000 EUR → APPROVED
A-7: платена
  CardPay: A-8 4000 EUR → DECLINED
A-8: отказана
A-7: вече е платена

// Портовете: какво иска ядрото, с неговите думи
//   payments.charge(orderId, euros) връща true или false
//   orders.find(id) връща поръчката, orders.save(order)


// Ядрото: правилата, без нищо отвън
class Checkout {
  constructor(orders, payments) {
    this.orders = orders;
    this.payments = payments;
  }


  pay(id) {
    const order = this.orders.find(id);
    if (order.paid) return "вече е платена";
    const ok = this.payments.charge(id, order.total);
    if (!ok) return "отказана";
    order.paid = true;
    this.orders.save(order);
    return "платена";
  }
}
Стъпка по стъпка, с думи
  1. Ядрото е Checkout с два порта. Портовете са на ядрото и говорят с неговите думи: евро, да или не.
  2. Checkout знае само портовете. Не знае кой стои зад тях.
  3. В магазина в портовете влизат адаптери: CardPayAdapter пред доставчика и хранилището на поръчките.
  4. A-7 за 120 €: адаптерът го превежда в 12000 цента EUR, доставчикът казва APPROVED, а ядрото чува true.
  5. За теста адаптерите се сменят: двойник вместо доставчика. Ядрото е същото, без нито един променен ред.
  6. Тестът плаща A-7 два пъти: „платена“, после „вече е платена“. Двойникът е записал едно плащане. Без мрежа и без база.
  7. Стрелките сочат навътре: адаптерите зависят от портовете на ядрото, а ядрото не зависи от нищо отвън.

Ядрото казва „120 €“, а CardPay получава „12000 EUR“. Преводът е в адаптера и само там. В истинския магазин поръчките са в база: адаптерът SqlOrders е хранилището от урока Repository, а тук са в паметта, защото в урока база няма.

Виж го

Тестът без нищо отвън

Същото ядро, други адаптери: двойникът вместо CardPay. Нито мрежа, нито база, нито ключ:

const orders = new InMemoryOrders();
orders.save({ id: "A-7", total: 120, paid: false });
const payments = new FakePayments(true);
const checkout = new Checkout(orders, payments);
console.log(checkout.pay("A-7"));
console.log(checkout.pay("A-7"));
console.log("Плащания: " + payments.charged.join(", "));
Изход
платена
вече е платена
Плащания: A-7 120 €

Правилото „платена поръчка не се плаща пак“ е проверено, а двойникът показва, че доставчикът е видял само едно плащане.

Пробвай

Предвиди изхода

Двойникът сега отказва всяко плащане. Какво печата тестът?

const orders = new InMemoryOrders();
orders.save({ id: "A-8", total: 40, paid: false });
const payments = new FakePayments(false);
const checkout = new Checkout(orders, payments);
console.log(checkout.pay("A-8"));
console.log(checkout.pay("A-8"));
console.log("Плащания: " + payments.charged.join(", "));
Отговор

Идеята

Правилото за зависимостите

Посоката от слоевете тук става правило за зависимостите (dependency rule): зависимостите в кода сочат навътре, към ядрото. Адаптерът знае порта, а ядрото не знае адаптера. Кой внася кого:

  • ядрото: само себе си (Checkout, Order, портовете);
  • CardPayAdapter: порта Payments и SDK-то на CardPay;
  • FakePayments и InMemoryOrders: само портовете;
  • сглобяването в програмата: всичко, защото то решава.

Clean architecture (Robert Martin) рисува същото като кръгове: в средата правилата на бизнеса, около тях случаите на употреба (Checkout.pay), после адаптерите, а най-отвън рамките, базата и мрежата. Имената са различни, правилото е едно: стрелките сочат към средата.

Правилото не се чупи само с import. Чупи се и когато дума отвън влезе в ядрото.

Пробвай

Намери грешката

Някой е решил, че портът може да връща направо статуса на доставчика:

// Портовете: какво иска ядрото, с неговите думи
//   payments.charge(orderId, euros) връща статус
//   orders.find(id) връща поръчката, orders.save(order)
// Ядрото: правилата, без нищо отвън
class Checkout {
  constructor(orders, payments) {
    this.orders = orders;
    this.payments = payments;
  }


  pay(id) {
    const order = this.orders.find(id);
    if (order.paid) return "вече е платена";
    const status = this.payments.charge(id, order.total);
    if (status !== "APPROVED") return "отказана";
    order.paid = true;
    this.orders.save(order);
    return "платена";
  }
}

Тестът подава двойник, който одобрява:

// Двойникът на теста: одобрява
class FakePayments {
  charge(orderId, euros) {
    return "OK";
  }
}
const orders = new InMemoryOrders();
orders.save({ id: "A-7", total: 120, paid: false });
const checkout = new Checkout(orders, new FakePayments());
console.log("A-7: " + checkout.pay("A-7"));
Изход
A-7: отказана

Двойникът одобрява, а поръчката е отказана. На кой ред от ядрото е грешката?

Избери реда с грешката.

Идеята

Кога е излишно

Портовете и адаптерите струват по един интерфейс и поне два класа за всяка граница. Не си струват, когато:

  • няма правила. Услуга, която чете ред и го връща, ще има порт, адаптер и превод между едни и същи данни, без нищо за тестване;
  • портът винаги има един адаптер и тестовете не го подменят. Тогава интерфейсът е само още един файл;
  • всеки адаптер има свой обект за поръчката (OrderEntity за базата, OrderDto за HTTP) и превеждането между тях е повече код от правилата.

Струва си, когато правилата трябва да се тестват без мрежа и база, когато външното нещо се сменя (доставчик на плащания, поща, склад) или когато едно ядро се вика от няколко места: уеб, мобилно приложение, нощна задача.

По-точно, за любопитните

Името. Alistair Cockburn нарича идеята „hexagonal“ (2005), защото рисува ядрото като шестоъгълник с място за много портове. Шестте страни не значат нищо. Onion architecture (Jeffrey Palermo) и clean architecture (Robert Martin) са варианти на същото правило.

В рамките. Spring и ASP.NET Core сглобяват ядрото и адаптерите с DI контейнер: портът е интерфейс, а контейнерът подава адаптера. В Python (FastAPI, Django) и Node (Express, Nest) сглобяването често е на ръка в началото на програмата, както в урока. Тестовете в истински проект ползват и библиотеки за двойници: Mockito, Moq, unittest.mock, node:test mock. Ръчният двойник от урока често е по-ясен.

Колко е „отвън“. Часовникът и случайността също са отвън. Правило „поръчката изтича след 30 минути“ не се тества, ако ядрото само пита системния часовник. Порт Clock с двойник, който казва „сега е 10:30“, го прави.

Без типове. В JavaScript правилото за зависимостите се пази с инструменти, които гледат import-ите (dependency-cruiser), а портовете се описват с JSDoc или с TypeScript интерфейс.

Упражнение

Втори доставчик

Реши задачата в редактора си.

Магазинът добавя втория доставчик PayLater. Неговото SDK иска сумата като текст („120.00 EUR“) и отговаря с да или не:

// SDK-то на втория доставчик: сума като текст, отговор да или не
class PayLaterClient {
  #answers;


  constructor(...answers) {
    this.#answers = answers;
  }


  submit(reference, amount) {
    const ok = this.#answers.shift();
    console.log(`  PayLater: ${reference} ${amount} → ${ok ? "ok" : "declined"}`);
    return ok;
  }
}

Напиши адаптер PayLaterAdapter за порта payments и го подай на същото ядро. Checkout не трябва да се променя. Плати A-7 (PayLater казва да) и A-8 (PayLater казва не):

Изход
  PayLater: A-7 120.00 EUR → ok
A-7: платена
  PayLater: A-8 40.00 EUR → declined
A-8: отказана

Още задачи

  • Известия. Добави порт Notifier с метод за известие „Поръчка A-7 е платена“. Адаптер за конзолата и двойник, който записва известията. Провери, че отказаната поръчка не праща известие.
  • Часовникът. Платената поръчка може да се върне до 14 дни. Добави порт за часовника и тест с двойник, който казва „днес е 15-ият ден“.

Тест

Провери се

1. Чий е портът Payments?
2. Магазинът сменя доставчика на плащания. Кой код се пише наново?
3. В ядрото пише if (status.equals("APPROVED")). Какво е нарушено?
4. Кое е водещ адаптер (driving), а не воден (driven)?
5. Услуга има един ендпойнт, който чете ред от базата и го връща, без правила. Струва ли си порт и адаптер?

Създаден от Иво Гергов като част от кампанията на Evo Tech за достъпно обучение по програмиране ·