Всем привет! Продолжаем наш цикл статей о внедрении подхода Design API First на проектах нашей компании. Ранее мы рассмотрели использование этого подхода, описали плюсы и минусы, узнали, как на практике выглядит проектирование API на примере сервиса аутентификации. Сегодня расскажем о том, как мы встраиваем Design API First в наш конвейер разработки, подробно остановимся на инструментах, помогающих с технической точки зрения организовать этот процесс. Объясним, как реагировать на изменения требований и обеспечивать версионность, а также что использовать для мокирования данных. Рассмотрим различные варианты применения: для нового проекта, для существующего проекта (где изначально был Code First).

Вместе с коллегами из Архитектурного комитета SimbirSoft мы попытались унифицировать процесс поставки изменений в контрактах, таким образом упростив жизнь командам разработки и ускорив внедрение изменений в проектах с «Непрерывной доставкой и/или развертыванием» (Continuous delivery and Continuous deployment). Для проверки жизнеспособности данного подхода в наших условиях мы используем Design API First для проектирования прикладного слоя сервисов API, предназначенных прежде всего для взаимодействия со слоем Frontend. 

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

В разрезе периодических изменений спецификации необходимо применять эти изменения в обоих мирах. Зачастую реальность устроена так, что владельцем контракта является команда Backend, и изменения, вносимые в спецификацию, сначала применяются в API Backend (подход Code First), а затем поддерживаются на стороне Frontend.

Нужно отметить, что при создании небольших программных продуктов такой подход может быть необоснован. Однако в случае итеративной разработки продуктовых решений, сложных многоуровневых систем или платформ, ориентированных на веб и массового пользователя, предполагающих множественные интеграции, последовательный рост и развитие, подход Design API First для разработки API — незаменимый помощник и, как минимум, заслуживает внимания в плане общего знакомства.  

В рамках нашей задачи мы инвертируем поток обновления контрактов (относительно Code First) согласно подходу Design API First.

Это позволит командам frontend-разработки получить оперативные изменения спецификаций и приступить к реализации изменений параллельно с командой Backend. 

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

1. Организационные (например, взаимодействие архитектора, аналитика, разработчика, которые занимаются проектированием спецификации; разработка регламента внесения изменений в спецификацию, уведомление команд о ее готовности и др.).

2. Структурные (хранение артефактов проектирования в Gitlab, настройка Gitflow, изменения в CI/CD).

3. Функциональные (поддержка mock-серверов для актуальных версий спецификации, использование ApiGateway в среде разработки с настроенной на эти сервера маршрутизацией).

Для предварительной оценки сложностей во внедрении подхода Design API First в рабочие процессы, а также с целью выявления «подводных камней», мы использовали способ, похожий на «стрельбу трассирующими» из книги «Программист-прагматик. Путь от подмастерья к мастеру» (Дейв Томас и Энди Хант), то есть создали одно простое программное решение по методологии Design API First.

Предварительно мы определили предметную область: для примера взяли файловое хранилище (Рис. 2), описали функциональные и нефункциональные требования (Таблица 1), описали основные элементы этого сервиса (Таблица 2) и протоколы интеграции (Таблица 3), сформировали список первичных тестовых сценариев использования. 

Таблица 1. Требования к реализации системы.

Таблица 2. Описание элементов системы.

Таблица 3. Протоколы интеграции.

Далее мы разработали эталонную спецификацию OpenSpec и создали необходимые диаграммы взаимодействия по примеру тех, которые описаны в нашей предыдущей статье. Следующим шагом было создание структуры хранилища (Рис. 3).

Мы также апробировали инструментальные средства (mock-server, настройку ApiGateway) и проверили техническую готовность нашей инфраструктуры (CI/CD) поддержать итеративную разработку в рамках Design API First. 

Учитывая доминирование Code First в практической разработке API среди наших команд и текущих проектов, а также издержки Design First, связанных с ошибками проектирования и необходимостью вносить изменения в контракт на этапах написания кода, было целесообразно сразу отработать два сценария:

1. Разработка проекта API идет в парадигме Code First, поэтому мы хотим прибегнуть к подходу Design API First, применяя его для проекта или его части.

2. При реализации спецификаций и сценариев на уровне программирования внести изменение в первоначальный контракт.

Не дожидаясь завершения этапа проектирования, команда Backend написала программное API, руководствуясь первоначальными требованиями в части работы с файлами по традиционному подходу Code First (сценарий 1). Далее взяли спецификацию API для авторизации (описанную в предыдущей статье) и реализовали эту часть программного API согласно спецификации.

После этого мы инициировали необходимость изменения спецификации API по работе с файлами (сценарий 2), провели еще одну итерацию проектирования и разработки, тем самым проверяя готовность команд (аналитики, разработчики, архитекторы) на взаимодействие в ключе подхода Design API First в условиях перехода с Code First или необходимости внести изменения в текущую версию API на поздних этапах (при написании кода согласно полученным артефактам проектирования).

Заключение

Таким образом мы получили систему, которая удовлетворяет всем требованиям, описанным выше, и позволяет продолжать разработку в режиме Design API First.

В наших следующих статьях мы расскажем, как указанные сценарии выше были отработаны командой проектирования API. А также какие изменения потребовалось внести в код проекта Backend для перехода с Code First на Design API First. Небольшой спойлер :) Часть Backend написана на .Net 6, а для генерации моделей мы использовали кодогенераторы Roslyn совместно с NSwag.