Введение в CESB: зачем банку сервисная шина

В банке десятки систем: АБС, интернет-банк, мобильное приложение, процессинг, антифрод, платёжные системы. Каждая время от времени должна обратиться к другой. Если соединять их напрямую, получается клубок интеграций, который дорого поддерживать и страшно менять. Сервисная шина решает эту проблему: она ставит в центр одну общую точку, через которую системы общаются друг с другом. Такая шина у Colvir называется CESB - Colvir Enterprise Service Bus, корпоративная сервисная шина Colvir. Этот урок вводный, кода ещё не будет. Задача - понять, что такое CESB, из чего она состоит и что происходит с запросом внутри неё. Это фундамент под все следующие модули.

1. Проблема, ради которой существуют шины

При прямых связях «каждый с каждым» число интеграций растёт квадратично: для n систем это n·(n−1)/2. Пять систем дают 10 связей, десять систем уже 45. Каждая связь несёт свой протокол, формат и обработку ошибок. Меняете одну систему, и есть риск задеть все, что с ней соединены.

Шина переворачивает картину. В центр ставится одна общая точка, и каждая система знает только про неё. Связей становится n вместо n².

Что шина берёт на себя:

Такой подход применяют там, где много разнородных систем, которые нельзя переписать с нуля: банки, телеком, страховые, госсектор. CESB это реализация такой шины от Colvir.

2. Где CESB стоит в архитектуре

CESB состоит из прикладных сервисов (в них живёт бизнес-логика) и ядра-шлюза, которое даёт сервисам общую функциональность. Три термина, которые будут встречаться постоянно:

• Сервис - программа, решающая свою бизнес-задачу (например, сервис авторизации AuthMngr или сервис платёжных шаблонов PayHub).
• Модуль - общее название для любой «единицы» шины: и каждый сервис - модуль, и само ядро - тоже модуль. Говорим «модуль», когда правило касается и сервисов, и ядра.
• Реплика - запущенная копия модуля. Один и тот же сервис может работать в трёх репликах: нагрузка делится между ними, а падение одной копии не роняет сервис. Это балансировка и отказоустойчивость.

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

Клиент шины (мобильное приложение, интернет-банк, внешняя система) обращается к слою доступа Web Access Layer, тот к шине, и уже шина общается с АБС и сторонними сервисами.

Зелёным на схеме - то, что пишете вы. Всё остальное уже существует: ваш сервис встраивается в готовую конструкцию, а не строит её заново.

Что это даёт банку: единую точку интеграции вместо прямых связей; переиспользование сервисов между разными клиентами шины; централизованную авторизацию; подключение новых систем без переписывания существующих.

Живой пример: мгновенный перевод

Чтобы увидеть шину в действии, проследим один мгновенный перевод по шагам:

1. Человек в мобильном приложении нажимает «Перевести».
2. Приложение шлёт запрос в сервис кошелька (хранит счета и балансы).
3. Сервис кошелька через шину вызывает сервис платежей - тот выполняет операцию резервирования средств: замораживает сумму на счёте, чтобы её нельзя было потратить дважды (это действие, а не отдельный сервис).
4. Сервис платежей через шину обращается к сервису платёжной системы и шлюзу банка, которые передают перевод во внешнюю систему мгновенных платежей.
5. Статус («исполнен» / «отказ») возвращается по той же цепочке, резерв списывается или снимается, человеку приходит уведомление.

Протоколы у участников разные, но каждый сервис видит только шину - она связывает всё в единый процесс. Запрос проходит через пять-шесть систем, а разработчику кошелька достаточно знать контракт соседнего сервиса, а не всю цепочку. Детально такие интеграции разберём в пятом модуле.

3. Протокол BaS: объекты Base и Service

Внутри шина говорит на протоколе с рабочим названием BaS. Все запросы и ответы это JSON, и в каждом всегда два параметра: B (Base) и S (Service).

• Base - строго регламентированный системный объект. В нём то, что не относится к бизнес-логике: кто вызывает, данные сессии и безопасности, как вернуть результат, контекст запроса.
• Service - объект произвольной структуры, полезная нагрузка для конкретного метода сервиса.

Клиент может прислать запрос в полном формате BaS либо в упрощённом REST или SOAP. Если запрос приходит не в BaS, шлюз сам достроит объект Base (часть полей возьмёт из HTTP-заголовков, например User-Agent, X-ColvirS, Authorization).

Из чего состоит Base

Пример запроса:

{
  "B": {
    "Cli": { "Code": "TestApp", "L": "RU" },
    "SD":  { "SID": "" },
    "RT":  { "Type": "S" },
    "QCTX":{ "ID": "7218216729702198041" }
  },
  "S": { "clientCode": "C-1024", "amount": "150000" }
}

Ответ всегда содержит B и S. Внутри S либо _R с результатом, либо _E с ошибкой. Успешный ответ:

{
  "B": { "QCTX": { "ID": "7218216729702198041" } },
  "S": { "_R": { "requestId": "REQ-1024", "status": "ACCEPTED" } }
}

Ответ с ошибкой - вместо _R приходит _E, и HTTP-код отражает суть ошибки:

{
  "B": { "QCTX": { "ID": "7218216729702198041" } },
  "S": { "_E": { "Code": 1500, "Text": "Неверный логин или пароль.", "HTTPCode": 403 } }
}

Частые вопросы про BaS

«Обязательно ли мне, как разработчику сервиса, знать все эти поля Base?»

В 90% случаев, когда вы пишете бизнес-логику, вы работаете только с объектом Service. Объект Base извлекается и обрабатывается ядром автоматически - вы его не собираете и не разбираете. Но понимать его структуру важно для отладки: QCTX.ID и SD.SID - ваш главный инструмент поиска проблем в логах.

«Что такое B.RT.Channel и когда оно используется?»

Поле указывает предпочтительный способ доставки асинхронного ответа (например, WS - WebSocket). Это позволяет ядру доставить результат обратно клиенту тем же путём, которым пришёл запрос. Для обычного синхронного вызова (RT.Type = S) поле не нужно.

«Где и кем заполняется QCTX.ID и SD.SID?»

QCTX.ID присваивает ядро шины, когда запрос в неё входит, - дальше он не меняется и проходит через все сервисы в цепочке. SD.SID появляется после успешного логина: его выдаёт AuthMngr, клиент забирает его из ответа и прикладывает к последующим запросам. Ваш сервис оба поля только читает.

4. Ядро это набор служб

Ядро не монолит. Внутри несколько служб, каждая отвечает за свой этап обработки запроса:

Три из них стоит понять сразу:

• Реестр сервисов. По нему шлюз понимает, кому перенаправить запрос. Сервис регистрируется при запуске и раскрывает все свои бизнес-методы, но шлюз может потребовать повторной регистрации во время обработки любого запроса. Шлюз вправе заблокировать сервис или отдельный метод независимо от того, что прислал сам сервис. Если сервис не зарегистрировался (упал на старте, не достучался до ядра) - для шины его не существует: реестр не находит адресата, и клиент получает ошибку «сервис или метод не найден». Работающий процесс без регистрации запросов не получит.
• Конфигурации. Держатель конфигурации это ядро. Сервис при старте обращается к ядру и получает настройки, своей конфигурации он не хранит.
• Авторизация. Пространство сервисов это чистая зона: внутрь попадает только проверенный запрос. Каждый метод может требовать свой вид проверки авторизации либо вовсе её исключить. CESB умеет работать и с авторизационными токенами, и с проверкой при каждом запросе. Данные о пользователе доступны во всех методах через Base.

Что происходит при сбое

Полезно понимать, в каких случаях ваш код вообще не будет вызван:

• Сервис не найден в реестре или авторизация вернула отказ. Ядро само формирует ответ с ошибкой (объект S._E) и возвращает его клиенту. Ваш код не вызывается вообще. Это гарантия, что сервис получает только «чистые» запросы: авторизованные и адресованные ему.
• Ваш сервис упал с исключением во время выполнения. Ядро перехватывает исключение, заворачивает его в стандартный формат S._E и возвращает клиенту. Так все ошибки в системе выглядят одинаково, независимо от того, где они возникли.

Отсюда практический вывод: не пишите в каждом методе проверки «а вдруг пользователь не авторизован» - до вас такой запрос не дойдёт. Зато ошибку своей бизнес-логики надо формировать осознанно, а не позволять ей превратиться в случайный NullPointerException (этим займёмся в уроке 4.1).

Как модули общаются между собой

Модули общаются по HTTP, используя hostname машины - он же служит уникальным кодом модуля. Запасной путь - шина сообщений RabbitMQ. Важное правило: за исключением внешних запросов к самому ядру, модули всегда отвечают HTTP-кодом 200, а возникшая ошибка передаётся внутри тела ответа (в S._E). Поэтому «200» от модуля ещё не значит «успех» - смотреть нужно в тело ответа, а не только на HTTP-статус.

Синхронно и асинхронно

Если результат нужен сразу, запрос синхронный (B.RT.Type = "S"): ответ возвращается по той же цепочке. Для долгих операций есть асинхронный режим ("A"): ядро через службу регистрации асинхронных запросов сразу подтверждает приём, а готовый результат клиент забирает позже по B.QCTX.ID.

Путь запроса целиком

1. Запрос приходит в ядро, проверяется формат.
2. Ядро читает Base.
3. По реестру сверяется, что сервис и метод существуют.
4. Если метод требует, проверяется авторизация.
5. Извлекается Service.
6. Проверяется кеш. Есть готовый ответ - он возвращается сразу, поход в сервис пропускается.
7. Иначе запрос уходит в сервис, стрелка двусторонняя: запрос и ответ.
8. Ответ адаптерами приводится к виду клиента и возвращается, синхронно напрямую или асинхронно через службу ответов.

5. Что уже готово в шине

Кроме ядра, в CESB есть стандартные модули. Терминологической ловушки здесь нет: GenericService, AuthMngr и прочие из таблицы - это системные сервисы, а раз каждый сервис является модулем (см. §2), их одинаково корректно называть и «стандартные сервисы», и «стандартные модули» - в документации и презентациях встречаются оба варианта. Их не нужно писать, ими нужно уметь пользоваться:

Несколько деталей, которые пригодятся дальше:

• GenericService позволяет собирать сервисы без написания Java - через метаописание в JSON (конфигурация, контроллеры с методами, сущности, адаптеры данных). Есть два типа: BasicGenericService и CBSGenericService. Хранится как WAR-проект в GitLab и Nexus.
• AuthMngr - именно к нему обращается служба авторизации ядра; он проверяет авторизованность и хранит авторизационные данные. Подробно - в модуле про интеграции.
• CBSMQ даёт вызывать методы сервисов прямо из СУБД CBS через встроенную очередь, в синхронном и асинхронном режимах, с гарантией доставки, и умеет работать как веб-прокси к внешним сервисам.
• Служба локализации реализована в базовой библиотеке; словарь можно даже вынести в отдельный сервис на всю локализацию.

Со всем этим вы работаете через CESB SDK - набор высокоуровневых методов, который почти полностью прячет внутреннюю кухню шины. Всё, что мы разобрали выше, происходит под капотом. Структуру SDK подробно разберём в модуле про разработку.

6. Каталог шины: что уже написано до вас

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

Сервисы делятся на три группы, и это деление не формальное - от него зависит, кто сервис заказывает, кто сопровождает и в какой репозиторий он попадает.

Общеполезные - это API к модулям АБС. Кредиты, депозиты, платежи, карты, зарплатные проекты, аккредитивы, факторинг, учёт обеспечения. Они не знают ничего про страну: их предметная область - банковское дело как таковое.

Локализованные - самая большая группа, и это закономерно. Каждая страна приносит свой набор обязательных интеграций: налоговая, кредитное бюро, реестр населения, регулятор, национальная платёжная система. Для Узбекистана это МУНИС, НИББД, ГРКИ, КАТМ, АНОР; для Казахстана - НБРК, КАСЕ, шлюз электронного правительства; для Азербайджана - свои. Один и тот же банковский продукт в трёх странах требует трёх разных наборов интеграций.

Кастомизированные - то, что нужно одному конкретному банку и больше никому.

Что это значит для вас

Три практических вывода, которые пригодятся уже на первом задании.

Первое: скорее всего, ваш сервис не первый в своём роде. Прежде чем проектировать с нуля, посмотрите, нет ли рядом сервиса с похожей задачей. Если вы делаете интеграцию с внешней системой - почти наверняка есть готовый образец, устроенный ровно так, как надо устроить ваш.

Второе: у большинства типовых задач есть сложившийся тип решения. Интеграция с чужим API без бизнес-логики на нашей стороне - это, как правило, прокси с одним методом: он сам авторизуется во внешней системе, держит таймауты и приводит запрос к нужному виду, но бизнес-решений не принимает. API к модулю АБС - ресурсная модель с путями вида /loans/{colvirReferenceId}. Обмен пачками по расписанию - очередь с планировщиком. Эти типы мы разберём в уроке 5.1 на боевых примерах.

Третье: инфраструктурные вещи уже решены и решены единообразно. Таймауты во всех интеграционных сервисах называются одинаково: connectionRequestTimeout, connectTimeout, responseTimeout. Секреты во всех сервисах хранятся одинаково - зашифрованными в конфигурации. Не изобретайте своих имён и своих способов: чужой сервис должен читаться вашим коллегой без объяснений.

Справочник: по каким доменам искать аналог

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

Клиенты и идентификация

Счета, выписки, РКО

Платежи

Кредиты

Депозиты, карты, валюта

Зарплата, персонал, специальные продукты

Уведомления и доставка

Инфраструктура и служебные

Где сервисы физически лежат

Три группы из предыдущего раздела видны прямо в структуре репозиториев. Код сервисов шины разложен по контурам: у каждого банка свой контур со своими сервисами, а общеполезные сервисы и сервисы для внешних систем конкретной страны лежат отдельно.

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

Два следствия, важных на практике.

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

Общие приёмы одинаковы везде. Имена таймаутов, шифрование секретов, заголовочный блок, формат depId_id соблюдаются во всех контурах. Различается бизнес-часть, а не каркас. Поэтому приёмы из курса переносятся в ваш контур без изменений.

Как читать документацию сервиса

Разборы в уроках курса построены на документации боевых сервисов шины, а в работе вам придётся читать документацию сервисов своего банка постоянно. Документы устроены одинаково, и читать их быстро - навык, который окупается с первого раза.

Типовой состав разделов:

В каком порядке читать

Не сверху вниз. Порядок, который экономит время:

Первое - «Общая схема работы». Там одна строка вида Внешняя система -> СШ -> АБС или Система, передающая логи -> СШ -> QRADAR. Эта строка говорит больше, чем весь остальной документ: она задаёт направление, а от направления зависит всё остальное. Сервис, в который приходят снаружи, и сервис, который ходит наружу сам, устроены по-разному, даже если оба называются интеграционными.

Второе - «Конфигурация». Читайте её как список того, что авторы ожидали менять. Есть emulatorActive - значит, предусмотрели работу без внешней системы. Есть DayLimitRequest - значит, столкнулись с превышением. Есть отдельные учётные данные для мобильного банка - значит, у сервиса несколько потребителей и их различают. Конфигурация - это спрессованная история эксплуатации.

Третье - «Методы сервиса». Теперь, зная направление и настройки, контракт читается осмысленно. Смотрите не только на список методов, но и на то, чего в нём нет: нет метода удаления - значит, в этом домене не удаляют; нет метода списка - значит, потребитель всегда знает идентификатор.

Четвёртое - «Список ошибок». Это перечень того, что в домене реально ломается. Быстрее любого описания даёт понять, о чём сервис на самом деле.

Пятое - «История изменений». Смотрите, что добавляли позже всего. Это то, чего не предусмотрели при проектировании, и почти всегда это же придётся предусмотреть вам.

Чего в документации нет и где это искать

Две вещи регулярно отсутствуют, и важно не искать их там, где их не бывает.

Почему сделано именно так. Документы описывают, что есть, а не почему выбрали этот вариант. Ответ обычно в задаче, на которую ссылается «История изменений».

Что происходит при сбое. Описано, как метод работает, но редко - что будет, если внешняя система не ответит. Это придётся выяснять по конфигурации (есть ли повторы и таймауты) и по списку ошибок.

7. Как разложить бизнес-задачу на решение в шине

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

1. Кто клиент шины? Это приложение или система, а не человек (§2).
2. Что уже есть в шине и в АБС? Самый недооценённый вопрос: стандартные модули (§5) и каталог (§6) закрывают большую часть инфраструктуры.
3. Что пишем мы? Какие операции у сервиса, что каждая принимает и возвращает и что уходит в АБС.
4. Синхронно или асинхронно, и что будет, если сосед не ответит? Человек ждёт у экрана - синхронно и быстро. Долгая операция или внешняя система, которая отвечает когда захочет, - асинхронно, с результатом по B.QCTX.ID.

У большинства задач уже есть сложившийся тип решения:

Пример: электронный кошелёк. Банк запускает кошелёк в мобильном приложении: регистрация, пополнение с карты, перевод другому клиенту. Разбор по вопросам:

1. Клиент - мобильное приложение. Оно ходит только в ядро, сессию проверяет AuthMngr.
2. Сервисы клиентов, счетов и платежей уже есть; в каталоге есть и сервис кошельков - сначала смотрим его.
3. Операции: регистрация (POST), чтение кошелька (GET), пополнение и перевод (POST), статус операции (GET). Деньги, резерв и проводки - в АБС, а не в сервисе.
4. Регистрация и перевод внутри банка - синхронно. Пополнение с карты зависит от внешнего процессинга - асинхронно: сразу «принято», статус позже.

Во всех таких решениях повторяется одно и то же: бизнес-логика живёт в сервисе, а вход, авторизация, кеш, очередь и связь с АБС уже есть в шине. Начинать надо с контракта, а не с кода, и ваш код встаёт на шаг 7 пути запроса. Ровно это от вас ждут в ДЗ-1 - только задача будет вашей.

8. Что дальше

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

Домашнее задание

ДЗ-1 подготовительное, без кода и без коммита в GitLab. На этом шаге репозитория с сервисом ещё нет, и мы проверяем не код, а продуманность вашего будущего сервиса: его документацию (домен, сущности, методы, связь с АБС). Этот документ станет основой README вашего проекта во втором уроке.

Проверьте себя

• Чем шина лучше прямых связей «каждый с каждым».
• Что такое модуль и чем он отличается от реплики.
• Зачем в каждом запросе два объекта, Base и Service.
• Что произойдёт, если сервис не зарегистрировался в ядре.
• На каком шаге пути запроса работает ваш код.
• Какие четыре вопроса задать себе, прежде чем проектировать сервис под бизнес-задачу.

Про каталог и документацию:

• Чем локализованный сервис отличается от кастомизированного и где это видно в GitLab.
• Почему один и тот же сервис существует в контурах двух банков и что из этого следует.
• С какого раздела документации вы начинаете чтение и почему именно с него.
• Что можно понять о сервисе по одной таблице его конфигурации.
• Каких двух вещей в документации сервиса обычно нет.

Глоссарий: модуль, реплика, ядро (шлюз), Base, Service, BaS, реестр сервисов, AuthMngr, GenericService, CBSMQ.