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

Любая система больше простого сайта состоит из модулей: каталог, заказы, оплата, склад, уведомления, отчёты. Часто к ним добавляются внешние системы: 1С, CRM, платёжные сервисы, службы доставки. Каждый модуль может отлично работать отдельно, но проблемы начинаются на стыках: данные передаются не в том формате, один модуль недоступен, и другой зависает, сообщение теряется, и заказ «пропадает». Интеграция модулей — отдельная инженерная задача, которую стоит проектировать заранее.

Контракт между модулями

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

• описан явно, например в спецификации API или схеме сообщений
• версионируется: изменения не ломают существующих потребителей
• включает описание ошибок и их обработки
• согласован командами, которые разрабатывают модули

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

Синхронный обмен

Модуль отправляет запрос и ждёт ответа. Примеры: HTTP-запросы к REST API, gRPC. Подходит, когда ответ нужен сразу: проверить наличие товара, рассчитать стоимость доставки.

Риски: если вызываемый модуль медленный или недоступен, вызывающий тоже начинает тормозить или падать. Защита:

1. Тайм-ауты на все вызовы
2. Повторные попытки с увеличивающейся паузой
3. Автоматический выключатель — прекращение вызовов неработающего модуля на время
4. Запасной сценарий: что делать, если ответа нет

Асинхронный обмен

Модуль отправляет сообщение и продолжает работу, не дожидаясь обработки. Сообщения проходят через брокер — очередь сообщений, например RabbitMQ или Kafka. Подходит, когда результат не нужен немедленно: отправить уведомление, передать заказ в учётную систему, обновить аналитику.

Преимущества:

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

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

Идемпотентность

Сообщение может прийти дважды: сеть оборвалась после обработки, и отправитель повторил. Если повторная обработка создаёт второй заказ или второй платёж — это серьёзная ошибка. Решение — идемпотентность: каждая операция имеет уникальный идентификатор, и повторная обработка с тем же идентификатором ничего не меняет. Это одно из ключевых правил надёжной интеграции, особенно для платежей.

Согласованность данных

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

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

Обработка ошибок

Для каждой интеграции продумайте:

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

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

Тестирование интеграций

• Контрактные тесты — проверяют, что модуль соответствует контракту, без запуска второй стороны
• Интеграционные тесты — модули запускаются вместе в тестовой среде
• Сквозные сценарии — проверка бизнес-процесса целиком, например от заказа на сайте до документа в 1С
• Тесты на сбои — что происходит, если один из модулей недоступен или отвечает с ошибкой

Наблюдаемость

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

Типичные сбои

• Отсутствие тайм-аутов — зависание всей системы из-за одного модуля
• Двойная обработка сообщений без идемпотентности
• Изменение формата без согласования
• Тихая потеря сообщений без оповещения

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