Версионирование API или единая кодовая база для всех версий14.09.2021 16:46

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

Типовая реализация API и ее перевод на версионирование Blueprints

Несколько лет назад была популярна вирусная реклама про внутренности кофе-машин, банкоматов и прочих аппаратов, которая показывала их «грязное нутро».

Типичная реализация API

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

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

Вынесение подсистем API

В слое, согласующем эту «пару» интерфейсов, надо реализовать три системы. Во-первых, систему конфигурации данных, которая умеет брать сериализованные DTO, превращать их в модели, отдавать на бэкенд и из ответа бэкенда формировать понятные клиентам API данные. Во-вторых, cистему конфигурации эндпоинтов, которая занимается маршрутизаций, ограничением доступа, описанием входных и выходных данных, а также описанием фильтров и сортировки коллекций. В-третьих, систему управления версиями, которая собирает две предыдущие подсистемы на основе конфигов, полученных из папки с запрошенной версией.

Теперь рассмотрим, как нюансы реализации API описывать в конфигах. Разработчики SuperJob используют для конфигурационных файлов API формат yaml, вы можете использовать любой, который вам нравится.

В примере ниже — конфиг эндпоинтов для RESTful реализации API. Секция endpoints содержит все эндпоинты API, два уровня ее подсекций содержат URI ресурса и методы HTTP, которые реализованы для данного ресурса. В случае реализации на основе RPC вместо URL и HTTP-метода достаточно указать название метода API (например, getUsers). Далее идет описание работы эндпоинта и его связь с кодом бэкенда.

Секция class служит для указания обработчика. Вы можете завести вместо этого две секции: controller и action, для обработки запросов, свойственных некоторым фреймворкам.

Секция query содержит информацию о запросе, который ожидает эндпоинт, в данном примере — описание поддерживаемых фильтров и сортировок. Секция out в данном примере описывает возвращаемые эндпоинтом сущности: коллекцию пользователей.

Секция constraints пригодится для запросов на изменение, в ней можно описать ограничения на доступ к функционалу эндпоинта. Валидаторы для входных данных и доступа можно описать в подсекции validation, указав класс и входные параметры (в примере константный параметр с названием проверки и указание где в payload брать второй параметр, userId):

Конфигурация эндпоинтов

# /configs/1.0/endpoints/config.yml (REST)

endpoints:
    /user/:
     	get:
      	class: app\actions\GetUserAction
        query:
          filters:
            town: Town[] required
          sort: [nickname, birthdate]
        out: User[]
      patch:
        class: app\actions\UpdateUserAction
      	constraints:
      		validation:
          	class: validators\AccessValidator
          	parameters:
          		rule: editProfile
          		userid: body:user.id 

Вариант кода запроса коллекции пользователей для этой конфигурации:

Запрос коллекции пользователей

repository->find(
        $filter,
        $sort
    );

    //…
    return $this->format($users);
	}

}

Пример кода конвертации DTO в модели и обратно:

getBody());

//…

$user = UserHydrator::fromDto($userDto);

//…

/**
* @var UserRepository $repository
* @var User $user
*/
$user = $repository->save($user);

//…

$userDto = UserHydrator::toDto($user);

//…

return json_encode($userDto);

# файл /config/1.0/dataMapper/entities.yml 
entities:
	User:
  	model: orm\User
    repository: orm\UserRepository
    attributes:  
        nickname:
          type: string required
        	getter: getLogin
    relationships:
        towns:
        	type: Town[]
        	getter: getTowns
          setter: getTowns

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

В редких случаях может возникнуть необходимость дополнительного использования Feature-версионирования. Feature прикрепляют к версиям, и в дальнейшем их активность можно проверить в коде бэкенда и коренным образом изменить его поведение. За 12 версий разработчиками SuperJob было внедрено всего 3 Feature. Например, чтобы после первых двух версий запретить HTTP-методу использовать PUT, который не поддерживается стандартом JSON: API.

Без чего не обойтись при реализации

Вот набор некоторых инструментов и библиотек, которые сэкономят вам время, при реализации такого способа версионирования.

1. Для того что бы превратить конфигурацию в набор абстракций вашего метаязыка описания API, вам потребуется парсер. Исторически сложилось, что при разработке в Superjob использовался Peg парсер, хотя есть и другие реализации парсеров. Например, AST Parser — возможно вам он подойдет больше.

2. Чтобы не собирать раз за разом слепок API для нужной версии, удобнее воспользоваться автогенерацией и закэшировать готовые абстракции, например, с помощью nette/php-generator.

3. Для превращения DTO в нужные модели и обратно подходит любой конвертер/билдер, например, JMSSerializer. Но у него есть свои недостатки — при большом количестве ответов он работает медленно и довольно тяжелый в плане поддержки. Поэтому в SuperJob перестали им пользоваться, а написали свой сериалайзер Hydrator, который быстро конвертит все сущности. Но для начала вполне подойдет JMSSerializer, тем более, что на него много документации в интернете. .

4. Имея конфиги, вы можете по первому же изменению их файлов обновлять документацию в формате OpenApi тем же Swagger«ом.

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

Преимущества версионирования Blueprints

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

Документация тоже создается автоматически — как спецификации самого API, так и, например, истории изменений (changelogs). А выпуск новой версии — это просто копирование папки с разрабатываемой версией в папку с названием новой версии. При этом она сразу становится доступна. Поэтому выпуск новых версий можно вынести в автоматику CI/CD и разработчикам не придется отвлекаться от своих задач.

Недостатки версионирования Blueprints

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

Есть еще один небольшой минус — у спецификаций в IDE нет поддержки. После того, как разработчики SuperJob изобрели свой метаязык конфигураций, его поддержку им тоже пришлось реализовывать самим. Но делать плагины под PHPStorm — очень интересное дело. В результате у них теперь работает поиск использования и автозамена для класса. В конфигах тоже все меняется, указывается и подсвечивается, например, в каких версиях этот класс используется. Пока нет только автоподстановки, но они планируют ее разработку в ближайшем будущем. В конфигах тоже все меняется, указывается и подсвечивается — например, в каких версиях указанный класс используется. Пока нет только автоподстановки, но они планируют ее разработку в ближайшем будущем.

Тестирование версий

Как тестируют версии API в SuperJob? Для функционального тестирования версий API используется тестовый фреймворк Behat. Команда SuperJob немного расширила его функционал и помечает тестовые сценарии тэгами с версиями, для которых он применим. Соответственно, на тестовой сборке каждый сценарий запускается для каждой версии, которая активна и попадает в указанный для сценария диапазон версий.

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

Сначала проиллюстрируем проблему:

Тестирование версий

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

Вот так выглядели графики тестовых прогонов до того, как команда SuperJob начала использовать Impact-анализ:

Графики тестовых прогонов до использования Impact-анализа

Каждая ступень на графике (выпуск новой версии) — это плюс 2,5 тысячи тестов. И если на первых версиях затраченное на тесты время находилось в диапазоне 12–13 минут, то через три версии это уже было полчаса. Бесконечно ставить костыли, горизонтально масштабировать, раскидывать по фича-файлам, которые можно запустить в разных процессах параллельно, — все равно не получится. Чем больше версий вы поддерживаете, чем больше функционала докидываете, тем дольше проходит стадия тестирования, а следовательно — и релиза. На этом этапе разработки API и оптимизации тестов разработчики и обнаружили в коде жемчужину.

У вас есть сценарий, который вы гоняете по нескольким версиям, чтобы проверить, что он не падает, но сам сценарий неизменен. У него одинаковые исходные условия и условия проверки для всех версий. Код, который не зависит от версии, вы вынесли отдельно. Сама API не меняется от версии к версии, бэкенд — тем более, а ваши версии отличаются только тем, что лежит в конфигах.

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

Допустим, второй сценарий разработчики долго не трогали, он работал с одним и тем же набором конфигов. Четвертый сценарий не менялся на протяжении двух версий, а пятый — на протяжении трех. Благодаря Impact-анализу можно выкинуть лишние прогоны по версиям и на этом искусственном примере получить в два раза меньше прогонов:

Impact-анализ

Все зависит от того, насколько различаются ваши версии. Impact-анализ позволяет тестировать только реальные изменения между версиями.

Несмотря на то, что в API Superjob продолжали добавляться версии, а количество тестовых сценариев перевалило за две с половиной тысячи, после внедрения Impact-анализа продолжительность сценариев стабилизировалась на 20-ти минутах:

Графики тестовых прогонов после Impact-анализа

Заключение

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

Все эти находки могут быть применены в других системах. А в SuperJob уже планируют новые доработки.

Видео выступления Антона Золотилина на конференции PHP Russia 2021.

Открытая трансляция главного зала Saint HighLoad++ будет возможна благодаря поддержке ЦФТ. Для доступа к трансляции вам нужно только зарегистрироваться.

За 2 дня это будут 14 докладов. Смотрите расписание.

© Habrahabr.ru