@dddboy

Эффективное погружение новичка в проект

2023-05-28T15:09:42.008Z

Когда вы решаете создать свой собственный продукт, вам понадобится ряд инструментов, которые помогут новичкам быстро погрузиться в идею вашего продукта и его техническую реализацию. Эти инструменты должны помочь новичкам понять:

Как реализована архитектура вашего продукта?

Как пользоваться UI-кой вашего продукта?

Какие бизнес-процессы реализуются в вашем продукте?

Как запустить все компоненты продукта локально и начать с ним взаимодействовать через API?

Как бизнес-процессы используют архитектурные компоненты вашего продукта?

Как проверить, что новичок спустя определенное время работы понимает, как работает продукт?

Как через эту архитектуру протекают бизнес-процессы вашего продукта?

Вот несколько инструментов, которые могут вам помочь:

Icepanel.io позволяет реализовать визуальное представление архитектуры вашего продукта по нотации C4. Все элементы, такие как внешние системы, сервер, фронтенд клиент, мобильное приложение и бизнес-процессы, в которых они задействованы, могут быть удобно и понятно отражены в виде схемы, где каждый элемент имеет функционал вложенности, то есть вы можете провалиться в него для получения более детализированного контекста.

Proto.io позволяет спроектировать ваш пользовательский интерфейс в понятной форме. Вы можете спроектировать мобильное приложение или сайт.

Stormbpmn позволяет спроектировать BPMN-схемы ваших бизнес-процессов совместно с другими участниками команды.

Readme.so - это удобный readme editor. Он содержит большое количество текстовых заготовок, с помощью которых вы сможете быстро сформировать качественный readme-файл. В нем можно разместить руководство по локальному поднятию экосистемы ваших микросервисов, запуск локального окружения, настройку сертификатов и т.д.

Для того чтобы представить новичку связь между архитектурными компонентами (определенными на C4 борде ) и bpmn схемами можно использовать knowlege based инструмент .

В инструменте должен иметься механизм классификатора с помощью которого можно будет отметить связанные бизнес-процессы и компоненты.

Далее в поиске можно будет с помощью фильтров найти все необходимые ресурсы.Скрин представлен из интерфейса инстурмента управления знаниями teamly.

teamly - российский аналог confluence. Инструмент изначально позиционируется как база знаний + тестирование сотрудников на предмет понимания продукта в разработке которого они принимают участие.Очень удобный интерфейс создания набора тестов для аттестации сотрудника .

Hot Swap- как менять source код в Inteleji IDE в debug session без перезапуска проекта

2022-11-08T23:44:58.426Z

Когда мы разрабатываем код древнего монолита и дебажим его локально в формате задеплоеного war на локальный tomcat через inteleji idea - каждое изменение кода требует перезапуска приложения для применения изменений.

На одном из проектов я столкнулся с тем что локальный стартап приложения занимает 6 минут.Все дальнейшие эксперименты и попытки проходили на подыпытном вида - jdk1.8.0_181 and gradle multi module project build and deployed as single war on Tomcat 8.5.68.

Spring на проекте есть но не spring boot -следовательно spring boot dev tools отпадает.

Шаг 1 - пытаемся в Hot Swap в Inteleji Idea Ultimate 2022

Первым шагом было знакомство с встроенными иснтрументами IDE для того чтобы попытаться в динамике поменять java class source code state in jvm - такая процедура определяется термином Hot Swap .

Ветераны индустрии помнят такой иструмент как Jrebel - но нас сейчас он не интересует так как Jrebel на момент сентября 2022 года не работает в России.

Inteleji предоставляет такую возможность : https://www.jetbrains.com/help/idea/altering-the-program-s-execution-flow.html#reload_classes

Но работает это судя по всему только в hello world приложениях не зависящих от таких фреймворков как spring и hibernate.При моей попытке через Inteleji Hot-Swap-нуть код класса аннотированного @Service в монолите на базе java 8 я словил такой exception

Отгуглить как решать такой кейс базовыми инструментами Inteleji Ultimate я не смог.

Шаг 2 - DCEVM

Hot Swap в Inteleji существует с некоторыми ограничениями

Due to VM design, HotSwap has the following limitations:

it is only available if a method body is modified. Changing signatures is not supported.
adding and removing class members is not supported
if the modified method is already in the call stack, the changes will take effect only after the program exits the modified method. Until that moment, the method body remains unchanged, and the frame is marked as obsolete.

If you want to remove the limitations imposed by the standard VM, you can use the Dynamic Code Evolution VM with unlimited support for reloading classes at runtime.

Ну DCEVM так DCEVM подумал я и пошел искать.

Есть 2 варианта настройки :

1 вариант - наиболее понятный https://ssledz.github.io/blog/2016/05/16/hot-swap-in-java-with-dcevm-and-hotswapagent-a-jrebel-free-alternative/ - у меня не сработал - пробовал с liberica jdk и oracle jdk 8 - летели ошибки HOT Swap в IDE

2 вариант - официальный гайд - http://hotswapagent.org/ - пробовал только для java 8 с установкой всех инструментов из гайда + oracle jdk 181 - тоже не сработало - летели ошибки HOT Swap в IDE :

hotswap-agent-1.4.2-SNAPSHOT

DCEVM-8u181-installer-build2

Шаг 3 Single Hot Swap inteleji plugin

Потратив день на безрезультатные эксперименты в рамках предыдущих 2 шагов и заведя тикет https://github.com/HotswapProjects/HotswapAgent/issues/446

Случайно был найден плагин :

https://plugins.jetbrains.com/plugin/14832-single-hotswap

Он как раз и дал эффективный результат без всяких настроек JVM с помощью флажков указанных в run/debug configuraton IDE для tomcat,возни с hotswap agent ,и DCEVM инсталятором .

Я просто поставил плагин и Hot Swap заработал для - liberica jdk 1.8 and gradle multi module project build and deployed as single war on Tomcat 8.5.68 .

После подключения в ide появляется такой значок :

Для Hot Swap IDE у меня стояла такая настройка :

В итоге запустив debug сессию в IDE - я смог коментить код/менять код в inteleji ide code space и hot swap-ить его на ходу без перезапуска проекта =)

Как автоматически распилить монолитный open api файл на 21 000 строк в читаемый вид ?

2022-07-05T19:21:28.758Z

Есть такая штука - fist api driven подход .

Это когда вы сначала пишете yml файлик или yml файлики с указанием вашего rest api ( урлы эндпоинтов, структура респонса,структура реквеста, коды ошибок и тд).

А потом либо используете в confluence как read-only спеку или генерите код эндпоинтов при копиляции проекта.

Выглядит это примерно так :

Когда размер конфигурационного файла достигает 21 000 строк - внесение изменений в него начинает быть мучительным.

Перебить руками это в ликвибейзоподобный вид можно - но долго и сложно.

В итоге к нам на помощь приходит супер тул - https://redocly.com/ .

Итак погнали разбираться - сначала поставим его на свою тачку.

Я ставил его на мак следующей командой :

npm i -g @redocly/cli@latest

Дальше чтобы показать как разбивать - сплитить файл - на мастер с чайлд файлами я использую велком теплейт отсюда https://editor.swagger.io/.

Но с единственным НО - этот тул работает только со спекой в формате open api 3.0.0 .

С swager 2.0.0 к сожалению не пашет - поэтому предварительно надо сконвертить его к формату openapi 3.0.0 если у вас был в формате свагера . Это спокойно делается в онлайн редакторе https://editor.swagger.io/

Итак после того как мы сконвертили - идем в интеледжи и создаем пустой демо проект.

Вставляем туда наш файлик с open api 3.0.0 контентом.

699 строк и это только то что поместилось в экран.

Итак начинаем распил . Сначала заходим в консоль в пакет где находится openapi.yml.

И вводим команду

redocly split openapi.yml --outDir=openapi_decomposed

Дока команды : https://redocly.com/docs/cli/commands/split/#split

Давайте ее разберем :

redocly split - разбить файл на структуру

openapi.yml - путь до файла который разбить

--outDir=openapi_decomposed - директория куда будет положена структура с мастер файлом и чайлд файлами

В папке schemas - лежат файлы каждый из которых представляет структуру одного из реквестов или респонсов .

В папке paths - лежат конкретные файлы описывающие начинку каждого уникального урла .На один файл может приходится несколько методов - GET,PUT,POST - которые прикреплены именно у этому уникальному урлу.

Ну и наконец мастер файл с ссылками на чайлдов. И явными урлами эндпоинтов.

Красное подчеркивание из за того, что тул при генерации в случае с урлами содержащими path variable криво определяет filename .

Но это легко лечится через refactor rename прямо в этой строчке.

Итог : мы повысили читабельность наших конфиг файлов.

Код из статьи : https://github.com/redkatok/redocly_demo

P.S. Также этот тул может собирать несколько файлов open api в один. Советую почитать доку этого инструмента.