Comments 12
А как же AsyncApi?
Добрый день. Про AsyncAPI написано в статье. Мы его рассматривали. Но у него для нас есть критичные недостатки: инфраструктура вокруг него вся на JS и это еще один DSL.
У вас какая-то странная получилась история. Вроде бы и есть объяснение странностей, но от этого история не перестает быть странной. Складывается ощущение, что вы не до конца поняли что такое AsyncAPI.
Если для документирования http интерфейсов существует спецификация OpenAPI, то для асинхронного сообщения с использованием брокеров сообщений мы не нашли подобного инструмента.
Но это он и есть https://www.asyncapi.com/. Инструмент под названием "спецификация".
Увидев текущие проблемы документирования интерфейсов, использующих брокеры сообщений, мы подумали, как их можно решить. Для решения проблемы отсутствия единого формата документирования решили использовать OpenAPI нотацию.
Нет, уже есть спецификация — AsyncAPI. Если вы считаете, что она "неполноценна" или что-то подобное, так присоединитесь и помогите https://github.com/asyncapi?type=source#-contribute-to-asyncapi, вместо того, чтобы изобретать велосипед.
Как мы знаем, OpenAPI - это нотация для описания http интерфейсов. Соответственно, вся инфраструктура вокруг OpenAPI спецификации построена для http. Для использования OpenAPI инфраструктуры необходимы доработки.
Да, они и были сделаны в AsyncAPI https://www.asyncapi.com/docs/tutorials/getting-started/coming-from-openapi, а вы все еще изобретаете велосипед.
AsyncApi - протокол для описания асинхронного общения между приложениями. Протокол позволяет проектировать приложения в Event-Driven Architecture. У OpenAPI и у AsyncAPI есть много общего (например, описание моделей).
Нет, это не "протокол", это "спецификация", аналогичная OpenAPI, но для асинхронных API.
Ну, и еще одно:
Мы его рассматривали. Но у него для нас есть критичные недостатки: инфраструктура вокруг него вся на JS и это еще один DSL.
Какая еще инфраструктура? О чем вы? Ну и не так все плохо с Java https://www.asyncapi.com/tools?pricing=free&langs=Java, в том числе с генерацией кода из дока на основе этой спецификации https://www.asyncapi.com/tools?pricing=free&langs=Java&categories=Code+Generators.
P.S. А, это я непонял — вы продвигаете "AxenAPI - разработка Axenix". Тогда все понятно)
генераторы кода для Async API на node JS - по крайней мере то что я нашла на их сайте. Соответственно для сборки проекта с генерацией кода в инфраструктуру для сборки Java приложений надо тянуть ноду (не хочу). Я хочу такой же процесс сборки - плагин (в моем случае gradle plugin). Надо посмотреть внимательнее на плагин, который вы прислали (спасибо).
Так же, когда речь идет о переходе на api-first, то изучение двух DSL станет большим препятствием. Мы решили немного приблизить спецификацию асинхронного общения к OpenAPI
Расскажу про свой опыт использования данной практики в разработке. На текущем месте где я работаю, чуть меньше года как была введена инженерная практика api first. Нам тоже говорили про все эти плюсы и говорили, что это будет круто, всем будет удобно этим пользоваться, но по факту, оказалось нафиг это никому не нужно и во многие сервисы просто были добавлены api.yaml кто-то json только лишь для прохождения проверки quality gates. И так с какими же проблемами мы столкнулись.
Проблема с generic типами для java/kotlin моделей. В запросах и ответах мы везде пользуемся обобщенными типами, используемая библиотека openapi-generator не предполагает работу с такими данными типа
val data: T? = null. Да мы это обошли через костыли путем переопределения шаблонов и классов генерации, но по итогу в описанных схемах у нас одни данные, а на выходе сгенерированные данные другие уже в обернутых классах с обобщенными типами.Переход на сгенерированные данные. Тут начинается боль перехода с data классов на java классы, для универсальности мы генерируем данные на java, так как не все пишут на kotlin. Проекты которые уже были написаны давно используют свою устоявшуюся модель, то при переходе на сгенерированные данные и где в задаче у нас есть расширение модели путем добавления новых данных в openapi спецификацию, по цепочке ведет к большому переписыванию на новые модели. Отсутствие крайне полезной функции copy()
Миф о том что можно заслать свое api в другую команду и они это заиспользуют, уменьшает время простоя команды. Нет, это так не сработает, у всех сервисов есть свои нюансы ведения моделей. В большом энтерпрайзе никто этого делать не будет. Есть документация в вики-системах, это куда быстрее и удобнее найти актуальную модель используемая теми или иными сервисами.
Каждая команда начинает генерировать свои модели, хотя по составу они за частую идентичны с тем что используется в соседней команде. Тут куда эффективнее и проще иметь одну common библиотеку, куда все команды будут закидывать актуальные изменения.
Итого: Для проектов которые уже давно существуют, переходить на технологию api first это будет еще одна проблема в вашем коде :) Когда это следует использовать, ну к примеру в не большом проекте с не большим количеством сервисов 2-4, который только начинает развитие, возможно это и привнесет какие-то плюсы, но скорее всего больше минусов. Не забывайте, что из коробки не сможете пользоваться обобщенными типами, придется попотеть чтобы научиться это делать. Рекомендую ли я пользоваться api firstom'ом, однозначно нет, на презентациях и в статьях на эту тему всегда красиво пишут про данную практику, но на деле это не так, по своему опыту внедрения данной технологии очень много ресурсов ушло чтобы все это дело как-то заработало с тем что есть :)
Переход на какой либо процесс - это всегда нетривиальная задача. У меня был опыт гибрида: мы клиенту (js+react) отсылали спеку (сложную с обобщёнными типами), а сами эту спеку создавали автоматически по моделям java. В итоге клиент перешел на генерацию кода, а мы (бек) нет. Но это нас вполне устроило. Немного смягчит сценарий перехода.
По поводу крупный или не крупный проект: постановка вопроса от размера проекта абсолютно не зависит. Ломать что-то работающее всегда сложно. Прекрасно видела систему из множества сервисов (ты даж не знал, кто твои клиенты) и единственное чем обменивались была подобная спецификация.
По поводу коммон библиотек: распространение коммон библиотек у нас привело к тому, что в одном общем классе было 100500 групп валидаций. Да и как только коммон библиотека меняет версию начинается очень большая беготня (или если версии где-то разошлись). Если используются спеки эта проблема пропадает (при полной поддержке обратной совместимости).
С дженериками при неудачном стечении обстоятельств действительное были проблемы (сейчас уже лучше - начиная с 3.1).
Про генерацию кода на бэке и передачу сгенерированных интерфейсов для фронта, это все таки задача не много про другое. Я делал на стороне бэка ровно такую же задачу, на этапе сборки мы это все по красоте упаковывали в npm артефакт и фронт мог спокойно забрать нужную версию. Но все таки тут есть зависимость одной команды от другой и такой подход сложно назвать api first'ом.
Если же все таки и нужно как-то быть в одном информационном поле, то на мой взгляд нет ничего проще и удобнее использовать генерацию на основе json/xsd/wsdl и т.д. схем.
API First как процесс не имеет ничего общего с генерацией кода. Это процесс при котором сначала разрабатывается API. Потом всё остальное. Поэтому не рекомендовать процесс я не могу :-).
Генерация кода - это хорошее дополнение к процессу. Почему бы не сгенерировать код, если команда определилась как будет описывать API . В нашем случае то самое единое информационное поле - это спецификации в OpenAPI формате (имхо: wsdl немного архаично смотрится, json scheme не содержит всю информацию об API).
Мы не упаковывали npm - мы именно отдавали спеку. На мой взгляд, это удачный пример мягкого перехода на описанные процессы генерации кода. Никто не мешает поочередно переходить на использование спецификации в качестве источника информации об API.
Если речь только про Kafka, то там есть Schema registry (https://docs.confluent.io/platform/current/schema-registry/index.html). На нем прекрасно реализуется API First подход
Во-первых, речь идёт не только о Кафка - мы её взяли для примера. Во-вторых, с помощью schema registry можно сгенерировать только модели - не учитываются хедеры, которые по спецификации api могут быть обязательны. Третье - мы пытаемся сгенерировать не только dto , но и обвязку вокруг. Ну и последнее - мы пытаемся именно объединить описание двух спецификаций - чтоб использовать один язык (OpenAPI) и один процесс генерации кода - openapi plugin.
Асинхронный API First