Документирование вашей архитектуры: Wireshark, PlantUML и REPL, чтобы склеить их все.

Недавно мне пришлось задокументировать результаты оценки новой системы.

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

Чтобы понять все шесть, я просмотрел логи с серверов плюс сетевую панель Chrome DevTools, пытаясь сопоставить запросы с ответами и трафиком между серверами.

Как часть документации я подумал, что было бы важно иметь несколько диаграмм последовательности для объяснения протокола между различными частями системы.

Но, пытаясь нарисовать диаграммы последовательности, я понял, что все это прищуривание только позволило мне уловить общее ощущение разницы между вариантами, но не настолько, чтобы записать правильное и точное описание каждого из них.

Кроме того, предстоящая скука, связанная с открытием моего наименее ненавистного UML-инструмента и проведением нескольких часов за перетаскиванием ящиков и возни с линиями, не наполняла меня радостью.

Учитывая, что у меня уже было шесть комбинаций для проверки концепции, могу ли я воспользоваться этим?

Для начала нам нужно узнать весь трафик между компонентами системы. Для этого воспользуемся почтенным Wireshark.

Wireshark позволит нам перехватывать любой сетевой трафик, отфильтровывая все ненужное, плюс он поставляется с удобным экспортировать в json Функция для упрощения анализа вывода.

Фрагмент того, как выглядит HTTP-запрос:

Во-вторых, нам нужно будет сгенерировать диаграммы UML. Для этого мы будем использовать ЗаводUML, который представляет собой текстовый UML DSL с сопутствующими библиотеками для создания изображений. Будучи основанным на тексте, наша проблема создания диаграмм UML становится проблемой конкатенации строк.

Наконец, нам нужен клей для преобразования json-файлов Wireshark в текстовые файлы PlantUML. Мы будем использовать Clojure, но подойдет любой полный по Тьюрингу язык. Конечно, Clojure REPL делает задачу более приятной.

Результат

Во-первых, чтобы показать, давайте посмотрим, как выглядит одна из диаграмм:

Эта диаграмма требует 40 строк PlantUML, которые выглядят так:

browser -> backend: /api/datasets/ds-1 (536.0B)
browser <-- backend: 200 json (0.7KB)
browser -> backend: /api/library (525.0B)
browser <-- backend: 200 json (1.0KB)
note over browser, nginx: ->1.2KB/<-532.0B
note over browser, backend: ->4.4KB/<-5.3KB

Весь код PlantUML здесь и код можно найти здесь.

Если вам интересно, диаграмма соответствует загрузке Одностраничное приложениевыполняя аутентификацию с помощью Подключиться к OpenID и авторизация конечной точки API с помощью Пользовательский доступ.

Преимущества

Преимущества использования этих трех инструментов:

1. Мы можем создать набор точных диаграмм, что дает вам уверенность в том, что вы ничего не упустили. При условии отсутствия ошибок в коде синтаксического анализа.
2. Поскольку набор диаграмм создается с использованием одного и того же кода, все они выглядят согласованными как по содержащимся в них данным, так и по внешнему виду.
3. Данные, диаграммы и код для их создания — все текстовые, что означает, что их можно контролировать версиями и вручную проверять или настраивать, если это необходимо.
4. Если мы решим изменить какие-либо детали диаграмм, обновление всех диаграмм не займет много времени.
5. Возможно, код для создания диаграмм можно использовать в других проектах.
6. Схемы имеют желаемый уровень детализации. Например, в диаграммах мы убрали загрузку изображений, файлов css и javascript.
7. Вы можете добавить много деталей к диаграммам, так как в сборе данных есть даже запрос/ответ, поэтому вы можете анализировать их и извлекать информацию, относящуюся к вашей системе.
8. Вы можете делать все это из своей любимой IDE в интерактивном режиме:

альтернативный

Недостатки

Конечно есть некоторые недостатки:

1. У нас должна быть работающая система, и мы должны иметь возможность анализировать трафик.
2. Сбор данных может быть огромным, поэтому может потребоваться некоторая предварительная фильтрация на этапе сбора.
3. В захвате могут быть конфиденциальные данные. Будьте осторожны с охраной!

Больше преимуществ!

Последнее, но, вероятно, самое важное преимущество заключается в том, что мы превратили утомительную задачу в приятную.

Никогда не думал, что скажу это, но… Приятного документирования!