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

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

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

Проблем

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

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

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

class Orders {
  constructor(warehouse, accounting, delivery) {
    this.warehouse = warehouse;
    this.accounting = accounting;
    this.delivery = delivery;
  }


  place(id, sku, qty, cents) {
    // складът от 2009: CSV и код OUT
    this.warehouse.send(`${id};${sku};${qty};OUT`);
    // счетоводството: XML, сумата с точка
    const total = euros(cents);
    this.accounting.send(
      `<invoice no="${id}" total="${total}"/>`);
    // доставката: JSON
    const json = JSON.stringify({ order: id, sku });
    this.delivery.send(json);
  }
}
const 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 пази цял модел да не изтече. Той решава какво значи всяка чужда стойност и какво прави с непознатото. Правилото: непознатото се отказва на глас, не се познава.

Виж го

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

// границата: само тук се знае какво значат A, B и -1
class WarehouseAcl {
  rejected = [];


  read(lines) {
    const stock = [];
    for (const line of lines) {
      const [sku, text, status] = line.split(";");
      const qty = Number(text);
      if (status === "A" && qty >= 0) stock.push({ sku, available: qty });
      else if (status === "A") this.rejected.push(sku + ": неизвестно количество");
      else if (status === "B") stock.push({ sku, available: 0 });
      else this.rejected.push(sku + ": непознат статус " + status);
    }
    return stock;
  }
}
В JavaScript няма записи: Stock е обикновен обект { sku, available }.

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

// файлът, който старият склад качва по FTP всеки час
const file = ["HP-01;3;A", "CH-07;0;A", "KB-12;5;B", "MS-03;-1;A", "SP-02;2;R"];
const acl = new WarehouseAcl();
for (const s of acl.read(file)) console.log(s.sku + ": " + s.available);
for (const r of acl.rejected) console.log("✗ " + 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-ът на склада.

class Hub {
  adapters = new Map();


  connect(system, adapter) {
    this.adapters.set(system, adapter);
  }


  publish(event) {
    for (const [system, adapter] of this.adapters)
      system.send(adapter(event));
  }


  get size() {
    return this.adapters.size;
  }
}
Стъпка по стъпка, с думи
  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 е обикновен обект: в JavaScript няма интерфейси и записи. Поръчките публикуват веднъж, а адаптерите са до всяка система:

const 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) => JSON.stringify({ order: e.id, sku: e.sku }));
// поръчките публикуват веднъж, в каноничната форма
hub.publish({ id: 1042, sku: "HP-01", qty: 1, cents: 5900 });
console.log("адаптери: " + 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.

Пробвай

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

for (const n of [3, 6, 10]) {
  const links = (n * (n - 1)) / 2;
  console.log(`${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 за достъпно обучение по програмиране ·