Hexagonal и clean architecture

Код на:JavaC#PythonJavaScript

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

Проблем

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

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

class Checkout:
    def __init__(self):
        self.orders = SqlOrders("db.shop.local")
        self.provider = CardPayClient()

    def pay(self, order_id):
        order = self.orders.find(order_id)
        if order.paid:
            return "вече е платена"
        response = self.provider.charge(order.total * 100, "EUR", order_id)
        if response["status"] != "APPROVED":
            return "отказана"
        order.paid = True
        self.orders.save(order)
        return "платена"

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

# Истинските класове отвън. Тук няма нито база, нито мрежа.
class SqlOrders:
    def __init__(self, host):
        raise ConnectionError("няма връзка с " + host)

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

try:
    checkout = Checkout()
    print(checkout.pay("A-7"))
except ConnectionError as e:
    print("Тестът пада: " + str(e))

Изход

Тестът пада: няма връзка с 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 или центове:

# Портовете: какво иска ядрото, с неговите думи
class Payments(Protocol):
    def charge(self, order_id: str, euros: int) -> bool: ...


class Orders(Protocol):
    def find(self, order_id: str) -> "Order": ...

    def save(self, order: "Order") -> None: ...


@dataclass
class Order:
    id: str
    total: int
    paid: bool = False


# Ядрото: правилата, без нищо отвън
class Checkout:
    def __init__(self, orders: Orders, payments: Payments):
        self.orders = orders
        self.payments = payments

    def pay(self, order_id):
        order = self.orders.find(order_id)
        if order.paid:
            return "вече е платена"
        if not self.payments.charge(order_id, order.total):
            return "отказана"
        order.paid = True
        self.orders.save(order)
        return "платена"

В Python портът е Protocol: адаптерите не го наследяват, стига им да имат същите методи. Проверка на типовете (mypy) хваща адаптер без charge, преди програмата да тръгне.

Виж го

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

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

# SDK-то на доставчика. Тук мрежата е заменена
# със записани отговори.
class CardPayClient:
    def __init__(self, *answers):
        self.answers = list(answers)

    def charge(self, cents, currency, reference):
        status = self.answers.pop(0)
        print(f"  CardPay: {reference} {cents} {currency} → {status}")
        return {"status": status}

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

# Адаптерът превежда думите на ядрото към доставчика
class CardPayAdapter:
    def __init__(self, client):
        self.client = client

    def charge(self, order_id, euros):
        response = self.client.charge(euros * 100, "EUR", order_id)
        return response["status"] == "APPROVED"


# Двойникът за теста: записва и отговаря, както му кажеш
class FakePayments:
    def __init__(self, approve):
        self.approve = approve
        self.charged = []

    def charge(self, order_id, euros):
        self.charged.append(f"{order_id} {euros} €")
        return self.approve


# Поръчките в паметта (в магазина: SqlOrders)
class InMemoryOrders:
    def __init__(self):
        self.rows = {}

    def find(self, order_id):
        return self.rows[order_id]

    def save(self, order):
        self.rows[order.id] = order

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

orders = InMemoryOrders()
orders.save(Order("A-7", 120))
orders.save(Order("A-8", 40))
client = CardPayClient("APPROVED", "DECLINED")
payments = CardPayAdapter(client)
checkout = Checkout(orders, payments)
for order_id in ["A-7", "A-8", "A-7"]:
    print(f"{order_id}: {checkout.pay(order_id)}")

Изход

  CardPay: A-7 12000 EUR → APPROVED
A-7: платена
  CardPay: A-8 4000 EUR → DECLINED
A-8: отказана
A-7: вече е платена

# Портовете: какво иска ядрото, с неговите думи
class Payments(Protocol):
    def charge(self, order_id: str, euros: int) -> bool: ...


class Orders(Protocol):
    def find(self, order_id: str) -> "Order": ...

    def save(self, order: "Order") -> None: ...


@dataclass
class Order:
    id: str
    total: int
    paid: bool = False


# Ядрото: правилата, без нищо отвън
class Checkout:
    def __init__(self, orders: Orders, payments: Payments):
        self.orders = orders
        self.payments = payments

    def pay(self, order_id):
        order = self.orders.find(order_id)
        if order.paid:
            return "вече е платена"
        if not self.payments.charge(order_id, order.total):
            return "отказана"
        order.paid = True
        self.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. Нито мрежа, нито база, нито ключ:

orders = InMemoryOrders()
orders.save(Order("A-7", 120))
payments = FakePayments(True)
checkout = Checkout(orders, payments)
print(checkout.pay("A-7"))
print(checkout.pay("A-7"))
print("Плащания: " + ", ".join(payments.charged))

Изход

платена
вече е платена
Плащания: A-7 120 €

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

Пробвай

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

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

orders = InMemoryOrders()
orders.save(Order("A-8", 40))
payments = FakePayments(False)
checkout = Checkout(orders, payments)
print(checkout.pay("A-8"))
print(checkout.pay("A-8"))
print("Плащания: " + ", ".join(payments.charged))

Отговор

отказана
отказана
Плащания: A-8 40 €, A-8 40 €

отказана
отказана
Плащания: 

отказана
вече е платена
Плащания: A-8 40 €

Провери

Идеята

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

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

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

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

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

Пробвай

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

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

# Портовете: какво иска ядрото, с неговите думи
class Payments(Protocol):
    def charge(self, order_id: str, euros: int) -> str: ...


class Orders(Protocol):
    def find(self, order_id: str) -> "Order": ...

    def save(self, order: "Order") -> None: ...

# Ядрото: правилата, без нищо отвън
class Checkout:
    def __init__(self, orders: Orders, payments: Payments):
        self.orders = orders
        self.payments = payments

    def pay(self, order_id):
        order = self.orders.find(order_id)
        if order.paid:
            return "вече е платена"
        status = self.payments.charge(order_id, order.total)
        if status != "APPROVED":
            return "отказана"
        order.paid = True
        self.orders.save(order)
        return "платена"

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

# Двойникът на теста: одобрява
class FakePayments:
    def charge(self, order_id, euros):
        return "OK"

orders = InMemoryOrders()
orders.save(Order("A-7", 120))
checkout = Checkout(orders, FakePayments())
print("A-7: " + checkout.pay("A-7"))

Изход

A-7: отказана

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

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

1# Ядрото: правилата, без нищо отвън2class Checkout:3 def __init__(self, orders: Orders, payments: Payments):4 self.orders = orders5 self.payments = payments67 def pay(self, order_id):8 order = self.orders.find(order_id)9 if order.paid:10 return "вече е платена"11 status = self.payments.charge(order_id, order.total)12 if status != "APPROVED":13 return "отказана"14 order.paid = True15 self.orders.save(order)16 return "платена"

Провери

Идеята

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

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

• няма правила. Услуга, която чете ред и го връща, ще има порт, адаптер и превод между едни и същи данни, без нищо за тестване;
• портът винаги има един адаптер и тестовете не го подменят. Тогава интерфейсът е само още един файл;
• всеки адаптер има свой обект за поръчката (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“, го прави.

Упражнение

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

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

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

# SDK-то на втория доставчик: сума като текст, отговор да или не
class PayLaterClient:
    def __init__(self, *answers):
        self.answers = list(answers)

    def submit(self, reference, amount):
        ok = self.answers.pop(0)
        print(f"  PayLater: {reference} {amount} → {'ok' if ok else '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?

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

2. Магазинът сменя доставчика на плащания. Кой код се пише наново?

Само адаптерът към новия доставчикЯдрото и всичките му тестовеХранилището на поръчките

3. В ядрото пише if (status.equals("APPROVED")). Какво е нарушено?

Нищо: това е просто сравнение на текстПравилото на слоевете: ядрото вика надолуПравилото за зависимостите: думата на доставчика е влязла в ядрото

4. Кое е водещ адаптер (driving), а не воден (driven)?

Тестът или контролерът, който вика Checkout.payCardPayAdapterInMemoryOrders

5. Услуга има един ендпойнт, който чете ред от базата и го връща, без правила. Струва ли си порт и адаптер?

Обикновено не: портът и адаптерът ще са само препращанеДа, винагиДа, ако има поне една таблица

Провери

Започни урока отначало

Свързани уроци

• Нужно отпреди: Adapter и Facade · Repository · SOLID без догма · Слоеве
• Продължава в: Монолит, модулен монолит, услуги · ADR: записани архитектурни решения · Архитектурен преглед
• Задачи по темата: Софтуерни архитектури