Рус Eng Cn Перевести страницу на:  
Please select your language to translate the article


You can just close the window to don't translate
Библиотека
ваш профиль

Вернуться к содержанию

Программные системы и вычислительные методы
Правильная ссылка на статью:

Единый формат спецификации в качестве 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

DOI:

10.7256/2454-0714.2022.4.39235

EDN:

MFEXNN

Дата направления статьи в редакцию:

23-11-2022


Дата публикации:

30-12-2022


Аннотация: Объектом исследования являются протоколы взаимодействия (API - Application Programming Interface) микросервисов. API микросервисов является важным объектом разработки, т.к. микросервисы создаются разными командами разработчиков и, не смотря на это, могут быть зависимы друг от друга. Для построения единой системы взаимодействия микросервисов использована методология синхронизации протоколов общения серверных приложений API-First. Целью работы является создание метода разработки API микросервисов серверных java-приложений с использованием библиотек spring. Метод основывается на том, что API декларируется как главная часть разработки микросервисных приложений и поэтому создается на начальном этапе проектирования. Предложен подход, основанный на едином API микросервисов и технике тестирования TDD, повышающий эффективность управления разработкой серверных java-приложений. API микросервисов создается с использованием спецификации в качестве API-артефакта. Разработанная методика позволяет: использовать созданный API другой командой независимо от языка проекта; увеличить производительность команд разработки; качественно документировать методы и модели; уменьшить объем ручного написания программ, т.к. код генерируется автоматически из спецификации; выявить ошибки дизайна API раньше, чем в традиционном подходе к проектированию (code-frist) за счет применения TDD и работы с API до его реализации.


Ключевые слова:

API, API-First, code-frist, тестирование, техника TDD, микросервисы, сервер приложений, цикл разработки, Rest клиент, spring

Abstract: The object of research is the interaction protocols (API - Application Programming Interface) of microservices. The microservices API is an important development object because each microservice can be a client for any other microservice and be created by a separate team. To build a unified system of interaction between microservices, the API-First methodology for synchronizing communication protocols for server applications was used. The aim of the work is to create a way to develop API microservices of server java applications using spring-boot, spring-web, openapi-generator, springdoc libraries. The method is based on the fact that the API is the most important part of the product and therefore is created at the initial design stage. An approach based on a single microservices API and TDD testing technique is proposed, which increases the efficiency of managing the development of server-side java applications. The microservices API is built using the specification as the API artifact. The developed technique allows: use the created API by another team, regardless of the development language; increase the productivity of development teams; to carry out a qualitative description of methods and models; reduce the amount of routine code by generating code from the specification; identify API design errors earlier than with the standard development approach (API after implementation) by applying TDD and working with the API before it is implemented.


Keywords:

API, API-First, code-frist, testing, TDD technique, microservices, Application server, development cycle, Rest client, spring

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.

https://habrastorage.org/r/w1560/getpro/habr/upload_files/379/b21/684/379b216849d6240f697b3ed4e628b005.png

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Библиография
1. Мехди Меджуи, Майк Амундсен, Ронни Митра, Эрик Уайлд. Непрерывное развитие API. Правильные решения в изменчивом технологическом ландшафте — СПб: Питер, 2021.
2. Janet Wagner. Understanding the API-First Approach to Building Products — URL:https://swagger.io/resources/articles/adopting-an-api-first-approach (date of access: 23.11.2022).
3. Agile-манифест разработки программного обеспечения — URL: http://agilemanifesto.org/iso/ru/manifesto.html (date of access: 23.11.2022).
4. Полянин М. Что такое Design first и Code first // Код(журнал Яндекс Практикума).–2020. — URL: https://thecode.media/design-first/ (date of access: 23.11.2022).
5. Волушкова В.Л. — Интеграция разнородных данных в корпоративных информационных системах // Программные системы и вычислительные методы. – 2019. – № 1. – С. 81-90. DOI: 10.7256/2454-0714.2019.1.28768 URL: https://nbpublish.com/library_read_article.php?id=28768
6. Beck K. Test-Driven Development by Example – Addison Wesley, 2003.
7. Eric Elliott TDD Changed My Life — URL: https://medium.com/javascript-scene/tdd-changed-my-life-5af0ce099f80 (date of access: 23.11.2022).
8. OpenAPI Specification — URL: https://swagger.io/specification (date of access: 23.11.2022).
9. Волушкова А. API-First и микросервисы — URL: https://habr.com/ru/company/axenix/blog/694340 (date of access: 23.11.2022).
10. Spring Cloud OpenFeign — URL: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html (date of access: 23.11.2022).
11. Swagger UI — URL: https://swagger.io/tools/swagger-ui/ (date of access: 23.11.2022).
References
1. Medjaoui M., Amundsen M., Mitra R., Wilde E. (2021). Continuous API Management. SPB: Piter.
2. Janet Wagner. (2020). Understanding the API-First Approach to Building Products. Retrieved from https://swagger.io/resources/articles/adopting-an-api-first-approach.
3. The Agile Software Development Manifesto. Retrieved from http://agilemanifesto.org/iso/ru/manifesto.html.
4. Polyanin M. (2020). What is Design first and Code first in Code (Yandex Practicum magazine). Retrieved from https://thecode.media/design-first/
5. V.L.Volushkova — Integraciya raznorodnyh dannyh v korporativnyh informacionnyh sistemah // Programmnye sistemy i vychislitel'nye metody. – 2019. – № 1. – С. 81-90. DOI: 10.7256/2454-0714.2019.1.28768 URL: https://nbpublish.com/library_read_article.php?id=28768
6. Beck K. (2003). Test-Driven Development by Example. Addison Wesley.
7. Eric Elliott. (2019). TDD Changed My Life. Retrieved from https://medium.com/javascript-scene/tdd-changed-my-life-5af0ce099f80.
8. OpenAPI Specification. Retrieved from https://swagger.io/specification.
9. Volushkova A. (2022). API-First i mikroservisy — URL: https://habr.com/ru/company/axenix/blog/694340.
10. Spring Cloud OpenFeign. Retrieved from https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html.
11. Swagger UI. Retrieved from https://swagger.io/tools/swagger-ui/.

Результаты процедуры рецензирования статьи

В связи с политикой двойного слепого рецензирования личность рецензента не раскрывается.
Со списком рецензентов издательства можно ознакомиться здесь.

Предметом исследований является способ создания корпоративных приложений, при котором API имеет самый высокий приоритет и создается на начальном этапе проектирования. В статье подробно описывается алгоритм создания и тестирования микросервисов с использованием спецификации в качестве API-артефакта. Рассмотрен принцип практического создания единого формата спецификации в качестве API-артефакта микросервиса при определенных допущениях. А, именно: а)приложение с API состоит из двух проектов – создание API и реализация API; б)API-спецификация представляет собой SNAPSHOT API, который является отдельным артефактом. Изменения API означают сначала изменение API-спецификации, от которой зависят реализующий API сервис и приложения-потребители. Команды, создающие клиентские приложения, забирают измененный артефакт API. Затем они проверяют, подходит ли команде созданное API. Параллельно, опираясь на спецификацию API, создающая сервисы команда имеет возможность формировать тесты для API.
Разработка интерфейса представляет собой законченный проект. Поэтому команда, создающая приложение, использующее API, и команда, реализующая сервис интерфейса, имеет возможность проверить правильность спецификации и создать release артефакт API.
Предложен процесс разработки с использованием архитектуры проектирования API-First и техники TDD. Такой способ проектирования по мнению авторов разработки позволяет добиться следующих преимуществ. прежде всего появляется возможность использовать разработанное API другой командой независимо от используемого языка проекта. Это вызовет существенное сокращение трудовых затрат и длительности выполнения проекта. Кроме того, предлагаемый подход позволяет выполнять одновременное создание различных частей проекта. Тестировщики, команда создания клиента API и команда разработки сервисов, реализующих интерфейс, могут работать одновременно, используя готовое API, что сокращает в целом длительность разработки. Авторы также предполагают, что их алгоритм созданий позволит не только качественно документировать методы и модели, за счет обязательного предварительного описания интерфейса, но и уменьшать объем ручного написания программ, т.к. код генерируется автоматически из спецификации. Поскольку документация интерфейса имеет удобное визуальное представление (swagger-ui), то собственно разрабатываемая документация и код будут согласованы в силу того, что именно по документации создается программа сервиса. Следовательно, спецификация будет всегда представлена текущей версией. Несомненным преимуществом предлагаемого алгоритма является возможность выявлять ошибки дизайна API раньше, чем в архитектуре проектирования code-frist благодаря использованию параллельного тестирования и работы с интерфейсом до его имплементации. Таким образом минимизируются издержки, вызванные ошибками в документации. Научная новизна в работе отсутствует, так как она направлена на решение конкретной прикладной задачи и не устанавливает новых, ранее не известных научному сообществу, закономерностей и фактов. В то же время работа является актуальной и может быть интересна специалистам, занимающимся создание микросервисов с использованием спецификации в качестве API-артефакта. Стиль, структура и метод подачи материала является дискуссионным и нуждается в логической корректировке. Но, это мнение рецензента является частным и не снижает практической ценности смыслового содержания статьи, которая может быть опубликована в авторской редакции.