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

Друзья, не думал, что тема еще актуальна в 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-чики в чатиках и т.д.?

Читайте так же:

  • Что не так с мозговым штурмомЧто не так с мозговым штурмом Давайте представим себе ситуацию: группе экспертов нужно решить сложную задачу. Она необычная и не решается стандартными способами. Одна из самых распространённых методик поиска решения таких задач — мозговой штурм. Его часто используют для поиска идей на заданную тему в командах […]
  • Какие рекомендации следует учитывать при наполнении страниц сайтаКакие рекомендации следует учитывать при наполнении страниц сайта Сегодняшнее сообщение от Эйдана Брайанта, одного из наших собственных старших исследователей UX. Эйдан был достаточно любезен, чтобы заглянуть в блог, чтобы помочь нам с тем. Что делать и чего не делать при создании великолепных веб-форм. Наслаждайтесь! Поздравляю! Вы сделали […]
  • Сколько стоит наполнение сайта информациейСколько стоит наполнение сайта информацией Поделитесь этим постом: Судя по популярности нашего блога о том, сколько стоит маркетинг в социальных сетях, людей очень интересует. Сколько агентства и фрилансеры берут за управление социальными сетями. Фактически, этот пост в настоящее время занимает 1-е место на страницах […]
  • CNCF представила бета-версию нового (более простого) экзамена по Kubernetes — KCNACNCF представила бета-версию нового (более простого) экзамена по Kubernetes — KCNA Kubernetes and Cloud Native Associate (KCNA) — новый экзамен начального уровня, публично анонсированный 13 октября в рамках конференции KubeCon, который проходит в эти дни в США. Экзамен позиционируется как «подготовительный» перед сдачей уже зарекомендовавших себя в индустрии Certified […]