NEOMSA APIM состоит из 2 слоев. Слой управления API отвечает за публикацию, шлюз, ключи и лимиты. Интеграционный слой подключает системы источники. В интеграционном слое работают 2 отдельных продукта с разными движками, у каждого своя среда выполнения. Микроинтегратор (WSO2 Integrator: MI, прежнее имя WSO2 Micro Integrator) работает на движке Apache Synapse и закрывает интеграцию систем: синхронный вызов с ответом вызывающей стороне, асинхронную передачу через очередь, файловые и пакетные обмены. Потоковый интегратор (WSO2 Streaming Integrator) работает на движке потоковой обработки и закрывает обработку событийных потоков: непрерывные запросы к потоку, временные окна, агрегации. Продукты решают разные задачи, взаимозаменяемыми они не являются.

Термины статьи. Среда выполнения это экземпляр микроинтегратора, который разворачивается, масштабируется и обновляется как единица инфраструктуры. Интеграционный сервис это конфигурация медиации: API, прокси-сервис, последовательности, endpoints. Она исполняется внутри среды выполнения. Интеграционный поток это путь сообщения от точки входа до точки выхода. У конфигурации медиации нет собственного жизненного цикла, своего хранилища данных и отдельной команды сопровождения. Единицей развертывания выступает среда выполнения с набором артефактов. Артефактом далее называется отдельный элемент конфигурации: REST API, прокси-сервис, последовательность, endpoint. Интеграционный проект это набор таких элементов, который собирается в один файл поставки и разворачивается в среду выполнения.

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

Микроинтегратор строит интеграционные потоки и поддерживает шаблоны корпоративной интеграции (Enterprise Integration Patterns, EIP). Поддерживаются 2 стиля развертывания. Децентрализованный (decentralized, microservices): отдельный экземпляр среды выполнения поднимается под группу связанных интеграционных потоков, рядом с системами, которые он обслуживает. Централизованный (centralized, ESB): один экземпляр обслуживает интеграционные потоки нескольких систем в стиле общей шины. Разворачивается в обоих случаях среда выполнения с набором артефактов. Работает на виртуальных машинах, в Kubernetes, в локальной инфраструктуре и в облаке. Для команд, которые ведут разработку микросервисов, это способ вынести интеграционную логику из кода сервисов на отдельный уровень.

Сообщение попадает в среду выполнения через одну из точек входа:

● REST API: артефакт привязан к заданному контексту URL, состоит из ресурсов и обрабатывает запросы внутри своего контекста. Штатный выбор для HTTP и REST

● прокси-сервис: артефакт для SOAP и для транспортов помимо HTTP (JMS, VFS, MailTo, FIX). Ставится перед существующим бэкендом и дает возможность добавить преобразование и логику без правки самого бэкенда. Для сценариев HTTP и REST применяется артефакт REST API

● входящая точка (inbound endpoint): несет собственную конфигурацию, включая свой порт, параметры протокола и пул потоков. Общий транспортный стек экземпляра при этом не задействуется, поэтому входящая точка добавляется, изменяется и снимается без перезапуска среды выполнения. Типовое применение: слушатели JMS, Kafka, RabbitMQ, файловых каталогов, а также слушатели HTTP на выделенных портах

● главная последовательность (main sequence): обрабатывает сообщения, которые не адресованы ни одному API и ни одному прокси-сервису

Список охватывает точки входа для сценариев обмена сообщениями. Интерфейсы над базами данных в статье не рассматриваются.

Отдельно работают задачи по расписанию, которые сами инициируют сообщение. По умолчанию такая задача отрабатывает на каждом экземпляре среды выполнения: при 3 репликах она выполнится 3 раза. Вариантов решения 2: включить координацию задач между узлами либо вынести задачи в отдельный экземпляр, поднятый в 1 реплике. Выбор фиксируется до вывода потока в промышленную эксплуатацию.

По умолчанию работает транспорт PassThrough: тело сообщения проходит сквозным потоком (binary relay) и не разбирается, пока к нему не обратится медиатор. В момент обращения включается сборщик (message builder), тело приводится к внутреннему представлению, с которым работает движок медиации, на выходе форматтер собирает его обратно. Любая трансформация или валидация тела снимает сквозной режим и меняет профиль нагрузки на экземпляр.

Медиатор это единица обработки: трансформация, обогащение, фильтрация, логирование, ветвление, вызов. Последовательность это набор медиаторов, выстроенных в логический поток, реализация паттерна pipes and filters. Последовательности именуются и переиспользуются: одна цепочка подключается по ключу из разных API и прокси-сервисов. Конфигурация описывается на языке Apache Synapse в формате XML. Цепочка собирается графически, в редакторе с низкокодовым интерфейсом (расширение WSO2 Integrator: MI for VS Code). Инструмент на базе Eclipse (WSO2 Integration Studio) объявлен устаревшим.

Библиотека медиаторов покрывает шаблоны корпоративной интеграции из каталога Хопа и Вульфа (Hohpe, Woolf): маршрутизацию по содержимому (Content-Based Router), разделение и сборку сообщения (Splitter, Aggregator), обогащение из внешнего источника (Content Enricher). Паттерны микросервисной архитектуры описывают устройство системы сервисов, а не обработку сообщения. Отдельного медиатора для размыкания цепи при отказе в микроинтеграторе нет: отказоустойчивость собирается на уровне endpoint через повторы и перевод в состояние Suspended, а также через endpoint типов failover и load balance.

На каждый ресурс REST API и на каждый прокси-сервис заводится до 3 последовательностей: входящая (inSequence) для валидации, параметров и логирования, исходящая (outSequence) для логирования и возврата ответа, последовательность ошибок (faultSequence). У API с 5 ресурсами это 5 независимых наборов.

В актуальных версиях явная исходящая последовательность нужна не всегда: ответ получателя возвращается в тот же поток после медиатора call и отдается вызывающей стороне медиатором respond. Последовательность ошибок пустой не бывает. Если своя не задана, отрабатывает встроенная по умолчанию: она пишет ошибку в лог и вызывает Drop. Ответ при этом не формируется, и вызывающая сторона вместо ошибки получает таймаут.

Endpoint описывает внешнего получателя: адрес, очередь, почтовый ящик, сокет вместе с параметрами соединения. Через него микроинтегратор вызывает API микросервисов, унаследованные системы и брокеры. Транспорт выбирается схемой адреса: http, jms, vfs, mailto. Независимость endpoint в другом: он не привязан к конкретному входящему потоку и подключается по ключу из разных API и прокси-сервисов.

В endpoint задаются таймаут, коды ошибок для повторной отправки, число попыток и правила перевода в нерабочее состояние. Состояния: Active, Timeout, Suspended, Off. Настройки: timeout, markForSuspension (errorCodes, retriesBeforeSuspension, retryDelay), suspendOnFailure (initialDuration, progressionFactor, maximumDuration). Пауза перед следующей попыткой растет по формуле min(текущая пауза × progressionFactor, maximumDuration). При ошибке endpoint меняет состояние и запускает последовательность ошибок.

Практическое правило: отдельный endpoint на каждую операцию. Он дает операции свои таймаут, набор кодов ошибок и политику повторов. Отдельного пула соединений он при этом не дает: в транспорте PassThrough соединения пулятся по паре host и port, общий лимит задается параметром среды выполнения max_http_connection_per_host_port в файле deployment.toml. 2 endpoint на один и тот же хост делят 1 пул, и медленный вызов задержит быстрые. Изоляцию тяжелых и быстрых операций дают другие механизмы: разные таймауты, вынос тяжелого трафика на отдельный экземпляр среды выполнения, асинхронная схема через хранилище сообщений, настройка пула рабочих потоков.

Обращение к базе данных выполняется помимо endpoint: медиаторами работы с базой (dblookup, dbreport) с обращением к описанному источнику данных.

Целевая система редко держит тот же темп, что и входящий поток. Между медиацией и получателем ставится пара из хранилища сообщений (Message Store) и обработчика сообщений (Message Processor). Для этого сценария нужен плановый обработчик пересылки (Scheduled Message Forwarding Processor) с настройками interval и max.delivery.attempts. Обработчик выборки (Message Sampling Processor) имеет другую семантику и для развязки скоростей не подходит.

Медиация принимает запрос, медиатором store кладет сообщение в хранилище и формирует ответ явно: payloadFactory и respond. Без явного формирования ответа вызывающая сторона останется ждать. Обработчик вычитывает хранилище и отправляет сообщения в бэкенд с той частотой, которую тот выдерживает.

Хранилищем выступает очередь или база. Сообщение переживает перезапуск экземпляра только при постоянном хранилище: JMS, RabbitMQ, JDBC. Встроенное хранилище In-Memory держит очередь в памяти и теряет ее при рестарте, для промышленной эксплуатации оно не рекомендуется. При недоступности бэкенда обработчик повторяет отправку по своим правилам, накопленная очередь разбирается после восстановления.

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

Ресурсы и конфигурации хранятся в каталоге ресурсов проекта и в реестре: XSLT, XSD, WSDL, спецификации, параметры среды. Обращение идет по ключу, похожему на путь в файловой системе, потому что у реестра 3 уровня: local, config, governance. В актуальных версиях проект переехал на структуру с каталогом ресурсов внутри проекта, классический реестр постепенно уходит.

Адреса бэкендов и параметры среды выносятся в ресурсы проекта или в переменные окружения, в артефакте их нет. Учетные данные в открытом виде не кладутся ни в артефакт, ни в реестр. Штатный механизм это защищенное хранилище (Secure Vault): значение шифруется утилитой cipher-tool, конфигурация обращается к нему по алиасу. Поддерживаются также внешние хранилища секретов и секреты Kubernetes и Docker.

Коннекторы добавляют готовые операции для работы с внешними системами. Конфигурация подключения хранится отдельно от самого коннектора и параметризуется по средам.

Каждый элемент проекта хранится отдельным файлом конфигурации. При сборке они попадают в один композитный артефакт приложения (Composite Application, CApp, файл .car).

Структура типового проекта:

Последовательности и endpoints выносятся из ресурса и подключаются по ключу, поэтому одна цепочка обслуживает несколько методов и несколько API.

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

Экземпляр среды выполнения поднимается под набор интеграционных сервисов, стартует за секунды, масштабируется горизонтально и выкатывается тем же CI/CD, что и остальные сервисы контура.

Дальше интеграционные сервисы регистрируются в каталоге сервисов, и слой управления API создает на них прокси напрямую, без повторного описания интерфейса. Регистрация не происходит сама: публикация включается в файле deployment.toml, где задаются адрес узла слоя управления API и учетные данные, а у интеграционного сервиса должны быть метаданные и сгенерированное описание OpenAPI. Автоматически публикуются артефакты REST API. Прокси-сервисы SOAP автоматически не публикуются.

● источник работает по SOAP или обменивается файлами, потребителю нужен REST

● один вызов API собирает ответ из 3 и более систем

● нужна асинхронная развязка через очередь

● данные требуется обогатить и проверить до попадания в шлюз

● последовательность ошибок задана явно во всех ресурсах API и во всех прокси-сервисах

● структура сообщения об ошибке единая для всех сервисов контура

● код ответа бэкенда проверяется явно, через свойство HTTP_SC: при значении вне 200, 201, 202, 204 ошибка формируется в потоке. Последовательность ошибок отрабатывает на транспортных ошибках и таймаутах. Ответ вне диапазона успешных ее сам по себе не запускает, для микроинтегратора это доставленный ответ

● на экземпляре среды выполнения настроены пробы: liveness на порт транспорта (по умолчанию 8290), readiness на встроенный /healthz служебного порта (по умолчанию 9201). Отдельный ресурс /health в интеграционном сервисе не описывается: проба относится к среде выполнения. В неизменяемом развертывании (immutable) она переходит в состояние ready после успешного развертывания всех CApp и возвращает список сбойных

● спецификация OpenAPI 3.0 доступна запросом к самому сервису, суффиксы ?swagger.json и ?swagger.yaml

● адреса и параметры среды вынесены в переменные окружения или ресурсы проекта, учетные данные в Secure Vault или во внешнее хранилище секретов. В артефакте и в реестре секретов в открытом виде нет

● для задач по расписанию зафиксирован режим работы при нескольких репликах: координация между узлами либо отдельный экземпляр в 1 реплике

Классическая сервисная шина предприятия это одна общая среда выполнения, куда разворачиваются все интеграционные потоки. Микроинтегратор поддерживает 2 стиля развертывания. В децентрализованном отдельный экземпляр среды выполнения поднимается под набор интеграционных сервисов, стартует за секунды, масштабируется горизонтально и выкатывается тем же CI/CD, что и остальные сервисы контура. В централизованном один экземпляр обслуживает интеграционные потоки нескольких систем в стиле общей шины.

Медиатор это единица обработки сообщения: трансформация, обогащение, фильтрация, логирование, ветвление, вызов. Последовательность это цепочка медиаторов, реализация паттерна pipes and filters. Последовательности именуются и подключаются по ключу из разных API и прокси-сервисов. Последовательности привязываются к ресурсу REST API или к прокси-сервису, поэтому у API с 5 ресурсами это 5 независимых наборов.

Интеграционные сервисы регистрируются в каталоге сервисов, после чего слой управления API создаёт на них прокси напрямую, без повторного описания интерфейса, и применяет политики доступа, версии, лимиты и мониторинг. Регистрация не происходит сама: публикация включается настройкой среды выполнения, у интеграционного сервиса должны быть метаданные и описание OpenAPI. Автоматически публикуются артефакты REST API. Прокси-сервисы SOAP автоматически не публикуются.

Когда целевая система не держит темп входящего потока. Медиация принимает запрос, кладёт сообщение в хранилище и формирует ответ явно, обработчик отправляет сообщения в бэкенд с той частотой, которую тот выдерживает. Сообщение переживает перезапуск экземпляра только при постоянном хранилище: JMS, RabbitMQ, JDBC. Встроенное хранилище в памяти теряет очередь при рестарте. Для сценариев с синхронным ответом схема не подходит.

Виртуальные машины, Kubernetes, локальная инфраструктура и облако. Разворачивается среда выполнения с набором артефактов, в децентрализованном или в централизованном стиле. Интеграционный сервис при этом не является самостоятельным микросервисом: он представляет собой конфигурацию медиации, которая исполняется внутри среды выполнения.

Шаблоны интеграции корпоративных приложений описывают обработку сообщения: маршрутизация по содержимому, разделение и сборка, обогащение из внешнего источника. В микроинтеграторе они реализуются медиаторами. Паттерны микросервисной архитектуры описывают устройство системы сервисов и реализуются платформой контейнеров и настройками endpoint. Отдельного медиатора для размыкания цепи при отказе в микроинтеграторе нет, отказоустойчивость собирается на уровне endpoint.

Микроинтегратор работает на движке Apache Synapse и входит в состав NEOMSA APIM: интеграционные сервисы регистрируются в каталоге сервисов, и слой управления API создаёт на них прокси. Отдельный продукт NEOMSA ESB построен на другом движке, Apache Camel, и реализует тот же набор шаблонов интеграции корпоративных приложений без привязки к слою управления API.