Привет, Хабр! На связи Давид Саргсян. Я занимаюсь системным анализом цифровых продуктов банка ПСБ.

В этой статье расскажу, как не упустить ничего важного на этапах выбора концепции и проектирования вашей будущей интеграции.

Когда интеграция неизбежна

Если вашей информационной системе необходимо собирать какие-либо данные, то есть два пути:

1. Собирать данные самостоятельно;

2. Найти другую информационную систему, которая уже собирает эти данные, и получать их от неё.

Создавать информационную систему долго, дорого и сложно. И если:

• данные, которые мы собираем, для нас не являются профильными, а лишь дополняют нашу систему;

• у нас недостаточно компетенций и возможностей для самостоятельного сбора данных;

• уже существует информационная система, которая делает это на нужном уровне...

То для экономии времени, средств и сил есть смысл выбрать интеграцию с уже существующей информационной системой.

Реализация интеграции между разными системами — это частая задача для ИТ-команд, и именно аналитикам предстоит её проектировать: либо для микросервисов в рамках одной системы, либо для получения данных из сторонних систем.

Интеграции могут использоваться ещё и для того, чтобы воспользоваться функциями, которых нет в нашей системе, или запуска какого-либо процесса. Например, для валидации каких-либо данных в ИС уполномоченной организации.

Также интеграции могут происходить между фронтом и бэком.

Чтобы интеграция прошла успешно, а процесс проектирования был проще и качественнее, я, главный системный аналитик в банке ПСБ, собрал в одной статье чек-лист с основными вопросами, которые нужно задавать себе (и команде) для описания работы системы. И, конечно же, добавил примеры ответов — они помогут собрать полные требования и создать спецификацию к вашей будущей интеграции.

Паспорт интеграции

1. Концепция

1.1. Зачем мы интегрируемся

Я буду разбирать часть пунктов на примере информационной системы (ИС) для отслеживания грузоперевозок.

Необходимо сделать так, чтобы в информационной системе-агрегаторе «Отслеживание грузоперевозок» появились данные о железнодорожных перевозках. Зачем? Во-первых, так грузополучатели будут получать информацию о дате поставки своих товаров и подготовятся к их получению. Это лояльность старых пользователей. Во-вторых, новые возможности ИС привлекут больше клиентов. В итоге эта интеграция просто и прозрачно решает вопросы бизнеса.

1.2. Системы-участники интеграционного взаимодействия 

Названия систем и их роли

Почему именно эта мастер-система?

Во-первых, она собирает все необходимые нам данные по ж/д грузоперевозке. Во-вторых, эта система собирает информацию о движении поездов между всеми ж/д-станциями России. И, в-третьих, «Железные дороги России» готовы интегрироваться с другими системами и делиться данными.

Дальше я объясню, какие именно данные нам нужны. 

Но сперва — пара слов о ролях в командах и ответственности.

R («Responsible») — исполнитель, непосредственно работающий над процессом;
A («Accountable») — куратор, ответственный за конечный результат в указанном процессе;
C («Consult») — консультант, являющийся держателем экспертизы;
I («Informed») — оповещаемый, не участвующий непосредственно в процессе, но который заинтересован в получении информации о его статусе.

1.3. Какие данные нам нужны 

Итак, допустим, в нашей системе есть номер маршрутного листа. Но его маловато для того, чтобы пользователь понял, где груз едет и когда прибудет. Нужно больше данных. 

Например, вот таких:
1. Номер перевозки; 
2. Ожидаемая дата отправки; 
3. Фактическая дата отправки; 
4. Ожидаемая дата прибытия; 
5. Фактическая дата прибытия; 
6. Последняя ж/д-станция, которую проехал поезд; 
7. Статус грузоперевозки.

Их мы называем «входные данные», т. е. сведения, которые система должна получать извне (от мастер-системы) в ходе интеграции.

Но чтобы мы могли получить все эти сведения, мастер-система должна определить, какой экземпляр сущности нас интересует. Вот тут и пригодится номер маршрутного листа. Его наша система-потребитель данных отправит вовне как «выходные данные». 

Мы определились с системами для интеграции и с интересующими данными. Следующий вопрос уже в том, как мы будем интегрироваться.

1.4. Интеграционный стиль и технология: протокол взаимодействия, архитектурный паттерн интеграции

Вопросы, с которых необходимо начать

1. Каким образом система источник данных готова передавать данные? Есть ли интеграционная документация/контракт?

2. Каким будет тип взаимодействия?

Скрытый текст

Ретрай (retry) – повторное обращение к системе-источнику данных при отсутствии от неё ответа при первом обращении.

Коллбэк (callback) — функция, которая вызывается после завершения какого-либо действия. Для программы, запустившей запрос или долгое вычисление, коллбэк — это способ сообщить, что надлежит сделать, когда вычисление завершится.

Фолбэк (fallback) — запасной вариант, дополнительная реализация на случай неполадок, недоступности основной функции.

Алгоритмы выбора технологии интеграции

Полную информацию по технологиям интеграций можно найти в файле: https://clck.ru/3JhtpS 

1.5. Нефункциональные требования к системам

Собрать нефункциональные требования важно командам обеих систем. Например, создателям системы-источника важно понимать, как часто система-потребитель будет обращаться к их системе за данными. А команда системы-потребителя, например, должна решить, как долго их система готова ждать информацию от мастер-системы.

Это также может влиять на выбор технологии интеграции.

*Троттлинг – пропускная способность: сколько запросов может обрабатывать система в один момент.
**Используется аббревиатура RPS (Requests Per Second) — количество запросов за одну секунду.
Если сервис высоконагруженный, можно создать параллельные потоки, что увеличит пропускные возможности системы: этот инструмент называется «балансировка».

2. Проектирование

Если интеграция подразумевает хранение информации в базе данных системы-
 потребителя, то важно учесть следующее:

1. Когда сущности в системе-потребителе проектируются с нуля, следует создать правила единообразного нейминга сущностей и их атрибутов.

2. Когда сущности и атрибуты уже созданы, необходимо спроектировать маппинг данных — об этом я расскажу чуть позже.

2.1. Как будем хранить сведения в базе данных 

Объектная модель

*Согласно ISO 8601

При проектировании сущностей необходимо придерживаться форм нормализации баз данных — так мы обеспечиваем её неизбыточность. В частности, можно дойти до 3-й нормальной формы.

 1-я нормальная форма:

• В таблице нет повторяющихся строк;

• Все атрибуты таблицы простые, а не указаны в виде списка;

• Все значения скалярны: в них хранится только одно значение.

2-я нормальная форма:

• Все требования к 1-й нормальной форме выполнены;

• У атрибутов таблицы должен быть уникальный ключ*;

• Все атрибуты должны описывать первичный ключ целиком, а не какую-то его часть.
  Так, например, не должно быть соединено в одну таблицу несколько таблиц.

Например, у нас есть таблица «Продукты». В ней не могут находиться атрибуты, описывающие сущность «Ингредиенты», ведь на самом деле это должны быть две отдельные таблицы. И будет третья таблица, промежуточная, «Продукты_ингредиенты». В ней будут отображаться первичные ключи обеих таблиц (в ней они уже называются внешними). Это нужно для реализации в БД связи типа «Многое ко многим», так как один продукт может состоять из множества ингредиентов, и один из них может использоваться во множестве продуктов.

 3-я нормальная форма:

• Все требования ко 2-й нормальной форме выполнены;

• Не должно быть зависимостей одних неключевых атрибутов от других. Все атрибуты зависят только от первичного ключа.

Ключи:

• Первичный ключ — это id строки в самой таблице.

• Внешний ключ — это отсылка на id строки в какой-либо другой таблице.

Если первичный ключ состоит из единственного атрибута, его называют простым ключом.
Если первичный ключ состоит из двух и более атрибутов, его называют составным ключом.

• Естественный ключ — это, например, ИНН, который является индивидуальным для каждого гражданина.

• Добавленный системой ключ — это id, присвоенный системой.

2.2. Как данные от системы-отправителя соотносятся с данными в нашей базе данных

Маппинг данных

На этапе маппинга данных, когда мы определим, как соотносятся данные из таблиц и атрибутов системы-источника с данными в системе-потребителе, можем столкнуться со следующими проблемами:

1. Не все данные, которые нам нужны, есть в системе-источнике. А значит необходимо заполнить пустующие атрибуты либо самостоятельно, либо с помощью другой системы-источника.

В нашем примере нет данных для заполнения атрибута «Ожидаемая дата прибытия» Expected_date_of_arrival

Так как этот атрибут для нас необязательный, можем его не заполнять сейчас. Либо же можно рассчитать эту дату: среднюю скорость поезда умножить на расстояние, которое поезд должен проделать из пункта отправления в пункт назначения. 

2. Формат данных системы-источника отличается от того, что используется в системе-потребителе.
В нашем примере формат данных для заполнения атрибута «Статус доставки» delivery_status в системе-потребителе является VARCHAR. Для него ожидаются варианты «Планируется; В пути; Прибыл». В системе-источнике же отдаются данные из атрибута state в формате INT в вариантах 0,1,2,3.

Для решения этого несоответствия нужно составить алгоритм преобразования данных. Его мы будем использовать перед записью данных в систему-потребитель.

Алгоритм преобразования данных 

3. Какой-либо вариант из перечислений не предусмотрен в системе-потребителе.
Это частая проблема на данном этапе. В таком случае можем либо скорректировать перечисление в таблице «Статус доставки» Delivery_status и добавить в него новое значение, либо игнорировать его как неинтересное для пользователей системы-потребителя.

Скрытый текст

Также может возникать потребность сохранить данные из нескольких отдельных атрибутов. Например, системе-потребителю необходимо получить данные по ФИО машиниста поезда в качестве одного атрибута, а в системе-источнике данные указаны в трех отдельных атрибутах: «Фамилия», «Имя» и «Отчество».  В таком случае нужно составить алгоритм по «склеиванию» (конкатенации) данных из трёх атрибутов в один. И заодно можно учесть возможность отсутствия данных (например, отчества), а также использования двойных имён или фамилий, различных приставок и дополнительных слов к отчеству.

Валидация данных

 В примерах работы с данными, которые мы не ожидаем, я указывал решения:

а) частичной передачи данных — после этого атрибуты, по которым не хватило данных, остаются пустующими, пока не будут заполнены самостоятельно или при последующей интеграции с системой-источником.
б) только полной передачи данных — если каких-либо данных не хватает, мы считаем все данные по грузоперевозке недостоверными и не сохраняем их.

Необходимо выработать стратегию валидации ошибок для каждого атрибута в зависимости от его важности для пользователей нашей системы. И понять, в каких случаях команды должны искать решения при получении «неожиданных» данных от системы-источника, от чего будет зависеть система настройки уведомлений о таких событиях.

Также стоит установить правила качества данных (data quality rules). Примеры таких правил:

• Все получаемые данные необходимо проверять на уникальность первичного ключа по сравнению с теми данными, что уже у нас есть в базе данных.

• Поля, по которым должны прийти Null, приходят не пустыми, так как Null и пустота — это разные значения.

• Сравнение объёма таблиц: после добавления/удаления строк в таблице помогает определить, что эти изменения произошли.

• Сравнение хэша строк: помогает при определении полных дублей.

Необходимость сохранения данных в системе-источнике

Важно уточнить, нужна ли системе-источнику информация по id сущности «Грузоперевозка», которая была создана в системе-потребителе на основании данных от системы-источника. Если ответ «да», нужно реализовать решение по передаче им этого идентификатора.

2.3. Как выглядит взаимодействие между системами  

Составим схему передачи данных, чтобы наглядно увидеть, как системы будут взаимодействовать между собой:

Дополнительно можно составить диаграмму потоков данных и диаграмму последовательности.

3. Техническая спецификация

В этой части рассмотрим вопросы, которые стоит задать себе для сбора требований к той или иной технологии интеграции. За рамками этой статьи останется то, как реализовать то или иное требование. Но ответы, которые вы будете давать на задаваемые вопросы, должны быть также подробно расписаны. Так разработчик поймёт, как именно можно реализовать тот или иной аспект интеграции наилучшим образом. 

Общие вопросы для всех нижеуказанных технологий интеграций:

• Каким будет способ аутентификации и авторизации в системе-источнике, чтобы она смогла передавать данные системе-потребителю?

• Будут ли шифроваться передаваемые данные?

• Какими будут firewall-доступы и сертификаты?

• Будем ли использовать кэширование, чтобы сохранять нединамические меняющиеся данные на клиенте пользователя и снизить количество запросов/передачи информации?

• Каким образом планируется обрабатывать ошибки при получении данных?

• Будут ли, с какой периодичностью и как долго повторно отправляться запросы при не-ответе системы-источника? Их принято называть «ретраями» (Retry) и о всех таких случаях вести запись в логе.

3.1. Файловый обмен 

1. Папка и файл

• Каким должен быть путь до папки с файлами для обмена?

• Какими будут настройки подключения к серверу?

• Какой будет формат файла? В том числе необходимо учесть отличия между .xls и .xslx.

• Какой будет маска названия для папки и файлов, чтобы при сопоставлении с ней система понимала, откуда брать данные?

Например: если составляем маску названия файла с датой и временем, то в требованиях прописываем маску полностью: ДД.ММ.ГГГГ и ЧЧ:ММ:СС в 24-часовом формате.

2. Ответственность за доступы  

Чьими силами будет настроен доступ:
а) заказчика;
б) исполнителя.

3. Протокол взаимодействия

Каким будет протокол взаимодействия?

1. Обычный открытый FTP-протокол;
2. Защищённые протоколы:
2.1. FTPS (FTP через защищённый криптографический протокол SSL);
2.2. SFTP (с использованием защищённого протокола SSH);
3. HTTP/HTTPS.

4. Триггеры для интеграции 

Каким будет вариант запуска интеграции?
а) В системе‑потребителе или системе‑источнике были созданы, удалены, изменены какие‑либо данные;
б) У какой‑либо сущности изменился статус;
в) Пользователь нажал на определённую кнопку;
г) Наступил срок для интеграции по расписанию.

Параметры расписания для запуска механизма интеграции:

1. Периодичность, с которой запускается механизм интеграции: например, 1 раз в сутки;

2. Возможность отключения задания по интеграции: возможно или невозможно;

3. Возможность принудительного запуска задания по интеграции в любой момент, вне зависимости от настроенного расписания запуска: возможно или невозможно.

5. Источник данных 

Что делать, если система-потребитель не может получить ответ от системы-источника?

• Сколько раз повторять обращение («попытки достучаться») до неотвечающей системы-источника?

• Через сколько времени повторять обращение?

• Какой должен быть таймаут, чтобы перестать обращаться к системе-источнику? 

• Есть ли возможность взять данные из другого альтернативного источника?

• Кого из команды системы-потребителя уведомлять об этом?

Как обрабатывать дубликаты файлов с одинаковым названием и датой?

а) Оставляем оба дубликата: предложить ли переименовать новый файл? Вариант «Оставить оба файла» может привести к конфликту данных;
б) Оставляем новый файл;
в) Оставляем первый файл.

Как загружать файлы?

• Можно ли автоматически забирать данные?

• Есть возможность вручную загрузить данные, скачать данные архивом и загрузить в систему или БД?

Какой порядок хранения файлов?

• Как долго мы храним файлы перед их удалением? 

6. Валидация данных 

Есть ли документация или примеры передаваемых данных? Есть ли XSD-схема или JSON-схема?

Как действовать системе-источнику, если мы получаем не то, что ожидаем?

Например:
а) Файл не соответствует формату;
б) Нарушена структура и порядок следования атрибутов;
в) Обязательные реквизиты не заполнены;
г) Файл пуст.
 Как будем его обрабатывать:
 – игнорировать
 – выдать ошибку (если да, то какую именно?)
д) «Битый файл» (не открывается вовсе; открывается, но в нём корректно отображается лишь часть данных)
 Как будем его обрабатывать:
 – почистить данные
 – отображать данные как есть
 – обработать те данные, что корректны при отображении в битом файле

Как будем сохранять информацию о проблемных файлах и кого будет уведомлять об этом?

7. Правила и ограничения

Могут быть случаи, когда экземпляра сущности из системы-потребителя больше нет в системе-источнике. Или передаётся дочерняя сущность, но больше нет родительской сущности. Как тогда необходимо поступить:
а) удалить экземпляр сущности в системе-потребителе и решить, как поступить со связанными с ней сущностями (разорвать между ними связь или удалить их тоже?);
б) оставить экземпляр сущности в системе-потребителе и показать её неактивный статус;
в) отображать вместо неё другую сущность, связанную с отсутствующей.

Какие будут системные и архитектурные ограничения?

• Какой максимальный размер файла система-потребитель может принять?

8. Управление запусками интеграций 

• Если предусмотрен ручной запуск интеграции, кто имеет право инициировать этот запуск?

• Кто имеет право смотреть историю запусков?

• Кто может смотреть/настраивать права для инициирования или просмотра истории запусков?

3.2. Общая база данных

1. Способ взаимодействия с БД
а) нативное подключение;
б) с использованием DBC API (JDBC или ODBC).

2. Тип обращения внешних приложений
а) напрямую к таблицам в БД;
б) к представлениям таблиц БД.

3. Возможности и доступ для внешних систем

• только на чтение данных;

• на чтение, запись, редактирование и удаление данных.
  Нужно ли в таком случае создать триггеры оповещения на потенциально опасные действия: удаление или запись данных?

4. Защита от встраивания в запрос вредоносного кода через SQL-инъекции

• Как реагировать на попытку записи данных с неверным типом?

• Как предотвратить неверную типизацию в коде приложения?

Ограничения:

• Если две системы одновременно захотят использовать одни и те же таблицы в БД, то ресурс будет заблокирован (ситуация называется «дедлок» (deadlock)*

• Если одной системе необходимо создать в таблице дополнительное поле или переименовать столбец – то обязательно необходимо согласовать изменение с другой системой.

• Низкий уровень абстракции, так как системы работают с конкретными полями и записями в БД.
   
   *При этом есть возможность обойти блокировку через метод «грязного чтения» (Dirty Read) — когда данные, которые пользователь прочитал, кто-то может откатить ещё до того, как пользователь завершит свою транзакцию.

Скрытый текст

Транзакция – это совокупность операций, которые должны выполняться последовательно и все. Если в процессе выполнения операций хотя бы по одной из них будет неуспешный результат, то все предыдущий операции отменяются, а оставшиеся больше не выполняются.

Набор требований к транзакционной системе, обеспечивающий наиболее надёжную и предсказуемую её работу, определён в критериях ACID:

1. Atomicity — Атомарность;

2. Consistency — Согласованность;

3. Isolation — Изолированность;

4. Durability — Прочность.

При реализации интеграции через общую базу данных определяют, какую БД наделят ролью ведущей (мастер-системой), а какую — ведомой.

Ведущая БД (node 1) — это основной узел базы данных, который обрабатывает все операции записи (например, INSERT, UPDATE, DELETE) и координирует данные. Когда клиентское приложение отправляет запрос на запись данных, он направляется к ведущей БД. Ведущая БД отвечает за согласование всех изменений и поддержание консистентности данных среди всех ведомых БД.

Ведомые БД (node 2) — это вторичные узлы базы данных, которые реплицируют данные с ведущей БД. Они отвечают за обработку операций чтения (например, SELECT). Когда клиентское приложение отправляет запрос на чтение данных, он может быть направлен к любой из ведомых БД. Так ведомые БД разгружают мастер-систему от запросов на чтение, что улучшает производительность.

Ключевые особенности:

1. Репликация данных: ведущая БД отправляет изменения данных всем ведомым БД, чтобы поддерживать их актуальность. Это происходит через процесс репликации, где изменения записей ведущей системы передаются и воспроизводятся на ведомых. Репликация также обеспечивает избыточность и отказоустойчивость, гарантируя, что данные реплицируются на несколько узлов синхронно или асинхронно.

2. Высокая доступность: если ведущая БД выходит из строя или недоступна, одна из ведомых БД может быть повышена до роли ведущей для обеспечения непрерывности обработки операций записи.

3. Масштабируемость на чтение: добавление дополнительных ведомых БД позволяет распределить нагрузку на операции чтения, увеличивая производительность БД.

Относительно низкая стоимость: использование ведомых БД для операций чтения позволяет использовать более дешёвое оборудование для них, что может снизить общую стоимость БД.

3.3. Удалённый вызов процедур

Общие вопросы для всех нижеуказанных вариантов удалённых вызовов процедур:

• Какой будет стратегия управления версиями?

REST

1. Какими будут названия веб-сервисов или методов (GET, POST, PUT, PATCH и DELETE и т. д.), к которым происходит обращение?

2. Каким будет описание формата, структуры запроса и ответа полезной нагрузки? Каким будет набор входящих и исходящих параметров для каждой конечной точки (endpoint)? 

3. Какой будет кодировка? Будут ли использоваться технические заголовки? Будет ли использоваться декларация? Будут ли использоваться конверты?

4. Какие будут правила к запросу/ответу данных?

5. Какие будут статусы ответов сервера для каждой конечной точки?

6. Какой будет зависимость между методами?

7. Какие будут форматы ошибок?

8. Каким должен быть таймаут?

9. Необходимо вести версионирование изменений условий взаимодействия, сообщая системе-потребителю о следующих изменениях:

• новые ответы;

• новые статусы;

• новые значения справочников;

• изменение обязательности данных;

• новые коды ошибок.

Необходимо поддерживать обратную совместимость: новые сервера могут читать старые запросы, а новые ответы могут читаться старыми клиентами. 

Скрытый текст

Выделяют 3 типа обеспечения совместимости:

Backward — обратная совместимость

Пользователи новой версии могут обрабатывать данные, указанные и в старой версии тоже. Потребитель версии (N+1) понимает производителя версии (N)

Аналогия: когда вы покупаете новый телевизор с HDMI 10.0, вы хотите иметь возможность подключить его к старому потоковому устройству, поддерживающему HDMI 9.0, в дополнение к выходным устройствам HDMI 10.0. Таким образом, HDMI 10.0 обратно совместим с HDMI 9.0. HDMI 10.0 был разработан таким образом, чтобы клиенты (телевизоры) могли подключаться к старым устройствам 9.0 (потоковым устройствам).

Forward — прямая совместимость 

Данные, созданные с помощью новой версии, могут быть обработаны потребителями, использующими старую версию. Потребитель версии (N) понимает производителя версии (N+1).

Аналогия: вы хотите, чтобы ваше новое потоковое устройство HDMI 10.0 могло подключаться к вашему старому телевизору HDMI 9.0. Это в дополнение к соединению 10.0 => 10.0. Это может означать, что HDMI 9.0 (потребительская сторона, телевизоры) был разработан с учётом перспективного мышления, что оставляет место для будущей эволюции (например, новые атрибуты игнорируются, если не распознаются). Таким образом, когда была создана версия 10.0, её можно было сделать совместимой с версией 9.0.

Full — полная совместимость 

Совокупность обратной и прямой совместимости:
Потребитель (V+1) понимает производителя (V)
Потребитель (V) понимает производителя (V+1)

HDMI 10.0 полностью совместим с HDMI 9.0, если вы можете подключить выход HDMI 10.0 (производитель) к телевизору HDMI 9.0 (потребитель) и выход HDMI 9.0 к телевизору HDMI 10.0.

Обратите внимание, что чаще всего мы читаем об обратной совместимости. Например, HDMI 2.1 обратно совместим. Фактически, он полностью совместим. В противном случае было бы невозможно подключить выходные устройства HDMI 2.1 (например, GPU) к старым мониторам HDMI 2.0. Это упрощение, так как протокол выбирается во время согласования протокола, и более новые устройства переключаются на связь по старому протоколу.

SOAP

1.  Какой будет перечень функций на сервере?

2.  Какой будет структура и содержимое XML-сообщений запросов? Какой будет XSD-схема?

3.  Какой будет перечень статусов ответов сервера, в том числе ошибок? 

4.  Какой будет структура и содержимое XML-сообщений ответов?

GraphQL 

1. Каким будет набор конечных точек? 

2. Какой будет для каждой конечной точки вид запроса: запрос, мутация, подписка на события – и JSON-схема полезной нагрузки запроса клиента?

3. Какой будет для каждой конечной точки статус ответа сервера, в том числе ошибок?

4. Какой будет GraphQL schema?

gRPC

1. Какой будет механика обмена данными:
а) синхронный запрос-ответ;
б) потоковая передача данных.

2. Каким будет название удалённой функции, которую необходимо вызывать?

3. Каким будет пример protobuf-сообщения полезной нагрузки ответа сервера?

Webhook

1. Какие данные будут передаваться, в каком формате?

2. Какой будет логика преобразования данных?

3. Каким будет состав событий-триггеров?

WebSocket

1. Каким будет сценарий отправки сообщений:
а) сообщение будет отправляться от клиента к серверу;
б) сообщение будет отправляться от сервера к клиенту.

2. Каким будет передаваемое сообщение? 

3. Какими будут требования по безопасности?

Требования позволят выбрать между протоколами:
а) wss – WebSocket Secure;
б) ws – WebSocket.

3.4. Асинхронный обмен сообщениями

1. Как будет называться канал связи*, в который будут публиковаться данные?
 
 *Варианты каналов связи у самых популярных инструментов асинхронного обмена сообщениями:
а) в Apache Kafka: топик;
б) в RabbitMQ: очередь.

2. Какие будут параметры полезной нагрузки сообщений от отправителя? Каким будет его формат и схема? Его максимальный размер будет не более 1 Мб? Какой будет его кодировка?

3. Какова надёжность системы-потребителя? Какой должна быть гарантия доставки сообщения? Будет ли использоваться ретрай: повторная отправка запроса?
Допускаем ли дублирование? Как поступать при обнаружении дубликата? 
Необходимо выбрать между двумя вариантами:
а) каждое сообщение может быть отправлено более 1 раза, но при этом возможно появление дубликатов;
б) каждое сообщение может быть отправлено лишь 1 раз, но при этом сообщение может потеряться.

4. Должно ли быть подтверждение о прочтении сообщения?
а) система-потребитель должна отправлять сообщение системеисточнику о прочтении сообщения;
б) система-потребитель не должна отправлять сообщение системе-источнику о прочтении сообщения.

5. Какова пропускная способность системы-источника, системы-потребителя и сети?

6. Каким будет фактор репликации: количество копий сообщения в кластере брокера?

7. Какой будет производительность потока данных в части публикации и потребления?

8. Как необходимо настроить размещение сообщений?

9. Какой будет схема потокового обмена, на которой будут отображены все топики/очереди, отправители и потребители данных?

10. Требуется ли преобразование протоколов при передаче данных?

11. Кто инициирует обмен данными?
а) система-потребитель первая инициирует запрос данных у системы-источника;
б) система-источник сама отправляет данные системе-потребителю;
в) обмен данными двунаправленный: и система-потребитель, и система-источник могут инициировать взаимодействие.

12. Какова периодичность передачи данных?

13. Каков характер передачи данных?
а) пакетный;
б) потоковый.

14. Какова максимально допустимая задержка обработки данных?
а) нужна передача данных в реальном времени;
б) допустимо ожидание данных.

15. Необходима ли транзакционность: нужно откатывать изменения, если на каком-то шаге возникла ошибка?

16. Какой должна быть доставка сообщения до системы-потребителя?
а) система-потребитель должна сама доставать сообщение из очереди сообщений;
б) система-источник должна через брокера сообщений «проталкивать» сообщение до системы-потребителя.

17. Какой должна быть система хранения и удаления сообщений?
а) сообщение должно храниться в брокере сообщений до плановой очистки;
б) сообщение должно удаляться сразу после его прочтения.

18. Какой должна быть модель потребления сообщения?
а) очередь: передача сообщения для одной системы-потребителя. Сообщение прочитано и удалено;
б) подписка: передача сообщение для нескольких систем-потребителей.

19. Будет ли брокер проверять сообщения на ошибки? Если да, то какой будет валидация? Требуется ли поддержка схем данных (например, проверка соответствия сообщения Schema Registry/JSON Schema)?

20. Какими будут требования к мониторингу очередей? Какими будут метрики по задержке и обработке зависших сообщений? 

4. Требования к журналированию

Прежде всего разделим понятия:

Журналирование — это процесс записи значимых событий, связанных с действиями пользователей или изменениями состояния системы, для обеспечения прозрачности, аудита и соблюдения нормативных требований.

Логирование — это процесс записи технических событий в системе (например, ошибок, запросов, изменений состояния) для диагностики проблем, мониторинга производительности и анализа работы приложения.

1.  Журнал запусков интеграций должен содержать: 

• Дату и время начала предыдущего, выполняемого и следующего запуска интеграции;

• Данные об общей длительности выполнения всех задач в запуске;

• Наименование участвующих в интеграции систем;

• Информацию о количестве записей.

2. Детализация в разрезе каждой записи: 

• Дата и время начала и окончания обработки записи;

• Результат обработки: успешно, предупреждение, ошибка;

• Сведения об ошибке/предупреждении: причина её возникновения.
   
   Рекомендуется:

• Учитывать не только ошибки с кодом 200 и 500;

• Сокращать ошибки с 500 кодом, описывая что именно произошло.

3. События, которые могут журналироваться: 

• Успешная и неуспешная авторизация пользователей в систему, а также выход из неё;

• Добавление, удаление или изменение пользовательских данных и их прав, согласно ролевой модели;

• Добавление, удаление или изменение контента и файлов;

• Заблокированные и разрешённые сетевые пакеты;

• Передача файлов. 

4. Оповещение по созданным событиям ответственных лиц 

• Будет ли по событиям создаваться отчёт?

• Кто будет иметь доступ к отчёту?

• Какой будет система уведомлений ответственных о готовом отчёте? Например, через интерфейс системы, письмом, push-уведомлением.

• Будут ли какие-либо пороговые значения, при превышении лимита которых будет целесообразно уведомлять ответственных о готовности отчёта по событиям? Например, уведомление при 5% ошибок за час.

5. Ротация журналов

• Как долго система должна хранить записи в журнале? 

Интегрироваться? Легко!

После того, как аналитик спроектирует интеграцию, задача переходит к другим специалистам.

Разработчики реализуют всё то, что вы спроектировали, и будут поддерживать систему при её изменениях.

Тестировщики проведут end-to-end тестирование, чтобы удостовериться, что ничего в работе системы не сломалось, нагрузочное тестирование, чтобы проверить, что мы придерживались заявленных критериев по SLA по производительности.

Системные администраторы будут отслеживать состояния интеграции с помощью Health Check-системы.

Надеюсь, моя статья поможет сделать процесс интеграции для вас и ваших коллег проще, эффективнее и быстрее.