Внутренние и внешние интеграции

Создание интеграций

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

lino integration new --name <ServiceName>
lino integration list

Используйте integration list, чтобы проверить существующие интеграции перед созданием новой. Избегайте универсальных интеграций, таких как CommonIntegration, потому что они склонны накапливать обязанности без четкой границы.

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

• Называйте по интегрируемому контексту: предпочитайте Billing, Identity, Catalog или Shipping универсальным именам.
• Отделяйте контракт от реализации: домен и приложение не должны напрямую зависеть от деталей транспорта.
• Предполагайте внешние сбои: любая удаленная интеграция может стать медленной, недоступной, вернуть частичную ошибку или изменить контракт.

Resources интеграции

Resources представляют объекты, которые интеграция предоставляет или потребляет, например customers, invoices, tenants, subscriptions, users или documents.

lino integration resource new --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino integration resource list --service <ServiceName> --module <ModuleName> --entity <EntityName>

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

• Моделируйте resource с использованием словаря интегрируемой системы.
• Не раскрывайте внутренние сущности как внешний контракт.
• Определите, какие поля являются идентификаторами, фильтрами и возвращаемыми данными.
• Документируйте пагинацию, аутентификацию и лимиты вызовов, если они существуют.

Когда resource представляет данные другого модуля, включайте только то, что необходимо потребителю. Тот же принцип появляется в shadow entities: потребляющий модуль хранит небольшую локальную копию, согласованную со своим Use Case, вместо зависимости от полной модели модуля-производителя.

Операции интеграции

Операции описывают действия, доступные для интеграционного resource: создать, запросить, обновить, отменить, отправить, синхронизировать или проверить.

lino integration operation new --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino integration operation list --service <ServiceName> --module <ModuleName> --entity <EntityName>

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

• Запросы должны иметь timeout и обработку недоступности.
• Удаленные команды по возможности должны быть идемпотентными.
• Внешние сбои не должны нарушать основную транзакцию, если бизнес допускает асинхронную обработку.
• Используйте логи и correlation id для трассировки вызовов между системами.

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

Потребление интеграций

После моделирования интеграции, resource и операции используйте потребление, чтобы подключить приложение к сгенерированному контракту. Цель — сделать так, чтобы Use Case зависел от именованной абстракции с предсказуемым входом и выходом, а не распределять HTTP-вызовы, сборку URL, headers, parsing ответа и обработку ошибок по нескольким handlers.

lino integration consume

Use Cases должны зависеть от абстракций, а не от деталей HTTP, разбросанных по коду. Это упрощает тестирование, замену реализации и единообразную обработку сбоев. Также это предотвращает ситуацию, когда каждый endpoint приложения заново и по-своему реализует timeout, аутентификацию, correlation id, сериализацию и сопоставление ошибок.

• Проверяйте данные перед вызовом внешнего сервиса.
• Используйте cancellation token и timeout.
• Сопоставляйте внешние ответы с предсказуемыми внутренними ошибками.
• Не сохраняйте сырой внешний payload как доменное правило без преобразования.

HTTP vs. in-process

In-process интеграция проста и быстра, когда модули выполняются вместе. HTTP создает более явный контракт между процессами, но добавляет задержку, сетевые сбои и необходимость устойчивости.

In-process интеграция не должна означать свободный доступ ко всему. Даже в одном runtime потребитель должен общаться через контракт, а не через внутреннюю сущность, DbContext или repository другого модуля. Стоимость сети ниже, но риск связанности остается.

HTTP лучше подходит, когда производитель и потребитель имеют разные runtimes или когда нужно сделать границу операционно явной. In-process подходит, когда одно приложение размещает контексты и ответ нужен немедленно, при условии что зависимость по-прежнему объявляется через контракт.

События vs. синхронные интеграции

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

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