Две системы называют сущность «клиентом», но используют разные правила и статусы. Как спроектировать интеграцию, чтобы модель одной системы не загрязнялась понятиями другой?
Используйте антикоррупционный слой — отдельный адаптер или компонент интеграции, который преобразует модель, термины, статусы и правила внешней системы в понятия локального домена. Локальная модель не должна напрямую принимать чужие сущности и значения только потому, что они похожи по названию.
Такой слой определяет явное соответствие между моделями, валидирует входные данные, преобразует состояния и фиксирует неоднозначности. В результате изменения внешней системы локализуются в интеграции, а не распространяются по бизнес-логике принимающей системы.
Подход сформировался в рамках предметно-ориентированного проектирования как средство интеграции систем с несовместимыми моделями предметной области. Исходная проблема заключалась в том, что прямое отображение чужой модели постепенно переносило её термины, ограничения и ошибки в собственную систему.
Антикоррупционный слой не означает, что одна модель считается плохой. Он защищает границы конкретного домена: одно и то же слово может иметь разный смысл, жизненный цикл и набор допустимых состояний в разных системах.
Например, CRM считает клиента потенциальным до первой сделки, а биллинговая система создаёт клиента только после прохождения проверки и присвоения платёжного профиля. Если напрямую передавать статус из CRM в биллинг, значение может не иметь эквивалента или привести к неверному бизнес-решению.
Прямое связывание моделей создаёт несколько рисков:
Сначала нужно определить границы каждой модели и владельца каждого значения. Для каждого объекта фиксируют не только соответствие полей, но и смысл: идентификатор, обязательность, допустимые состояния, единицы измерения, формат дат, правила удаления и источник истины.
Затем вводится локальный контракт интеграции. Он может принимать внешнее сообщение, преобразовывать его во внутреннюю команду или событие и возвращать наружу отдельный внешний формат. Внутренняя бизнес-логика работает с собственными терминами, а не с объектами внешней системы.
Преобразование статусов обычно не является простым переименованием. Для каждого внешнего состояния определяют соответствующее локальное состояние, возможное отсутствие соответствия и обработку неизвестного будущего значения. Если несколько внешних статусов сводятся к одному локальному, обратное преобразование может быть невозможным — это нужно явно учитывать.
Антикоррупционный слой также должен отделять техническую ошибку от смысловой. Неверный формат, неизвестный статус и нарушение локального бизнес-правила требуют разных реакций: повторной доставки, сообщения об ошибке интеграции или ручного разбора.
Подход имеет цену. Появляется дополнительная модель преобразования, дублируются некоторые данные и возрастает объём документации. Однако это обычно дешевле, чем зависимость всего домена от нестабильной или чужой семантики.
Не следует превращать слой в универсальную модель для всех систем без необходимости. Такая модель часто становится компромиссной, теряет точность и усложняет изменения. Если интеграция простая и модели действительно совпадают по смыслу, достаточно обычного адаптера; отдельный антикоррупционный слой оправдан при заметном различии терминов, правил или жизненного цикла.
Интернет-магазин получает сведения о покупателе из CRM, а передаёт их в систему противодействия мошенничеству. В CRM статус «активен» означает наличие действующей маркетинговой записи, тогда как проверочная система использует состояния «не проверен», «проверен», «заблокирован» и «проверка устарела».
Рассматривались три варианта. Прямая передача CRM-статуса была бы быстрой, но не отражала бы смысл проверки. Единая общая модель уменьшила бы число преобразований, однако потребовала бы согласовать разные жизненные циклы и стала бы зависимостью для обеих систем. Передача исходных и локальных статусов одновременно сохранила бы больше информации, но создала бы риск, что потребители начнут смешивать их.
Выбрали адаптер с отдельной моделью запроса на проверку. Он хранит внешний идентификатор CRM, преобразует только нужные атрибуты, не передаёт маркетинговые статусы как статусы проверки и явно обрабатывает неизвестные значения. Внутренняя система принимает решения только по своим состояниям, а изменение справочника CRM требует корректировки адаптера и его контрактных тестов, но не всей бизнес-логики.
1. Обязательно ли антикоррупционному слою преобразовывать каждое поле внешнего объекта?
Нет. Он должен преобразовывать только данные, необходимые локальному сценарию, и сохранять семантически значимые сведения. Механическое копирование всех полей увеличивает связанность и создаёт ложное ощущение, что модели эквивалентны.
При этом нельзя отбрасывать данные, нужные для аудита, дедупликации или повторной обработки. Решение о сохранении поля принимают по его локальному назначению и требованиям к трассируемости, а не по принципу «передадим всё» или «оставим минимум».
2. Что делать, если внешняя система прислала статус, которого ещё нет в локальной модели?
Нельзя молча преобразовывать его в наиболее удобное состояние: это может привести к неверному бизнес-решению. Систему следует сделать устойчивой к неизвестным значениям — например, отклонить конкретное сообщение с диагностикой, поместить его в очередь разбора или перевести объект в безопасное техническое состояние.
Выбор зависит от критичности операции. Для финансового решения безопаснее остановить обработку и привлечь владельца интеграции, чем принять неизвестный статус как подтверждённый. Одновременно нужно наблюдение за такими случаями и совместимое расширение справочника.
3. Где должна находиться логика преобразования: в отправителе или получателе?
Логика, защищающая модель получателя, обычно находится на его стороне либо в компоненте, которым он управляет. Получатель лучше знает, какие значения допустимы в его домене и какие преобразования сохраняют смысл.
Часть преобразований может выполняться отправителем для формирования стабильного внешнего контракта, но это не отменяет защиту на границе получателя. Нельзя полагаться только на договорённость, что отправитель всегда будет передавать данные в удобном формате: его версия, ошибки или новый потребитель могут изменить условия.