Единый формат спецификации в качестве API-артефакта микросервиса при использовании API-First

Волушкова Вера Львовна кандидат технических наук доцент, кафедра информатики, Тверской государственный университет 170004, Россия, Тверская область, г. Тверь, пр-д 2-Ой стахановский, 47 Volushkova Vera L'vovna PhD in Technical Science Associate Professor, Department of Computer Science, Tver State University 170004, Russia, Tverskaya oblast', g. Tver', pr-d 2-Oi stakhanovskii, 47 w2lvera@gmail.com Другие публикации этого автора

Волушкова Александра Юрьевна Java Backend Developer, ООО "Аксеникс" 115054, Россия, Московская область, г. Москва, ул. Пл. Павелецкая, д.2,стр.2 Volushkova Aleksandra Yurievna Java Backend Developer, Axenix LLC 115054, Russia, Moscow region, Moscow, Paveletskaya str., 2,p.2 sobakasasha114@gmail.com

API-First - это способ создания корпоративных приложений, при котором API имеет самый высокий приоритет и создается на начальном этапе проектирования ^[1][2]. В корпоративных приложениях важную роль играют микросервисы. При использовании API-First создание сервиса надо начинать именно с API. Это достаточно редкий подход к созданию микросервисов.

Среднестатистический IT менеджер создание API до создания микросервиса считает неэффективным, устаревшим, классическим способом работы над проектом. API-First – это фактически реализация традиционных этапов разработки: анализ, проектирование, разработка. Считается, что не устаревший подход к проектированию – это Agile^[3].

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

API микросервиса имеет собственную последовательность создания, в которой создается API артефакт. В проектируемом сервисе имеется зависимость от артефакта API. Это обеспечивает значимость спецификации в артефакте. Таким образом, очередность разработки API микросервиса подразумевает первоначальное создание API, а затем его реализацию в миросервисе. Приведенный порядок создания сервисов является главным при использовании парадигмы API-First, но не определяет ее. Из определения First следует, что создание интерфейса API является первоочередным этапом в разработке приложений. Зависимость микросервисов от API показана на рис.1.

Рисунок 1. API микросервисов

Создание единого API в рамках API-First позволяет:

· разрабатывать одновременно: использующее API приложение, тесты, имплементацию API;

· разрабатывать на любом языке приложение, использующее API;

· иметь обязательный этап проектирования — разработка API;

· иметь всегда актуальную спецификацию API;

· уменьшить возможность появления ошибок при проектировании;

· уменьшить трудозатраты на проектирование.

Создание единого API может изменить классический цикл разработки code-frist ^[4], заключающийся в том, что API создаётся после создания сервисов. Допустим, внедряется новый микросервис или изменяется API имеющегося сервиса. При этом необходимо, чтобы API спецификация соответствовала бизнес-требованиям. В классическом цикле разработки допускается проверка соответствия API бизнес-требованиям только после имплементации API. При нахождении ошибки в спецификации изменения будут и в спецификации и имплементации API, как показано в ^[5]. Команды тестирования и команды, создающие использующее API приложение, должны ждать окончания создания реализации API. Этот процесс показан на рис.2

Рисунок 2. Процесс разработки в архитектуре проектирования Code first

Архитектура API-First дает возможность уклониться от долгого ожидания команд проектировщиков. Разработанное API необходимо внедрить и в использующее API приложение и в сервис, имплементирующий API. Для успешного продвижения API предлагается применить способ проектирования TDD (test-driven development)^[6][7]. На этапе создания тестов допускается проверка спецификации API.

Можно сказать, что с момента разработки тестов начинается стадия создания новой версии API. При этом создающая клиент команда разрабатывает тесты, в которых вызов API влияет на работу клиентского приложения. В тестах данного этапа итог вызова API воспроизводится при помощи Mock'а. Так имитируется использование API сервиса в дальнейших разработках. С помощью этих тестов можно дополнительно проконтролировать API спецификацию, а именно:

· соответствует ли API условиям;

· имеется ли возможность оптимизировать число вызовов сервиса;

· соответствует ли требованиям передаваемая информация.

Такое тестирование не изменит эффективность команды. Производительность может даже улучшиться, если найдется ошибка.

Тесты могут создаваться как в использующем API приложении, так и в сервисе, имплементирующем API. Тесты в сервисе определяют, возможно ли реализовать требования, заданные в спецификации API, а именно достаточно ли имеющихся и предоставляемых данных. Благодаря тестированию ошибки конструирования API будут обнаружены еще до его создания. Это дает возможность корректировать недостатки дизайна API при его проектировании. API до реализации намного легче изменить, чем сам сервис. Процесс разработки в архитектуре API-First при использовании техники TDD показан на рис.3.

Рисунок 3. Процесс разработки в архитектуре API-First при использовании техники TDD

Если реализующим API приложением является клиентское приложение, сценарий одновременной работы также соблюдается. Frontend-команда начинает работу сразу после выхода финальной версии API. Стенд тестирования развертывается вслед за имплементацией API. Установка сервиса на стенд позволяет команде тестирования начать работу.

Приведенная архитектура проектирования дает всем реализующим API командам работать параллельно. При этом ошибки спецификации API выявляются раньше, чем в архитектуре проектирования Code first .

Процесс создания ПО в архитектуре API-First при использовании техники TDD дает следующие преимущества:

· одновременная работа различных команд разработки;

· корректность документации API, которая не будет отличаться от документации реализации API т.к. имеется специальный продукт API, который реализует сервис, и клиента этого сервиса;

· выявление ошибок API микросервисов до их разработки, т.к. в проектировании выделяется этап создания API по спецификации.

Рассмотрим, как практически создать единый формат спецификации в качестве API-артефакта микросервиса. Примем следующие положения.

Приложение с API состоит из двух проектов – создание API и реализация API.

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

Разработка интерфейса представляет собой законченный проект. Поэтому команда, создающая приложение, использующее API, и команда, реализующая сервис интерфейса, имеет возможность проверить правильность спецификации и создать release артефакт API.

Описание http API выполнено с помощью спецификации OPENAPI 3^[8].

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

· разработка артефакта API;

· формирование моделей на сервере, создание интерфейсов;

· создание кода клиента.

Сборка API артефакта состоит из: проверки спецификации, создания артефакта, публикации артефакта.

Для создания API-проекта необходимо выполнить семь шагов, которые подробно описаны в работе ^[9] .

В репозитории после сборки проектов по формированию интерфейсов появляются API-артефакты. API-артефакты представлены в виде zip-архива. Архив имеет один файл. API-артефакты будут включены как зависимости в наши проекты.

Например, если рассматривать два проекта ApiFirstMockClient, ApiFirstMock и репозиторий nexus, то включение зависимостей представлено на рис. 5.

Рисунок 4. API-артефакты как зависимости

Покажем, как формировать приложение на сервере, используя при этом API в еще одном сервисе. Сборка проекта серверного приложения включает в себя: извлечение API-артефакта из репозитория, распаковка этого артефакта, генерация кода по спецификации и включение его в директорию исходных текстов проекта.

Как выполняется данная последовательность показано в работе ^[9].

В результате выполнения этих четырех этапов в проект будет добавлен этап openApiGenerate. Модели на сервере созданы автоматически на основе спецификации. Так же будут сгенерированы и интерфейсы. К сгенерированным интерфейсам можно обратиться при создании контроллеров.

Рассмотрим создание кода клиента. В данном примере клиент представлен приложением на сервере. Как генерируется серверное приложение описано выше.

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

Подробнее о создании сервера и клиента можно посмотреть в работе ^[9].

Генерация Feign клиента ^[10], который упрощает написание клиентов веб-службы, также подробно описано в ^[9].

В статье рассмотрено создание микросервисов с использованием спецификации в качестве API-артефакта. Предложен процесс разработки с использованием архитектуры проектирования API-First и техники TDD. Такой способ проектирования микросервисов позволяет:

· Использовать разработанное API другой командой независимо от языка проекта.

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

· Качественно документировать методы и модели, за счет обязательного предварительного описания интерфейса.

· Уменьшать объем ручного написания программ, т.к. код генерируется автоматически из спецификации. Документация интерфейса имеет удобное визуальное представление (swagger-ui ^[11]). Документация и код будут согласованы в силу того, что именно по документации создается программа сервиса. Следовательно, спецификация будет всегда представлена текущей версией.

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