Хочу поделиться с вами инструкцией как описывать архитектуру системы как код. Формирование диаграмм будет в нотации С4, о самой нотации можно почитать по ссылке.
Применять будем инструмент Structurizr. Не будем рассматривать, как ввести инструмент в контур вашего ландшафта, задача показать, что именно необходимо сделать архитектору для описания текущего и будущего состояния системы.
Обеспечение рабочего места архитектора
Установить Java 17+
Установить idea (я использую vs code)
Установить плагин C4 DSL Extension
Скачать structurizr-lite.war (источник)
Создать репозиторий и добавить в него ветку dev, в нём будем хранить нашу архитектуру :) Теперь всё готов, перейдём к заполнению проекта.
Заполняем файл workspace.dsl
Скрытый текст
workspace {
name "наименование системы"
description "описание системы, понятноен психечески здоровым людям"
model {
# Подключаем ландшафт - справочник систем
!include landscape.dsl
# Подключаем контекстную диаграмму
!include context.dsl
# Подключаем контейнерную диаграмму
!include container.dsl
}
views {
# подключаем стили
!include styles.dsl
systemContext SRTUCTURIZR {
title "Контекст на сейчас"
include *
# авто форматирование, есть разные настройки, можно посмотреть в документации
autoLayout lr
exclude relationship.tag!=ASIS
}
systemContext SRTUCTURIZR {
title "Контекст на 2025"
include *
# autoLayout lr
exclude relationship.tag!=Q25
}
container SRTUCTURIZR {
title "Контейнеры"
include *
autoLayout lr
# exclude relationship.tag!=Q25
}
}
}Заполняем файл context.dsl
Скрытый текст
# Можно для наглядности добавить пользователя
Architector = person "Архитектор"
softwareSystem SRTUCTURIZR {
# Системный контекст на сейчас
Architector -> SPARXEA "Ведение архитектуры" "Ручной ввод" "ASIS"
SPARXEA -> SRTUCTURIZR "Выгрузка данных по системам ит ландшафта" "Ручной ввод" "ASIS,sync"
# Системный контекст на 2025 год
Architector -> SRTUCTURIZR "Ведение архитектуры" "Архитектура как код" "ASIS,Q25"
SRTUCTURIZR -> SPARXEA "выгрузка результатов" "dsl" "Q25"
}Заполняем файл container.dsl
Скрытый текст
!element SRTUCTURIZR {
webapp = container "Веб приложение" {
}
database = container "База данных" {
}
}
# Можно добавить связи
webapp -> database "save" "API" "ASISЗаполняем файл landscape.dsl
Скрытый текст
# Справочник систем
SRTUCTURIZR = softwareSystem "Structurizr" "Система для ведения архитектуры как кода"
SPARXEA = softwareSystem "SPARX EA" "Позволяет вести описания и проектирования систем"Заполняем файл styles.dsl
Скрытый текст
styles {
element "Element" {
background #1168bd
color #ffffff
shape RoundedBox
}
element "Person" {
background #1168bd
color #ffffff
shape person
}
relationship "sync" {
color #000000
dashed false
}
element "Container" {
color #ffffff
shape Pipe
}
}
Далее необходимо запустить проект с помощью команды через командную строку (можно сделать некий *.cmd), код указан ниже
Скрытый текст
java "-Djdk.util.jar.enableMultiRelease=false" -jar C:\structurizr-lite\structurizr-lite.war "C:\Users\.git\structurizr"где
"-Djdk.util.jar.enableMultiRelease=false"
# атрибут манифеста «Multi-Release» https://habr.com/ru/companies/haulmont/articles/428868/
"-jar C:\structurizr-lite\structurizr-lite.war"
# указывается источник structurizr
"C:\Users\.git\structurizr"
# указываем локальный репозиторий После запуска перейти в браузер, и обратиться к http://localhost:8080
Описание сформировалось и отображается
Скрытый текст
Для наглядности в указанном примере есть 2 варианта отображения, первый вариант сформирован системой, за это отвечает строка кода:
autoLayout lrВ документации указаны разные варианты, можно поэкспериментировать :-)
Вносим свои данные по контексту системы, контейнерам системы, можно поиграться стилями (в документации всё подробно изложено), пушим в репозиторий, профит. Теперь архитектура в виде кода.
Очень прошу соблюдать правила нотации С4 и при необходимости обращаться к документации. Гибрид в виде картинки, дело хорошее, но не всегда всем понятное
Если подход получит одобрение в рамках компании, то необходимо будет собирать архитектуру систем, и публиковать в structurizr. С этим поможет Structurizr CLI (https://docs.structurizr.com/cli). По факту необходимо 3 ключа и url
-id: The workspace ID (required)
-key: The workspace API key (required)
-secret: The workspace API secret (required)
-url: The Structurizr API URL (optional; defaults to https://api.structurizr.com)Надеюсь вы как минимум попробуйте данный подход, и для себя сами решите, полезен он вам или нет.
Материалы
https://docs.structurizr.com/ — сайт с документацией
https://github.com/structurizr/onpremises/releases — здесь можно скачать последнюю версию structurizr
https://gitflic.ru/project/trifonov‑ks/structurizr — пример проекта на всякий случай
Всем добра!
olku
Есть вариант проще, где пофикшены ссылки результатов поиска по документу, формат картинок в SVG вместо PNG, и доделана вставка в Конфлуенс, которая по замыслу Саймона должна работать только в платной версии. Также добавлен стандарт документации arc42. Поднимается докером, форкайте на здоровье https://gitlab.com/plgrnd/aac
kost_tr Автор
Интересное решение
Я предложил решение под винду, без докера. Мне кажется оно будет доступно большему числу желающих попробовать
Так же в предложенном варианте контекст и контейнеры вынесены в отдельные документы, что кажется удобнее
Предложен вариант справочника систем, которые можно вынести в отдельный репозиторий