Всем привет. Меня зовут Владимир Полукеев. Я занимаюсь backend-разработкой более 7 лет. В данный момент являюсь ведущим разработчиком, а также тим лидом разработки в компании «Синимекс». В этой статье я расскажу о сложностях интеграции веб-сервисов друг с другом и поделюсь найденным мною решением.

1. Проблемы интеграции веб-сервисов

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

2. Коммуникация как основа успешной разработки

Микросервисная архитектура — это в первую очередь про коммуникацию веб-сервисов, поэтому для начала предлагаю рассмотреть коммуникацию через призму человеческого взаимодействия. 

Представим группу людей с общей целью. Каждый участник прикладывает усилия (изобразим их векторами), которые в группе людей часто оказываются направленными в разные стороны (см. рис. 1). Причина — отнюдь не дефицит компетентности, а дефицит информации о задаче. Неполные или неточные данные о задаче у каждого из участников приводят к разногласиям при движении к цели.

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

3. Подходы к разработке API: Contract First vs Code First

Веб-сервисы общаются между собой через API. 

При разработке API выделяют два основных подхода:

1. Contract First (сначала контракт): предполагает проектирование спецификации API (то есть контракт) до написания кода.

2. Code First (сначала код): сначала создаётся код, потом на основе реализованной логики генерируется спецификация API.

В действительности, я редко наблюдаю использование подхода Code First — большинство команд предпочитает сначала проектировать интерфейсы взаимодействия, а затем реализовывать логику.

Contract First в теории

В теории Contract First работает так:

1. Проектирование контракта (на этом этапе спецификация API утверждается как контракт, обязательный для соблюдения обеими командами веб-сервиса — frontend и backend).

2. Реализация компонентов

3. Интеграция компонентов

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

Contract First на практике

На практике события часто развиваются несколько иначе.

На первом этапе проектируется контракт API, который передаётся backend и frontend-командам. На этапе реализации backend-разработчики сталкиваются с неучтёнными сценариями использования и неоптимальными моделями данных — это вынуждает их вносить со своей стороны правки в контракт. 

Правки эти вносятся без согласования с frontend-командой, так как предполагается, что API — зона ответственности backend-разработки и backend-разработчики ожидают, что frontend-команда сама следит за вносимыми изменениями в контракт. В реальности же, frontend-разработчики же работают с исходной версией контракта, не отслеживая его изменения. Таким образом, каждая команда работает с контрактом изолированно: frontend создаёт mock-серверы с устаревшей спецификацией API, а backend тестирует сервис через инструменты, эмулирующие запросы клиентской стороны с учетом актуальной спецификации API.

Это приводит к принципиальной проблеме — обе команды продолжают разработку изолированно, каждая из которых предполагает, что партнёры реализуют актуальную для них версию контракта. Когда на этапе интеграции mock-серверы заменяются реальными сервисами, неизбежно появляются ошибки 4xx/5xx, показывая таким образом расхождения в реализациях. Возникают конфликты, решение которых требует дополнительного времени и приводит к срыву сроков.

4. Улучшение процесса разработки: ранняя интеграция

Так почему же Contract First оказался не так хорош на практике? Это связано с тем, что в теории Contract First не учитывает необходимость постоянных доработок контракта и коммуникации между командами. Основная проблема кроется не в инструментах, а в процессах разработки API - если они выстроены плохо, коммуникация нарушается. Именно процессы — а не недостаток компетенций или инструментов — являются источником проблем.

Я выделил два ключевых неэффективных процесса:

1. Разработка API без учета потребностей клиентской части. Часто backend-разработчики создают интерфейсы, удобные для серверной реализации, не согласуя их с frontend-командой.

2. Отложенное тестирование интеграции. Реальная проверка взаимодействия между сервисами происходит после окончания всех работ по разработке. В результате, обе команды сталкиваются с непредвиденными ошибками при попытке «сдружить» независимо разработанные компоненты. Многие ошибки требуют пересмотра уже реализованной логики, что иногда сопоставимо по трудозатратам с полной переделкой функционала.

Оба этих процесса приводят к ошибкам и внеплановым доработкам во время интеграции веб-сервисов. Из этого следует важный вывод:

5. Анализ подходов: интеграция до и после реализации

Проанализируем разные подходы к интеграции и их влияние на трудозатраты с точки зрения процессов.

5.1. Интеграция компонентов ПОСЛЕ реализации: проблемы подхода

Начнём с классики (см. схему на рис. 6): интеграция выполняется после реализации.

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

Изменения в контракте, как правило, не занимают много времени, а вот связанные с ними правки в коде компонентов обычно требуют значительно больше времени — от пары часов до нескольких дней (рис. 7).

5.2 Интеграция компонентов ДО реализации: ключевые отличия

Теперь посмотрим на интеграцию компонентов до реализации в логике Contract First (см. рис. 8).

Предположим, что в этой схеме, так же на этапе интеграции обнаруживается необходимость доработать контракт. Команда вносит изменения и снова интегрирует компоненты. Только после этого, команды переходят к самому ресурсоемкому этапу: реализации внутренней логики компонентов (рис. 9). Таким образом, в схеме работы команд появляется ключевое отличие:

Рассмотрим пример MVP для интеграции компонентов через API: 

1. На сервере создаётся контроллер, который принимает API-запросы и возвращает заранее подготовленные mock-данные; 

2. На клиенте создаётся простая кнопка с базовой стилизацией, которая: отправляет API-запрос, получает данные и отображает их. 

3. Сервер запускается на тестовой среде, позволяя разработчикам клиента протестировать взаимодействие. 

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

5.3. Преимущества MVP и ранней интеграции

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

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

Такой подход создает еще одно неочевидное преимущество: 

6. Итоги

1. Коммуникация между командами критически важна. Без коммуникации трудно обеспечить ожидаемую функциональность и согласованную работу веб-сервисов. 

2. Интегрируйте доработки как можно раньше — это позволяет тестировать взаимодействие компонентов по API и получать обратную связь.

3. API должен быть клиентоориентированным, поэтому привлечение frontend-разработчиков к его проектированию обязательно. 

4. Используйте реальный MVP-сервер вместо mock-сервера для отладки и тестирования frontend-разработчиками клиентского приложения. 

На этом у меня всё, надеюсь, информация оказалась полезной. Приглашаю подписываться на блог нашей компании «Синимекс» на Хабре, чтобы не пропустить наши новые материалы по управлению разработкой.