Как стать автором
Обновить

Что делать, если никто не хочет документировать? Организация документирования микросервисов по минимуму

Время на прочтение 6 мин
Количество просмотров 5.7K
Всего голосов 6: ↑3 и ↓3 0
Комментарии 13

Комментарии 13

Поддержка свагера хороша у строго типизированных языков таких как си шарп джава, у остальные платформы даже не знают чё такое сваггер и опенапи!
Согласен -) Я с явой и работаю. Идея в том что надо в таком подходе использовать имеющиеся инструменты аннотации кода по максимуму.
Позволю не согласиться. Мои рубисты (помидорами только не кидайте) использует связку grape + entity + swagger, что на выходе даёт open_api–документацию вообще без каких-либо дополнительных аннотаций в коде — куда уж проще.
и это правильно ведь основная идея это использовать максимум возможностей в специфицировании от кода
В Python есть опциональная типизация, на ней тоже можно делать OpenAPI
к сожалению grape-entity для руби это костыль который скрывает нехватку статической типизации!. шел 2020 год а ейштеины придумывали очередной язык со статической типизацией, эх сколько было сломано копей об динамическую типизацию!
Движение в сторону статитеческой типизации оправдано тем, что это позволяет снизить число ошибок. А причины такие:
1) Много низкоквалифицированных разработчиков из-за дороговизны опытных и трудности с наймом.
2) Большая ротация по проектам. Человек, не знакомый с проектом, может легко допустить ошибку в предполагаемом типе и ему труднее понять, где и какие типы.
3) Статическая типизация очень хорошо заходит в современных IDE, которые делают проверку ошибок на лету, упрощают рефакторинг и так далее.
Проблема, с которой мы столкнулись при попытке использовать code-first подход к сваггеру — это не удобство обсуждения и согласования планируемых изменений между разными частями организации. По итогу делаем сначала сваггер (спека), а код ее реализует.
Полностью согласен. И в конкретном случае все внешние API все же идут через солюшин архитектора. Но код-вперед активно используется для рестов фронтенда (а у нас все фулстеки) и для бэкенд микросервисов, которые никто особенно не согласуют. И представленное решение является попыткой наведения хоть какого-то порядка
А общую структуру сервисов (например, разбиение на группы) и их зависимости вы как документируете?
В конкретном, выше описанном случае, разбиение сервисов на группы не практикуется.
Зависимости пока решили не документировать. Рассматривали две опции. 1) Описывать в том же Readme.md отдельной секцией. 2) Контролировать зависимости автоматически через мониторинг сетевой активности и авто репортинг с размещением в отдельный репозиторий для контроля изменений. И для Кубернета и для OpenShift есть такие средства. Я более склоняюсь к авто контролю зависимостей.
Я более склоняюсь к авто контролю зависимостей.

Признаться, в случак реальной логики я сомневаюсь, что это будет работать. Например — сервис А спрашивает сервис Б и в зависимости от параметра х далее спрашивает иногда В, иногда Г а иногда подождёт и переспросит Б. А сервис Б…
Другими словами, общие Workflows надо описывать в каких-то центральных моделях. И лучше не текстом, а UML.
Yes. Of course. I agree. But in case of nobody want to document it and nobody ready to change, in my view, the best option to use network monitoring or a distribute trace capability like Spring Cloud Sleuth.
Зарегистрируйтесь на Хабре , чтобы оставить комментарий

Публикации

Истории