Друзья, не думал, что тема еще актуальна в 2021 г., тем более на рубеже 2022.
Начало битвы за фронтенд
Все началось с того, что я задал вопрос «Как передать на бекенд требования к API?» в Хабр вопросах с гипотезой (сразу прошу прощения за профессиональный жаргон):
Если фронты хорошо знают REST, то это реальный профит, когда они сами могут накидать в Swagger ендпойнтов, которые потом утвердит или поправит бекенд. Если добавить сюда удобный редактор в стиле Notion - когда тут же правим и видим превью ендпойнта. А если, еще к нему зацепить Swagger с реализованного бэка потом, и эта штука сделает кросс-валидацию и скажет, где контракт нарушен – то вообще огонь или нет?
И вот, что из этого получилось:
@Vitsliputsli Многие фронтендеры относятся к беку, как к некой обертке для работы с базой данной. Когда такие становится лидом команды и начинают диктовать свои требования беку, начинается ад, проект даже с простым беком превращается в нечто монструозное, разваливающиеся на ходу. Судя по вашим фразам, вы скорее всего один из них.
@AgentSmith Совсем спустился до личных оскорблений и писал про фронтов как про обезьянок. К сожалению, (или счастью) ему стало стыдно и он удалил всю свою ветку, где писал оскорбления. Оставив только вот это:
@AgentSmith Судя по вопросу ты некомпетентен и лидом ты назвал себя сам. Подтвердить свою компетенцию на должность лида ты не можешь.
Из группы Боль Тим Лида в телеграм:
Да я бы даже сказал, что это бредово. Фронты это же обезьяны умеющие только делать запросы и выводить их. Им то д****ды как там все устроено на сервере. Пускать фронт к проектированию API это плохая идея, напроектируют. Еще бы фронт мне диктовал как реализовать API.
Если полистать комментарии, явно чувствуется крайне негативная повестка от вопроса. Я старался быть максимально вежливым, при этом часть собеседников явно не сдерживали эмоций. Это лишь небольшая часть «токсичности» вылитая на фронтов и лично меня. За фронтов обидно :-)
Хотя я @breslavsky старался и приводил множество аргументов:
@breslavsky Мне кажется проблема в том, что некоторые бекенд разработчики, неверно понимают разработку бизнес-логики и разработку интерфейса доступа к ней и к данным. Интерфейс на бекенд может быть HTTP, сокеты ли даже командная строка. Это всего лишь интерфейс. Эти разработчики при проектировании ендпойнта
/loginчасто зашивают в контроллер бизнес-логику, работу с базой, генерацию сессии и т.д. И именно поэтому они связывают проектирование API с разработкой кода функции и именно поэтому когда им нужно добавить, например, GraphQL им нужно дублировать код.
@breslavsky Почему заранее нельзя договориться с фронтом как данные будут бегать туда-обратно и начать работу параллельно? Такого кейса нет? Фронты не могут предложить вариант, как это видят? Вы на беке дадите добро или внесете изменения и у вас будет контракт с фронтами. Вы спокойно пойдете делать и они тоже. Потом через какое-то время вы соединитесь и проверите, что ваш контракт выполнен. Что тут не так?
Spec-First Development
Я понял, что многие просто не знают про подход – Spec-First Development.
Spec-First – это философия о том, как разрабатывать API более эффективно. Если вы следуете философии «сначала спецификация», вы сначала пишете спецификацию и используете ее в качестве контракта, к которому разработчики пишут код.
Многие думают, что Swagger (Open API) – это «UI шкурка», которую генерирует в конечном счете бек из кода, они не понимают, что это в первую очередь – JSON схема описания API.
Взято из https://starkovden.github.io/introduction-openapi-and-swagger.html
Можно сгенерировать свою спецификацию из аннотаций кода, но говорят, что автоматическая генерация - не лучший подход. Майкл Стоу (Michael Stowe) в статье Беспрепятственный REST: руководство по проектированию Perfect API рекомендует группам вручную реализовать спецификацию, а затем обрабатывать документ спецификации как документ, который разработчики используют при выполнении реального кодирования. Этот подход часто упоминается как «spec-first development».
Ну и инструмент для создания API спецификаций https://swagger.io/tools/swaggerhub/
Более 15 000 команд разработчиков программного обеспечения по всему миру используют SwaggerHub. Поскольку спецификация OpenAPI становится в большей степени отраслевым стандартом для документации API, специфичные инструменты SwaggerHub имеют важное значение.
Видимо, ни одного из этих 15 000 в комментариях не оказалось.
Фронты могут проектировать API
Мы в команде давно используем Swagger, мы пишем его заранее на фронте, потом передаем на бэк, чтобы они реализовали, что нам нужно. И да, мы не обезьянки, мы понимаем, что такое REST, пейджинг, сериализация и т.д. Мы согласовываем API с беком, вносим правки вместе, и работаем параллельно - это правда удобно. Конечно бизнес-логика отдельный вопрос – это чистый бэк, туда мы не лезем.
Нам не совсем удобно работать с одним большим Swagger YAML файлом, а так же при проектировании ендпойнтов и схем данных не хватает привязки в пользовательскому интерфейсу приложения, чтобы понимать, какие экраны (фичи) уже покрыты API, а какие нет.
Мы всегда ищем способы улучшения наших процессов и мой вопрос, по сути был элементом «кастева», чтобы предложить одно из возможных решений, которые мы планировали разработать.
И спустя пару месяцев мы разработали – API Projector ↗
Визуальный Swagger редактор
API projector – это визуальный Swagger редактор с возможностями привязки API к пользовательскому интерфейсу системы (приложения).
В нем, фронтенд разработчики, могут опираясь на UI (с пользовательской историей) спроектировать API, отправить его на проверку бекенду, согласовать и утвердить, а потом после реализации проверить, что все контракты выполнены.
Бекенд экономит время для концентрации на бизнес-логике, фронтенд предлагает формат взаимодействия с бизнес-логикой опираясь на потребности пользовательского интерфейса.
Покажу несколько примеров как это работает вместо длинного описания.
Ну и другие киллер-фичи на будущее:
Более удобное обсуждение контрактов через внутренние чаты.
Валидация спеки с реальными серверами, например:
dev,rc,prod. Всегда знаем какие отличия есть в ендпойнтах и схеме данных.Автоматическое тестирование ендпойнтов реального сервера на «уничтожение» через Schemathesis ↗
Спасибо друзья, очень нужна Ваша обратная связь: как считаете будущее за Spec-First Development или полный Agile (шутка): митинги, JSON-чики в чатиках и т.д.?
