Если вы хотите сделать что-то полезное и работающее, сделайте так, чтобы другие люди могли полноценно этим пользоваться, это нормально делать рецензии, и вообще о вас будут вспоминать добрым словом, а не темной стороной своего словаря.
Для этого, помимо того, что просто хорошо делать свою работу, писать правильный код, не бояться использовать современные технологии и вообще не тупить, необходимо обратить внимание на две вещи — документацию и API. Без них человеку будет сложно понять, с чем он имеет дело, как все это работает, а что лучше вообще не трогать.
Конечно, можно погуглить, что означает та или иная спецификация, можно проверить в бою, что и как (а потом так же бодро откатиться на предыдущую рабочую версию), но лучше, когда человеку дают подробную документацию.
Вот о чем я говорю сегодня.
В этом посте я расскажу, почему мы в RBK.money используем Swagger, как он помогает нам в работе и какие у него проблемы.
Итак, Swagger, он же OpenAPI ( https://swagger.io/ ).
Swagger хорош тем, что включает в себя сразу кучу полезных вкусностей, посмотрите:
- типизация переменных
- описание методов
- удобная схема ссылок
- не привязан к какому-то конкретному языку
- и вообще классная штука, все что нужно вроде есть.
Также можно быстро описать интерфейс в Swagger. Вот так - альтернатив особых нет в принципе.
Конечно, можно вспомнить xml, но лично мне он кажется какой-то неудобной древностью чисто с эстетической точки зрения.
Мне это вообще-то кажется важным, потому что я пытаюсь относиться к коду так, как товарищ Туполев относится к самолетам: 
Только красивые самолеты могут хорошо летать Да, тут можно порассуждать о точности цитаты, да и вообще вспомнить Марселя Дассо и его «un bel avion est un avion qui vole bien», но мы пока не об этом.
Надеюсь я все же передал суть.
Итак, вот оно.
В моем случае в Sublime Text то, что мы делаем, должно выглядеть красиво.
Если это спецификация, так и есть.
К сожалению, этот тезис не применим к xml. А вот YAML — никакого мусора там нет, есть только то, что вы написали.
Спецификация Swagger интересна еще и тем, что вы можете нормально делать описания и определения.
Вот и получается, что сам протокол — это интерактивная документация.
В арсенале много крутых штук, позволяющих сделать из YAML вполне приличную вещь.
Все, что мне нужно для его нормальной поддержки — немного подправить спецификации в YAML, и все, у меня есть готовая документация.
Пример интерактивной документации, построенной по спецификации с помощью скриптов ReDoc, используется нами на нашем портале разработчиков: https://developer.rbk.money/api/ .
Подробнее о преимуществах
Весь протокол виден и описан, вы знаете какие бывают типы, если вам нужно что-то проверить на степень безопасности, вы можете спокойно зайти в реализацию протокола в коде и понять, что (как минимум) все типы, которые приходят к вам, были проверены.Это уже круто, потому что это достаточная степень защиты — набор входящих данных в команду управления известен, и можно легко контролировать соответствие этого набора схеме.
Сразу оговорюсь, полной гарантии безопасности это не дает (спойлер: вообще ничего не дает), но сразу закрывает огромную кучу потенциальных дыр.
Подобный протокол также рассматривается быстро.
К новой сущности добавляется какое-то определение, например, возвратный платеж.
И не надо нудно пересматривать портянку на протяжении нескольких метров - видишь, что добавился новый тип, понимаешь, что именно он делает, это дает возможность автоматизировать тесты и безопасность.
Потому что возврат платежей, в принципе, — это по сути очень сложный бизнес-процесс.
И очень тяжелый.
Но здесь оно уместилось в 6 файлов и 224 строки.
Прелесть в том, что этого достаточно, чтобы понять, какие именно данные будут передаваться между микросервисами, описаны все возможные ошибки.
В общем, ребята, это действительно удобно.
Отладка также доставляет удовольствие.
Swagger также был выбран для того, чтобы можно было быстро войти в систему из браузера и просмотреть запросы и полезные данные.
Да, конечно, можно было бы пойти и сделать вебсокет и старательно загонять туда кучу данных, но я не фанат этого — обычно это свой протокол, который и так самый дикий, и чаще всего он бинарный, и это нормально отлаживать и не хотеть.
В процессе взять отпуск (или больничный) довольно сложно.
Тем более, что в такой схеме все должно быть дико защищено, а хочется открытости и прозрачности.
Чтобы можно было быстро выдернуть из консоли curl и посмотреть, как в целом обстоят дела.
Существует достаточно типов данных; до сих пор у нас никогда не было ситуации, когда нам не хватало типов данных.
И вот еще что.
Вы собрали распределенную команду, собрали все вместе, кто-то написал клиент, кто-то сервер, вы собственно пошли писать UX/UI для бэкенда.
Сам бэкенд создается долго, но у нас есть swagger-спек, мы берем его, генерируем на его основе мок-сервер — и все.
Вы можете начать писать интерфейс еще до того, как бэкенд допьет кофе и включит компьютер, чтобы начать работу.
А потом пишешь бэкенд, меняешь эндпойнт и получаешь готовое решение.
То есть вы можете не только распараллелить разработку, но и отделить зависимости команд. Это классная вещь.
Минусы, есть ли недостатки?
И где бы мы были без них? Это отличная вещь, но еще не панацея.Во-первых, кодогенератор Swagger на самом деле не работает. Нам пришлось его сократить, но мы настолько увлеклись, что в итоге написали свой собственный.
Теперь мы можем генерировать методы и классы.
А так на бумаге все было отлично, берешь спек, генеришь клиент, генеришь сервер, радуешься жизни.
На самом деле у вас нет ни клиента, ни сервера.
Услышав пару отчаянных матов от разработчиков на эту тему, я решил написать свой.
Во-вторых, на старте у нас был конфликт такого рода.
Внутри платформы у нас есть Thrift. В то же время снаружи у нас есть Swagger. Я, кстати, до сих пор не могу себе признаться, что мы точно всё сделали правильно, и что хорошо, что Сваггера не взяли сразу везде.
А так работы стало в два раза больше, переводчиков протоколов и прочих радостей.
Кстати, почему Бережливость - у нас были готовые разработки для rpc и клиент-серверных вещей, решавших транспортные задачи.
Мы быстро прикрутили реализацию Google Dapper, реализацию идеи о том, что в распределенной микросервисной среде обязательно нужно уметь отслеживать запросы.
То есть понять, через какую цепочку микросервисов идут эти самые вопросы, и где они глупы, если они глупы.
Подробнее об этом будет в одном из следующих постов.
И оказалось, что внутри все есть, а снаружи надо делать что-то свое.
А также список изменений.
Автоматизация журнала изменений здесь крайне слаба.
Вы меняете некоторые методы, чтобы показать, что раньше в этом методе было что-то одно — а теперь есть что-то другое, и так, кроме диффов, такого в репозитории нет. Поэтому журнал изменений необходимо писать вручную.
А поскольку все время что-то приходится делать вручную, потому что это невозможно автоматизировать, то это делаться вообще не будет. А теперь это немного мешает моей работе; например, я не могу нормально объяснить клиентам, в чем разница между API 2.0 и API 3.0 — нет журнала изменений.
И примеров нет. Обычно они существуют, но здесь их придется прописать самостоятельно в генераторе документации.
Это не так уж сложно, но требует времени.
Общий
В целом мы довольны, но есть нюансы — в документации не отражены некоторые вложенные структуры, теперь это 3-я спецификация, на которую мы пока не можем мигрировать и живем по второй.Но это наш технический долг.
Итак, давайте бороться.
И даже если мне что-то больше не понравилось, сбросить это больше некуда.
Вдруг вы предложите что-нибудь интересное по теме в комментариях.
Я бы, конечно, не променял Swagger на какой-то отдельный костыль, потому что что-то костыльное и свое в конечном счете даже хуже, чем что-то посредственное, но стандартное.
И вот почему.
В принципе, я был бы очень рад, если бы все, кто сейчас открывает API, пошли в сторону Swagger, посмотрите — это сообщество, в первую очередь.
Пришедшее сообщество посмотрит на стандарт, на спецификацию, и она начнет развиваться.
Там, где кому-то что-то не нравится, они это доделают и сделают лучше.
Стандарт здесь всегда предпочтительнее.
Потому что стандарт можно улучшить.
А можно начать делать что-то свое в отдельном уголке, а потом махнуть на это рукой или вообще – постоянно тянуть в разные стороны.
Но опять же, если вы знаете какую-то полезную альтернативу, подходящую для решения подобных задач, поделитесь ею в комментариях.
Замечание после обсуждения в комментариях.
Если начинать с нуля, то следует сразу сосредоточиться на спецификации Открытая спецификация API 3.0 .
Вкусностей кардинально больше, можно сказать, что это практически новый стандарт, сильно отличающийся от версии 2. Теги: #платежные системы #api #Микросервисы #java #Распределенные системы #Erlang/OTP #RBKmoney
-
Google Пришел В Россию?
19 Oct, 24 -
Хабрахелп Бета
19 Oct, 24 -
Редактор Поисковой Системы — Searchedit
19 Oct, 24 -
Техническое Задание? Иди Через Лес!
19 Oct, 24
