Я фронтенд разработчик, а не обезьянка

Kate · 3 Янв 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 ↗