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

Интеграция със стари и чужди системи

Накратко: Anti-corruption layer превежда модела на стара или чужда система към твоя домейн, а шина с канонична форма свежда връзките между n системи до по един адаптер на система.

Проблем

Склад от 2009 г. и счетоводство на XML

Магазинът има стар склад: програма от 2009 г., която никой не смее да пипа. Тя говори CSV, с ; и кодове: A е налично, B е блокирано, а количество -1 значи „броим в момента“. Счетоводството иска XML със сумата с точка. Доставката иска JSON.

Ето как поръчките казват на трите:

class Orders(Endpoint warehouse, Endpoint accounting,
             Endpoint delivery)
{
    public void Place(int id, string sku, int qty,
                      long cents)
    {
        // складът от 2009: CSV и код OUT
        warehouse.Send($"{id};{sku};{qty};OUT");
        // счетоводството: XML, сумата с точка
        var total = Euros(cents);
        accounting.Send(
            $"""<invoice no="{id}" total="{total}"/>""");
        // доставката: JSON
        var json = $$"""{"order":{{id}},"sku":"{{sku}}"}""";
        delivery.Send(json);
    }
}
var orders = new Orders(new Endpoint("склад"),
    new Endpoint("счетоводство"), new Endpoint("доставка"));
orders.Place(1042, "HP-01", 1, 5900);
Изход
склад ← 1042;HP-01;1;OUT
счетоводство ← <invoice no="1042" total="59.00"/>
доставка ← {"order":1042,"sku":"HP-01"}

Работи. Но поръчките вече знаят три чужди формата, а кодовете на склада са плъзнали и в касата: някъде пише if (status == "B"). Каталогът също говори със склада, търговците със счетоводството. Когато складът добави нов статус, никой не знае на колко места да търси.

Идеята

Преводач на границата

Чуждата система има свой модел: свои кодове, свои мерни единици, свои странни стойности. Ако той влезе в домейна, домейнът започва да мисли на езика на склада от 2009 г. и се сменя всеки път, когато складът се смени.

Затова на границата стои преводач. Той чете чуждия формат и пуска навътре само понятията на домейна: Stock(sku, available). Какво значат A, B и -1, знае само той. Това се казва anti-corruption layer (слой срещу заразата).

Отвътре това е адаптер, но с по-голяма задача: адаптерът сменя формата на един интерфейс, а anti-corruption layer пази цял модел да не изтече. Той решава какво значи всяка чужда стойност и какво прави с непознатото. Правилото: непознатото се отказва на глас, не се познава.

Виж го

Преводачът в код

record Stock(string Sku, int Available);


// границата: само тук се знае какво значат A, B и -1
class WarehouseAcl
{
    public List<string> Rejected { get; } = [];


    public List<Stock> Read(IEnumerable<string> lines)
    {
        var stock = new List<Stock>();
        foreach (var line in lines)
        {
            var f = line.Split(';');
            var sku = f[0];
            var qty = int.Parse(f[1]);
            switch (f[2])
            {
                case "A" when qty >= 0:
                    stock.Add(new Stock(sku, qty));
                    break;
                case "A":
                    Rejected.Add($"{sku}: неизвестно количество");
                    break;
                case "B":
                    stock.Add(new Stock(sku, 0));
                    break;
                default:
                    Rejected.Add($"{sku}: непознат статус {f[2]}");
                    break;
            }
        }
        return stock;
    }
}
case "A" when qty >= 0 е случай с условие: "A" с отрицателно количество отива в следващия случай.

Файлът от тази сутрин:

// файлът, който старият склад качва по FTP всеки час
string[] file = ["HP-01;3;A", "CH-07;0;A", "KB-12;5;B", "MS-03;-1;A", "SP-02;2;R"];
var acl = new WarehouseAcl();
foreach (var s in acl.Read(file))
    Console.WriteLine($"{s.Sku}: {s.Available}");
foreach (var r in acl.Rejected)
    Console.WriteLine($"✗ {r}");
Изход
HP-01: 3
CH-07: 0
KB-12: 0
✗ MS-03: неизвестно количество
✗ SP-02: непознат статус R

KB-12 е блокиран, затова за домейна е 0 налични. MS-03 се брои в момента: преводачът не знае колко е и не измисля число. SP-02 е със статус R, който никой не е описал. Отказан е и някой ще попита собственика на склада какво значи.

Пробвай

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

Колега пише по-кратък преводач: „всичко, което не е блокирано, е за продан“. Месец по-късно складът пуска статус R (запазено за външен търговец) и магазинът продава една и съща колонка на двама купувачи. Освен това MS-03 се появява на сайта с -1 бройки. На кой ред е грешката?

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

Идеята

Паяжината от връзки

Шест системи: поръчки, каталог, склад, счетоводство, доставка и външни търговци. Ако всяка говори с всяка, връзките са n(n-1)/2 = 15, и всяка има свой превод. Смяна на формата на склада пипа 5 от тях, в 5 системи, които трябва да се пуснат заедно.

Другият начин е шина с канонична форма: една обща форма на съобщението (OrderPlaced), която всички разбират. Всяка система се свързва веднъж, с адаптер между своя формат и каноничния. Шест системи, шест адаптера. Смяната на формата на склада пипа само неговия адаптер: той е anti-corruption layer-ът на склада.

record OrderPlaced(int Id, string Sku, int Qty,
                  long Cents);


delegate string Adapter(OrderPlaced e);


class Hub
{
    readonly Dictionary<Endpoint, Adapter> adapters = [];


    public void Connect(Endpoint system, Adapter adapter) =>
        adapters[system] = adapter;


    public void Publish(OrderPlaced e)
    {
        foreach (var (system, adapter) in adapters)
            system.Send(adapter(e));
    }


    public int Size => adapters.Count;
}
Стъпка по стъпка, с думи
  1. Поръчките пращат на три системи, всяка на нейния език: CSV на склада от 2009 г., XML на счетоводството, JSON на доставката. Поръчките знаят и трите формата.
  2. Така говорят и другите: каталогът със склада, търговците със счетоводството. 6 системи, които си говорят всяка с всяка, са 15 връзки, всяка със свой превод.
  3. Складът сменя формата си. Сменя се всяка връзка към него: 5 места в 5 системи, пуснати заедно.
  4. Шина: всяка система се свързва веднъж, с адаптер между своя формат и една канонична форма. 6 системи, 6 адаптера.
  5. Поръчките публикуват OrderPlaced веднъж и не знаят нито CSV, нито XML. Шината дава на всяка система нейния превод.
  6. Складът пак сменя формата: сменя се само неговият адаптер. Той пази стария модел извън домейна: anti-corruption layer.
  7. Точка-до-точка: 15 връзки, 5 промени при нов формат. Шина: 6 адаптера, 1 промяна. Цената: шината е още една система, която не бива да пада.

Виж го

Шината в код

Адаптерът е делегат: всяка ламбда с OrderPlaced на входа и текст на изхода става. Поръчките публикуват веднъж, а адаптерите са до всяка система:

var hub = new Hub();
hub.Connect(new Endpoint("склад"),
    e => $"{e.Id};{e.Sku};{e.Qty};OUT");
hub.Connect(new Endpoint("счетоводство"),
    e => $"""<invoice no="{e.Id}" total="{Euros(e.Cents)}"/>""");
hub.Connect(new Endpoint("доставка"),
    e => $$"""{"order":{{e.Id}},"sku":"{{e.Sku}}"}""");
// поръчките публикуват веднъж, в каноничната форма
hub.Publish(new OrderPlaced(1042, "HP-01", 1, 5900));
Console.WriteLine($"адаптери: {hub.Size}");
Изход
склад ← 1042;HP-01;1;OUT
счетоводство ← <invoice no="1042" total="59.00"/>
доставка ← {"order":1042,"sku":"HP-01"}
адаптери: 3

Съобщенията са същите като в началото. Разликата е кой знае формата: поръчките вече не знаят CSV и XML, а за нова система се добавя един connect, без да се пипат поръчките. Euros прави центовете на текст с точка: 5900 става 59.00.

Пробвай

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

foreach (var n in new[] { 3, 6, 10 })
{
    var links = n * (n - 1) / 2;
    Console.WriteLine($"{n} системи: {links} връзки или {n} адаптера");
}
Отговор

Идеята

Синхронно или асинхронно, и договорът

Не всяка връзка е еднаква:

Синхронно (заявка и отговор) Асинхронно (опашка, файл)
Кога отговорът трябва сега: „има ли стока?“ преди продажбата може да почака: фактурите до сутринта, файлът на склада всеки час
Ако другата страна е бавна чакаш и ти, затова timeout и retry съобщението чака в опашката
Ако другата страна е паднала отказваш или имаш резервен отговор наваксва, когато се върне

Каноничната форма е договор: всички зависят от нея. Сменя се като договора на API: ново поле се добавя, без да чупи старите адаптери, а махането на поле е нова версия. Ако в договора влезе стока за склада и поле само за счетоводството, той става на всички и не е на никого.

Идеята

Кога шината вреди

  • При две-три системи. Шината е още една система: пуска се, наблюдава се и пада. При малко връзки една права връзка с преводач е по-евтина.
  • Когато в нея влезе логика. Шина, която решава отстъпки или маршрути по бизнес правила, става място, което никой екип не притежава, а всички чакат. Шината пренася и превежда, правилата остават в системите.
  • Когато каноничната форма иска всичко. Модел, който описва поръчката за всички системи наведнъж, се договаря месеци и после никой не смее да го пипа. По-добре са няколко малки съобщения (OrderPlaced, StockChanged), всяко с ясен собственик.
  • Anti-corruption layer не винаги трябва. Ако чуждият модел е добър и стабилен (например договорът на доставчика на плащания) или ако е модул на твоя екип, преводачът е само още един слой за поддръжка.
По-точно, за любопитните

Истинските шини и брокери: Apache Kafka, RabbitMQ, облачните опашки (Amazon SQS, Azure Service Bus); за интеграция: Apache Camel, Spring Integration, MuleSoft, Kafka Connect. По-старото име е ESB (enterprise service bus). Лошата му слава е от шините, в които е влязла цялата бизнес логика.

Шаблоните имат имена. Книгата „Enterprise Integration Patterns“ (Gregor Hohpe и Bobby Woolf, 2003) описва преводача (message translator), каноничния модел на данните, маршрутизатора и още десетки. Anti-corruption layer е понятие от „Domain-Driven Design“ на Eric Evans (2003).

Стари системи на практика: преводачът пази и оригиналния файл, за да може редът да се пусне наново, след като се изясни какво значи R. Файл по FTP се чете чак когато е качен целият (например по празен файл .done до него). Самите FTP сървъри, брокерите и мрежата между тях са инфраструктура и се учат в курса по DevOps ZeroToOps.

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

Упражнение

Върнатите стоки

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

Старият склад качва и втори файл: върнатите стоки. Редът е RET;поръчка;артикул;брой;дата, а датата е dd.MM.yyyy. Във файла понякога има и редове от инвентаризацията (INV;…), които не са връщания. Напиши преводач, който дава на домейна връщания с дата във формат ISO (2026-10-15) и отказва на глас всеки ред, който не е връщане.

Входът е RET;1042;HP-01;1;15.10.2026, RET;1043;CH-07;2;16.10.2026 и INV;HP-01;3.

Изход
връщане 1042: HP-01 × 1 на 2026-10-15
връщане 1043: CH-07 × 2 на 2026-10-16
✗ не е връщане: INV;HP-01;3

Още задачи

  • Външните търговци. Свържи към шината и търговците: те искат ред ORDER 1042 HP-01. Колко реда в поръчките се сменят?
  • Счетоводството отговаря. Счетоводството връща XML <paid no="1042" cents="5900"/>. Напиши преводача навътре: домейнът иска плащане в евро.

Тест

Провери се

1. Какво прави anti-corruption layer?
2. Старият склад праща ред със статус, който преводачът не познава. Какво е правилно?
3. Осем системи си говорят всяка с всяка. Колко връзки са, и колко адаптера иска шина с канонична форма?
4. Касата трябва да знае дали има стока, преди да приеме поръчката. Счетоводството иска фактурите до сутринта. Как ги свързваш?
5. Кога шината е излишна?

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