Comments 9
Было бы здорово привести альтернативные генераторы и принцип их работы.
Например, openapi-fetch использует тонкий клиент, и глубокое вычисление типов из результата генерации openapi-typescript (.d.ts-файл) для создания полноценного API-клиента со строгой типизацией.
Схожую идею я реализую в своем генераторе React-хуков для Tanstack Query - openapi-qraft.
А за статью - спасибо. По работе с OpenAPI на frontend, мне кажется, довольно мало статей.
Парочка вопросов:
1. Как описыватеся или генерируется сам контракт.. руками? swagger-editor? комментрии в роутах?
2. Если фронт и бек пишут разные люди - как фронт-команда узнаёт что контракт изменился и нужно пересоздать "клиент"?
Если фронт и бек пишут разные люди - как фронт-команда узнаёт что контракт изменился и нужно пересоздать "клиент"?
Обычно генерируемый код (в данном случае клиент) не хранится в гите, а создаётся из актуального контракта при каждой сборке. Таким образом при несовместимых изменениях контракта проект автоматически ломается и вы узнаёте что и в каких местах надо чинить. Собственно это как в коде поменять какой-то интерфейс и посмотреть ошибки.
Хорошие вопросы, спасибо! Боюсь, что я не смогу полностью на них ответить, но постараюсь.
По первому вопросу у меня есть опыт в двух вариациях:
Когда контракты ручками с помощью swagger-editor составляют системные аналитики и они хранятся в гите.
Когда контракты генерируют бэкенд-разработчики.
И ответ на второй вопрос также будет в двух вариациях:
Когда контракты готовят системные аналитики, то они ссылаются на них в документации реализуемых фич. А системную документацию согласовывают с разработчиками.
Когда контракты генерируются бэкенд-разработчиками, они также должны крепится к задаче на фронт.
На практике и тот и другой вариант зависит только от того, насколько хорошо работают процессы в команде. Например, первый вариант в одной команде у меня не вызывает никаких проблем, а второй вариант в другой еще как вызывает, так как я постоянно бьюсь с предоставлением и содержанием этих контрактов.
И да, когда контракт обновляется нужно клиент генерировать заново.
@meonsou приветсвую! Я, кстати, не слышал, что генерацию API встраивают в pipeline. Технически это вопросов не вызывает. И да, в этом варианте, если контракт будет изменен, пайплайн упадет, если не будет сделано необходимых изменений на фронте. Таким образом это представляется дополнительной проверкой при деплое, но клиент все равно нужно генерировать руками для разработки или я не правильно вас понял?
Спасибо за ответы.
И да, когда контракт обновляется нужно клиент генерировать заново.
Вот тут не совсем ясен флоу. Был контракт, что возвращается поле user_messages. Потом бекенд-команда переименовала его на userMessages (примем, что они не забыли поменять аннотации в коде, или отредактировать в сваггер-эдиторе).
Факт смены поля.. об этом как-то сообщается, и если да - то в какой момент времени?.. например в слак "парни, мы поменяли поля - все пересоздайте у себя клиенты и поправьте маппинг!"
Или же оно должно дойти до qa или pipeline, там упасть, и только потом вернуться на фронт команду с отдельной задачей - чтоб те пересоздали клиенты и поправили маппинг?
В хорошем рабочем процессе, контракты обновляются на системном анализе продуктовой или технологической задачи. Все контракты должны быть согласованы разработчиками бэка и фронта до перехода в разработку.
Но бывает так, что системный анализ не предусмотрен штатом сотрудников, тогда за контракты отвечают разработчики бэкенда. Хорошим тоном будет согласовывать контракты при разработке бэкенда с фронтом, но и этого может не быть.
Если согласования контрактов нет, то фронт должны уведомить об изменениях.
Но бывала у меня практика, когда обновленный бэк просто проезжал дальше. Тут уже остается уповать на QA.
Чтобы наверняка узнать на фронте, что контракт поменялся, а вам об этом не сообщили, нужно использовать проверку runtime-типов.
Чтобы наверняка узнать на фронте, что контракт поменялся, а вам об этом не сообщили, нужно использовать проверку runtime-типов.
Я плавно подводил к этому)
Как вы считаете, если учесть что:
- фронт и бек пишут разные команды, может даже распределённые географически и во времени
- фронт и бек это разные репозитории
- факт согласования контракта\апи присутствует в любом случае, между лидами фронта\бека или с участием аналитика - неважно
- необходимость шага - оповещения фронт-команды про обновление контракта
- как следствие, необходимость шага - фронту "поправить код" (в рамках отдельной задачи, или в попыхах неважно)
Верно ли следующие, что:
Проще и надёжнее фронтам описывать контракт в своей кодовой базе и валидировать его в рантайме (условный zod делает это в одно "приседание"), и не доверять апи-респонсам также, как и не доверять пользовательскому вводу, поскольку это пограничные слои приложения. Да, будет некое дублирование кода во фронт\бек командах. Зато не будет дополнительного "непонятного\мусорного" кода 50-100кб на фронте. Да, не будет удобной(?) странички сваггера со всеми эндпоинтами, которую бек должен не забывать обновлять. Зато у фронта будет свой, написанный собственноручно контракт со всеми "ручками", а своему коду доверия больше как-то)) И самое главное, что при смене контракта - количество телодвижений остаётся ровно столько же, т.е. два - оповестить фронт, и поправить код фронта. И инструменты вроде swagger-typescript-api никакой рекламируемой автоматизации особо не добавляют (учитывая список моментов выше).
Почему я затеял эту дискусию.. потому что у меня часто подгорает когда на проектах 2+ года всеми любимый сваггер не соответствует действительности.. потому что это завязано на дисциплину бекенд-разработчиков. А фронт страдает.. че не работает?.. а блин Петя забыл аннотацию поправить и вообще сказать что он поменял поля этого ответа чуть-чуть))
Я не писал про автоматизацию, только про генерацию)) Для генерации нужна основа, поэтому контракты для этого нужно хранить в кодовой базе. Но я бы не стал их писать самостоятельно, так как не фронты делают ручки.
К сожалению, такова реальность, что именно на фронте пользователи ловят ошибки, поэтому и летит все в сторону фронта. Опять же, если нет грамотного процесса разбора багов.
И я с вами соглашусь, что единственный способ сразу отловить ошибки из-за расхождения контракта - это runtime-валидация с грамотным пользовательским интерфейсом, который сразу отобразит причину.
Работа с REST API при помощи swagger-typescript-api