Введение

В данной статье содержится вольный перевод документации по Structurizr.

Из-за большого объема информация разделена на три статьи:

общее описание языка;
синтаксис (эта статья);
книга рецептов.

Общая информация

Угловые скобки (<...>) показывают обязательные свойства.

Квадратные скобки ([...]) показывают необязательные свойства.

Большинство инструкций имеют вид: ключевое слово <обязательные свойства> [необязательные свойства].

workspace

workspace — языковая конструкция верхнего уровня и оболочка для модели и представлений. Рабочей области можно присвоить имя и описание:

workspace [name] [description] {
    ...
}

Рабочая область также может расширять другую рабочую область, добавляя в нее больше элементов, связей, представлений и так далее.

workspace extends <file|url> {
    ...
}

На базовую рабочую область можно ссылаться либо с помощью локального файла DSL/JSON, либо удаленного (через URL HTTPS) файла DSL/JSON. При расширении рабочей области на основе DSL все идентификаторы, определенные в этой рабочей области, доступны для использования в расширенной рабочей области.

Допустимые дочерние элементы:

name,
description,
properties,
!docs,
!adrs,
model,
views,
configuration.

model

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

model {
    ...
}

Допустимые дочерние элементы:

group,
person,
softwareSystem,
deploymentEnvironment,
element,
-> (relationship).

enterprise

Конструкция устарела — вместо нее нужно использовать group.

Ключевое слово enterprise предоставляет способ определения именованного “предприятия” (например, организации) в рамках модели верхнего уровня. Любые люди или программные системы, определенные внутри этого блока, будут считаться “внутренними”, в то время как все остальные будут считаться “внешними”. На диаграммах системного ландшафта и системного контекста предприятие представлено в виде пунктирной рамки. В рамках модели может быть определено только одно предприятие.

enterprise [name] {
    ...
}

Допустимые дочерние элементы:

group,
person,
softwareSystem,
-> (relationship).

group

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

group <name> {
    ...
}

Группы могут использоваться только для группировки элементов одного типа (одного и того же уровня абстракции) следующим образом:

Местонахождение	Дочерние элементы
Model	People and software systems
Software System	Containers
Container	Components

person

Ключевое слово person определяет человека (пользователя, актера, роль или персону).

person <name> [description] [tags] {
    ...
}

По умолчанию добавляются следующие теги:

Element,
Person.

Допустимые дочерние элементы:

description,
tags,
url,
properties,
perspectives,
-> (relationship).

softwareSystem

Ключевое слово определяет программную систему:

softwareSystem <name> [description] [tags] {
    ...
}

По умолчанию добавляются следующие теги:

Element,
Software System.

Допустимые дочерние элементы:

!docs,
!adrs,
group,
container,
description,
tags,
url,
properties,
perspectives,
-> (relationship).

container

Ключевое слово определяет контейнер внутри программной системы.

container <name> [description] [technology] [tags] {
    ...
}

По умолчанию добавляются следующие теги:

Element,
Container.

Допустимые дочерние элементы:

!docs,
!adrs,
group,
component,
description,
technology,
tags,
url,
properties,
perspectives,
-> (relationship).

component

Ключевое слово определяет компонент внутри контейнера.

component <name> [description] [technology] [tags] {
    ...
}

По умолчанию добавляются следующие теги:

Element,
Component.

Допустимые дочерние элементы:

!docs,
!adrs,
description,
technology,
tags,
url,
properties,
perspectives,
-> (relationship).

deploymentEnvironment

Ключевое слово предоставляет способ определения среды развертывания (например, разработка, тестирование, промежуточная обработка, live и тому подобное).

deploymentEnvironment <name> {
    ...
}

Допустимые дочерние элементы:

group,
deploymentGroup,
deploymentNode,
-> (relationship).

deploymentGroup

Ключевое слово предоставляет способ определения именованной группы развертывания.

deploymentGroup <name>

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

deploymentNode

Ключевое слово используется для определения узла развертывания.

deploymentNode <name> [description] [technology] [tags] [instances] {
    ...
}

По умолчанию добавляются следующие теги:

Element,
Deployment Node.

Допустимые дочерние элементы:

group,
deploymentNode (узлы развертывания могут быть вложенными),
infrastructureNode,
softwareSystemInstance,
containerInstance,
-> (relationship),
description,
technology,
instances,
tags,
url,
properties,
perspectives.

infrastructureNode

Ключевое слово определяет узел инфраструктуры, который обычно является чем-то вроде балансировщика нагрузки, брандмауэра, службы DNS и тому подобное.

infrastructureNode <name> [description] [technology] [tags] {
    ...
}

По умолчанию добавляются следующие теги:

Element,
Infrastructure Node.

Допустимые дочерние элементы:

(relationship),
description,
technology,
tags,
url,
properties,
perspectives.

softwareSystemInstance

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

softwareSystemInstance <identifier> [deploymentGroups] [tags] {
    ...
}

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

В дополнение к тегам программной системы по умолчанию добавляется тег Software System Instance.

Допустимые дочерние элементы:

(relationship),
description,
tags,
url,
properties,
perspectives,
healthCheck.

containerInstance

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

containerInstance <identifier> [deploymentGroups] [tags] {
    ...
}

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

В дополнение к тегам контейнера, по умолчанию добавляется тег Container Instance.

Допустимые дочерние элементы:

(relationship),
description,
tags,
url,
properties,
perspectives,
healthCheck.

healthCheck

Ключевое слово определяет проверку работоспособности HTTP для экземпляра родительской программной системы или контейнера.

healthCheck <name> <url> [interval] [timeout]

interval измеряется в секундах (по умолчанию 60 секунд), а timeout в миллисекундах (по умолчанию 0 мс).

element

Ключевое слово определяет пользовательский элемент (доступно только в облачном сервисе Structurizr/локальной установке/Lite).

element <name> [metadata] [description] [tags] {
    ...
}

По умолчанию добавляется тег Element.

Допустимые дочерние элементы:

description,
tags,
url,
properties,
perspectives,
-> (relationship).

relationship

-> используется для определения однонаправленной связи между двумя элементами.

Существует два способа определения взаимосвязей. Первый — явно, где вы явно используете идентификатор источника:

<identifier> -> <identifier> [description] [technology] [tags] {
    ...
}

Например:

user -> softwareSystem "Uses"

Второй способ — неявно, когда источником отношения является элемент в области видимости:

-> <identifier> [description] [technology] [tags]

Например:

person user {
    -> softwareSystem "Uses"
}

Это эквивалентно следующему коду, где специальный идентификатор this используется для ссылки на элемент в области видимости:

person user {
    this -> softwareSystem "Uses"
}

По умолчанию добавляется тег Relationship.

С помощью DSL можно создать следующие типы связей:

Источник	Целевой элемент
Person	Person, Software System, Container, Component
Software System	Person, Software System, Container, Component
Container	Person, Software System, Container, Component
Component	Person, Software System, Container, Component
Deployment Node	Deployment Node
Infrastructure Node	Deployment Node, Infrastructure Node, Software System Instance, Container Instance
Software System Instance	Infrastructure Node
Container Instance	Infrastructure Node

Допустимые дочерние элементы:

tags,
url,
properties,
perspectives.

tags

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

tags "Tag 1"
tags "Tag 1,Tag 2"
tags "Tag 1" "Tag 2"

description

Используется для установки описания элемента или представления.

description "Description"

technology

Используется для установки технологии в контейнере, компоненте, узле развертывания, узле инфраструктуры.

technology "Technology"

instances

Используется для задания количества экземпляров узла развертывания. Это может быть либо статическое число, либо диапазон (например 0..1, 1..3, 5..10, 0.. N, 0.., 1..N, 1.. и тому подобное).

instances "4"
instances "1..N"

url

Используется для установки URL-адреса элемента или связи.

url <https://example.com>

properties

Блок properties используется для определения одного или нескольких свойств.

properties {
    <name> <value>
    ...
}

perspectives

Блок perspectives используется для определения одной или нескольких перспектив для элемента или взаимосвязи.

perspectives {
    <name> <description>
    ...
}

!ref

Ключевое слово предоставляет способ ссылки на ранее определенный элемент/взаимосвязь и предназначено для использования с функциями extends или !include. Его можно использовать несколькими способами.

Первый сценарий использования заключается в ссылке на существующий элемент/взаимосвязь, которые были определены с помощью DSL. Это позволяет расширить элемент, на который ссылается данный идентификатор.

!ref <identifier> {
  ...
}

Или, если вы расширяете рабочее пространство на основе JSON, вы можете ссылаться на элемент по его “каноническому имени” и присваивать ему идентификатор.

<identifier> = !ref <canonical name> {
  ...
}

views

Каждая рабочая область также может содержать одно или несколько представлений, определенных с помощью блока views.

views {
    ...
}

Блок views может содержать следующие элементы:

systemLandscape,
systemContext,
container,
component,
filtered,
dynamic,
deployment,
custom,
image,
styles,
theme,
themes,
branding,
terminology,
properties.

Если в рабочей области нет блока views или блок views не определяет никаких представлений, будет определен набор представлений по умолчанию. Определение одного или нескольких представлений в блоке views приведет к удалению этого представления по умолчанию, хотя при необходимости их можно добавить обратно с помощью скрипта:

!script groovy {
    workspace.views.createDefaultViews()
}

systemLandscape view

Ключевое слово используется для определения ландшафтного представления системы.

systemLandscape [key] [description] {
    ...
}

Будет сгенерирован ключ просмотра, если он не указан явно; автоматически сгенерированные ключи просмотра не гарантируют стабильности с течением времени, и информация о макете может быть потеряна при их использовании в сочетании со Structurizr Lite/локально/ облачно.

Допустимые дочерние элементы:

include,
exclude,
autoLayout,
default,
animation,
title,
description,
properties.

systemContext view

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

systemContext <software system identifier> [key] [description] {
    ...
}

Ключ представления будет сгенерирован автоматически, если он не указан явно; автоматически сгенерированные ключи не гарантируют стабильности с течением времени, и информация о макете может быть потеряна при их использовании в сочетании со Structurizr Lite/локально/ облачно.

Допустимые дочерние элементы:

include,
exclude,
autoLayout,
default,
animation,
title,
description,
properties.

container view

Ключевое слово для определения представления контейнера для указанной программной системы.

container <software system identifier> [key] [description] {
    ...
}

Ключ представления будет сгенерирован автоматически, если он не указан явно; автоматически сгенерированные ключи не гарантируют стабильности с течением времени, и информация о макете может быть потеряна при их использовании в сочетании со Structurizr Lite/локально/ облачно.

Допустимые дочерние элементы:

include,
exclude,
autoLayout,
default,
animation,
title,
description,
properties.

component view

Ключевое слово для определения представления компонентов для указанного контейнера.

component <container identifier> [key] [description] {
    ...
}

Ключ представления будет сгенерирован автоматически, если он не указан явно; автоматически сгенерированные ключи не гарантируют стабильности с течением времени, и информация о макете может быть потеряна при их использовании в сочетании со Structurizr Lite/локально/ облачно.

Допустимые дочерние элементы:

include,
exclude,
autoLayout,
default,
animation,
title,
description,
properties.

filtered view

Ключевое слово для определения отфильтрованного представления поверх указанного представления.

filtered <baseKey> <include|exclude> <tags> [key] [description] {
    ...
}

Параметр baseKey определяет ключ системного ландшафта, системного контекста, контейнера или представления компонента, на котором должно основываться это отфильтрованное представление. Режим (include или exclude) определяет, должно ли представление включать или исключать элементы/взаимосвязи на основе предоставленных tags.

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

filtered <baseKey> include "Element,Relationship" [key] [description]

Допустимые дочерние элементы:

default,
title,
description,
properties.

dynamic view

Ключевое слово определяет динамическое представление для указанной области.

dynamic <*|software system identifier|container identifier> [key] [description] {
    ...
}

Первое свойство определяет область видимости и то, что может быть добавлено к представлению:

пользователи и программные системы;
область внутри программной системы: пользователи, другие программные системы и контейнеры;
область применения контейнера: пользователи, другие программные системы, другие контейнеры и компоненты.

Ключ представления будет сгенерирован автоматически, если он не указан явно; автоматически сгенерированные ключи не гарантируют стабильности с течением времени, и информация о макете может быть потеряна при их использовании в сочетании со Structurizr Lite/локально/ облачно.

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

<element identifier> -> <element identifier> [description] [technology]
<relationship identifier> [description]

В динамическом представлении показаны экземпляры связей, которые определены в статической модели. Например, есть две программные системы, определенные в статической модели, с единственной связью между ними, описанной как “Отправляет данные”. Динамическое представление позволяет переопределить описание взаимосвязи, чтобы лучше описать взаимодействие в контексте поведения, которое изображено на диаграмме.

Допустимые дочерние элементы:

autoLayout,
default,
title,
description,
properties.

deployment view

Ключевое слово определяет представление развертывания для указанной области и среды развертывания.

deployment <*|software system identifier> <environment> [key] [description] {
    ...
}

Первое свойство определяет область представления, а второе свойство определяет среду развертывания (которая может быть идентификатором или именем). Комбинация этих двух свойств определяет, что может быть добавлено к представлению:

область применения: все узлы развертывания, узлы инфраструктуры и экземпляры контейнеров в среде развертывания;
область применения программной системы: все узлы развертывания и узлы инфраструктуры в среде развертывания; экземпляры контейнера в среде развертывания, принадлежащие программной системе.

Ключ представления будет сгенерирован автоматически, если он не указан явно; автоматически сгенерированные ключи не гарантируют стабильности с течением времени, и информация о макете может быть потеряна при их использовании в сочетании со Structurizr Lite/локально/ облачно.

Допустимые дочерние элементы:

include,
exclude,
autoLayout,
default,
animation,
title,
description,
properties.

custom view

Ключевое слово используется для определения пользовательского представления (доступно только в облачном сервисе Structurizr/локальной установке/Lite).

custom [key] [title] [description] {
    ...
}

Допустимые дочерние элементы:

include,
exclude,
autoLayout,
default,
animation,
title,
description,
properties.

image view

Ключевое слово используется для определения представления с изображениями (доступно только в облачном сервисе Structurizr/локальной установке/Lite).

image <*|element identifier> [key] {
    ...
}

Внутри блока можно указать источник изображения, используя один из вариантов:

plantuml <file|url>,
mermaid <file|url>,
kroki <format> <file|url> (где format — идентификатор формата, включенный в URL-путь; например http://url/{формат}/...),
image <file|url>.

При использовании этих сервисов нужно указать URL-адрес PlantUML/Mermaid/Kroki и формат: png или svg (необязательно). Эти данные могут быть указаны как свойства набора представлений:

views {
    properties {
        "plantuml.url" "<http://localhost:7777>"
        "plantuml.format" "svg"
        "mermaid.url" "<http://localhost:8888>"
        "mermaid.format" "svg"
        "kroki.url" "<http://localhost:9999>"
        "kroki.format" "svg"
    }
...

}

Ссылки PlantUML (https://plantuml.com/plantuml ), Mermaid (https://mermaid.ink ), и Kroki (https://kroki.io ) могут работать, но при этом:

Информация отправляется стороннему сервису.
Общедоступные сторонние сервисы могут неправильно настроить заголовки CORS, необходимые для работы просмотров изображений.

Допустимые дочерние элементы:

default,
title,
description,
properties.

include

Ключевое слово используется для включения элементов или связей.

Включение элементов

Чтобы включить элементы в представление, используйте одну или несколько инструкций include внутри блока, определяющего представление.

include <*|identifier|expression> [*|identifier|expression...]

Элементы могут быть указаны либо с помощью индивидуальных идентификаторов, подстановочного знака (*), либо выражения свойства. Включение элементов также будет включать в себя отношения между этими элементами.

Идентификатор подстановочного знака (*) работает по-разному в зависимости от типа диаграммы:

представление системного ландшафта: включает всех пользователей и программные системы;
представление системного контекста: программная система, плюс все пользователи и программные системы, которые непосредственно подключены к данной программной системе;
представление контейнера: включает все контейнеры в рамках программной системы в области видимости; плюс пользователей и программные системы, которые непосредственно подключены к этим контейнерам;
представление компонентов: включает все компоненты внутри контейнера в области видимости; плюс пользователей, программные системы и контейнеры (принадлежащие программной системе в области видимости), непосредственно подключенные к ним;
Filtered view: неприменимо;
Dynamic view: неприменимо;
представление развертывания: включает в область действия все узлы развертывания, узлы инфраструктуры и экземпляры контейнеров, определенные в среде развертывания и (необязательно) программной системе.

Логика включения элементов по тегам:

element.tag==<tag>,[tag]: включает элементы, имеющие все указанные теги;
element.tag!=<tag>,[tag]: включает элементы, не имеющие все указанные теги.

Включение связей

Для включения связи в представление, нужно указать индивидуальный идентификатор связи или выражение:

include <identifier|expression> [identifier|expression...]

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

exclude

Ключевое слово используется для исключения элементов или связей.

Исключение элементов

Чтобы исключить определенные элементы, используйте одну или несколько инструкций exclude внутри блока, определяющего представление.

exclude <identifier|expression> [identifier|expression...]

Исключение связей

Чтобы исключить связь в представлении, можно указать индивидуальный идентификатор связи или использовать выражение свойства:

exclude <identifier|expression> [identifier|expression...]

Способы исключить отношения:

relationship.tag==<tag>,[tag] — исключить отношения, имеющие все указанные теги;
relationship.tag!=<tag>,[tag] — исключить отношения, не имеющие всех указанных тегов.

Как альтернативу можно использовать синтаксис выражения отношения следующим образом:

exclude "<*|identifier|expression> -> <*|identifier|expression>"

Комбинации параметров следующие:

-> * — все связи между всеми элементами;
source -> * — все связи от указанного элемента до любых элементов;
-> destination — все связи от любых элементов до указанного элемента;
source -> destination — все связи между указанными элементами.

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

autoLayout

Включает режим автоматической компоновки диаграммы.

autoLayout [tb|bt|lr|rl] [rankSeparation] [nodeSeparation]

Первое свойство — направление ранжирования:

tb — сверху вниз (по умолчанию),
bt — снизу вверх,
lr — слева направо,
rl — справа налево.

Второе свойство — дистанция между рядами в пикселях (по умолчанию: 300); третье свойство — дистанция между узлами одного ряда в пикселях (по умолчанию: 300).

Если в рабочем пространстве DSL явно не определены представления, анализатор DSL автоматически создаст набор представлений по умолчанию с включенной автоматической компоновкой. Чтобы изменить такое поведение, можно (1) описать представления в явном виде, (2) использовать скрипт для отключения автоматической компоновки.

default

Устанавливает представление для отображения по умолчанию.

default

animation

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

animation {
    <identifier> [identifier...]
    <identifier> [identifier...]
}

title

Переопределяет заголовок представления.

title <title>

styles

styles — блок для одного или нескольких стилей элементов/взаимосвязей, используемых при рендеринге диаграмм.

styles {
    ...
}

Допустимые дочерние элементы:

element,
relationship.

element style

Ключевое слово используется для определения стиля элемента. Все вложенные свойства (форма, значок и так далее) являются необязательными.

element <tag> {
    shape <Box|RoundedBox|Circle|Ellipse|Hexagon|Cylinder|Pipe|Person|Robot|Folder|WebBrowser|MobileDevicePortrait|MobileDeviceLandscape|Component>
    icon <file|url>
    width <integer>
    height <integer>
    background <#rrggbb|color name>
    color <#rrggbb|color name>
    colour <#rrggbb|color name>
    stroke <#rrggbb|color name>
    strokeWidth <integer: 1-10>
    fontSize <integer>
    border <solid|dashed|dotted>
    opacity <integer: 0-100>
    metadata <true|false>
    description <true|false>
    properties {
        name value
    }
}

Примечания:

цвета указываются в виде шестнадцатеричного кода (например, #ffff00) или по наименованию цвета (например, yellow);
стили элементов предназначены для работы с облачным сервисом Structurizr/локальной установкой/Lite и могут не полностью поддерживаться форматами экспорта PlantUML, Mermaid и подобными.

relationship style

Ключевое слово используется для определения стиля связи. Все вложенные свойства (толщина, цвет и так далее) являются необязательными.

relationship <tag> {
    thickness <integer>
    color <#rrggbb|color name>
    colour <#rrggbb|color name>
    style <solid|dashed|dotted>
    routing <Direct|Orthogonal|Curved>
    fontSize <integer>
    width <integer>
    position <integer: 0-100>
    opacity <integer: 0-100>
    properties {
        name value
    }
}

Примечания:

цвета указываются в виде шестнадцатеричного кода (например, #ffff00) или по наименованию цвета (например, yellow);
стили связей предназначены для работы с облачным сервисом Structurizr/локальной установкой/Lite и могут не полностью поддерживаться форматами экспорта PlantUML, Mermaid и подобными.

theme

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

theme <default|url>

Значение default — это сокращение от https://static.structurizr.com/themes/default/theme.json, тема Structurizr по умолчанию.

themes

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

themes <url> [url] ... [url]

Значение default — это сокращение от https://static.structurizr.com/themes/default/theme.json, тема Structurizr по умолчанию.

branding

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

branding {
    logo <file|url>
    font <name> [url]
}

terminology

Ключевое слово позволяет переопределить терминологию, используемую при визуализации диаграмм.

terminology {
    person <term>
    softwareSystem <term>
    container <term>
    component <term>
    deploymentNode <term>
    infrastructureNode <term>
    relationship <term>
}

configuration

Внутри блока configuration указываются некоторые параметры.

configuration {
    ...
}

Допустимые дочерние элементы:

visibility,
users,
properties.

visibility

Ключевое слово может быть использовано для настройки видимости рабочей области.

visibility <private|public>

users

Блок users может использоваться для указания пользователей, имеющих доступ к рабочей области для чтения или редактирования. Каждое имя пользователя (например, адрес электронной почты) и пара ролей должны быть указаны в отдельной строке. Допустимыми ролями являются read (только для чтения) и write (чтение-запись).

users {
    <username> <read|write>
}

!docs

Ключевое слово используется для присоединения документации Markdown/AsciiDoc к родительскому контексту (рабочей области, программной системе или контейнеру).

!docs <path> [fully qualified class name]

!adrs

Ключевое слово может используется для присоединения ADR Markdown/AsciiDoc к родительскому контексту (рабочей области, программной системе или контейнеру).

!adrs <path> [fully qualified class name]

Structurizr, описание, перевод (часть 2/3)