Спецификация диаграммы эффектов v0.1.0

История изменений

v0.2.0

Изменение нотации: обращено направление стрелок, обозначающих эффекты чтения - теперь они идут от операций к ресурсам.

v0.1.0

Изменение концептуальной модели: эффекты косвенного вызова заменены на события.
Улучшена стилистика и точность формулировок.
Удалено "Приложение 3. Философия эффекта".

v0.0.2

Изменение условного обозначения событий: отказ от представления отдельными блоками в пользу стрелок.
Переход к использованию визуального языка C4 Model.

Введение

Диаграмма эффектов — инструмент для разработчиков, предназначенный для визуализации поведения информационной системы через описание её взаимодействия с внешним миром.

Диаграмма эффектов полезна на всех этапах разработки ПО — от первичного анализа до планирования работ и поддержки. Она позволяет с минимальными затратами:

получить целостную картину реализации будущей системы;
оценить трудоёмкость разработки;
декомпозировать систему на модули;
определить порядок выполнения работ;
уменьшить количество регрессий при внесении изменений в систему.

Концептуальная модель

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

В диаграмме эффектов такие устройства моделируются с помощью четырёх основных элементов:

События — типы изменений в окружающем мире, на которые реагирует система;
Ресурсы — части окружающего мира, которые система изменяет в процессе своей работы;
Эффекты — атомарные единицы взаимодействия системы с окружающим миром;
Операции — группы эффектов, образующие атомарные функции системы.

Событие - это обнаруженное изменение части окружающего мира. Изменение определяется посредством сравнения текущего наблюдаемого состояния окружающего мира с его предыдущим известным состоянием. В современных информационных системах отслеживанием изменений обычно занимаются низкоуровневые компоненты — операционные системы, middleware, фреймворки и библиотеки — поэтому на уровне прикладного приложения, события превращаются в вызовы кода системы, переданного в такой компонент.

Примеры событий:

Поступил HTTP-запрос;
Появилось новое сообщение в очереди;
Наступила полночь;
Нажата кнопка мыши.

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

Ресурс

Ресурс - это именованная область изменяемого состояния.

Примеры ресурсов:

Глобальная переменная, хранящая примитивное значение;
Таблица в реляционной БД;
Топик очереди сообщений;
Ресурс REST API внешней системы;

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

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

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

Вызовы API ресурсов являются эффектами работы системы.

Эффект

Эффект — это атомарный на данном уровне абстракции акт чтения или изменения некоторого состояния (ресурса).

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

Примеры эффектов:

Чтение и запись глобальной переменной;
Чтение и запись файла;
Выборка или обновление данных в таблице реляционной БД;
Отправка HTTP-запроса*.

*Симметричный эффект чтения поступающих HTTP-запросов выполняется HTTP-сервером и в систему они попадают уже в виде событий - как вызов метода обработчика запросов.

Эффекты атомарны на одном уровне абстракции. Но на более низком уровне они могут быть реализованы несколькими эффектами. Например, эффект вставки строки в таблицу РСУБД в самой РСУБД приведёт к целой группе эффектов: считывание и запись страницы таблицы, считывание и запись страниц индексов таблицы, обновление последовательности генерации первичных ключей и т.д.

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

Операция

Операция - это атомарная единица полезной работы, которую система предоставляет для своих пользователей. В процессе своей работы операция, как правило, выполняет один или несколько эффектов чтения и записи.

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

Применение

Диаграмма эффектов даёт чёткое представление об операциях системы, необходимое на всех этапах жизненного цикла разработки.

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

Нотация

В основе визуального языка диаграммы эффектов лежит язык модели C4. Это позволяет встраивать диаграмму эффектов в модель C4 на четвёртом уровне — в качестве диаграммы кода.

Нотация диаграммы эффектов бывает двух типов — краткая и полная.

Краткая нотация

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

операции;
ресурсы;
эффекты;
события, генерируемые системой.

Полная нотация

В полной нотации добавляются элементы:

события, генерируемые внешними системами;
описания операций и ресурсов в формате модели C4;
границы контейнера из C4;
внешние системы, базы данных и компоненты из C4;
примечания.

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

Критерии выбора нотации

Краткая нотация подойдёт, если:

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

Полная нотация рекомендуется, если:

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

Пример диаграммы эффектов

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

Диаграмма эффектов с использованием краткой нотации:

Диаграмма эффектов с использованием полной нотации:

Элементы диаграммы эффектов

Операции

Операции обозначаются прямоугольником с именем операции:

Ресурсы

Ресурсы обозначаются прямоугольником с именем ресурса и цветом, отличным от цвета операции:

Эффекты

Эффект модификации ресурса обозначается утолщённой линией красного цвета со стрелкой от операции к ресурсу и сопровождается кратким описанием эффекта:

Эффект чтения ресурса обозначается обычной линией синего цвета со стрелкой от операции к ресурсу и сопровождается кратким описанием считываемых данных:

События

События обозначаются обычной линией с кругом в начале и стрелкой на конце. Стрелка направлена от внешней системы или ресурса-источника к операции и сопровождается описанием в формате C4.

В промежуточной версии диаграммы элемент внешней системы можно опустить:

Описания

Для блоков операций и ресурсов можно указать тип, способ реализации и описание:

Границы контейнера и внешние системы

Элементы, обозначающие границы системы и внешние системы, полностью соответствуют нотации C4:

границы системы обозначаются прямоугольником с указанием имени контейнера, для контура прямоугольника используется светло-серая прерывистая линия;
управляемые внешние системы и базы данных обозначаются прямоугольником и символом «База данных»;
неуправляемые внешние системы и компоненты обозначаются прямоугольниками светло-серого цвета;
неуправляемые базы данных обозначаются светло-серым символом «База данных».

Связь внешних систем с другими элементами диаграммы

Внешние системы связываются с операциями посредством событий:

Ресурсы связываются с внешними системами посредством стрелок с описанием:

Связь ресурсов со сторонними компонентами

Ресурс может быть связан со сторонним компонентом, работающим в том же процессе.

Примечания

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

Приложение 1. Инструментарий

Диаграмма эффектов основана на визуальном языке модели C4, поэтому для её построения можно использовать любой инструмент с поддержкой C4.

Приложение 2. Реализация концептуальной модели в коде

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

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

Ресурсы превращаются в структуру данных и коллекцию методов работы с ней. Это могут быть классы Spring Data агрегата и репозитория, классы события и интерфейса ApplicationEventPublisher (или обёртки вокруг него), классы REST API модели и клиента и т.п.

В контексте бэкендов информационных систем самыми распространёнными видами ресурсов являются:

любые постоянные коллекции данных — таблицы в реляционной СУБД, коллекции в документной СУБД и т.д.;
REST API внешних сервисов;
любые очереди сообщений и шины событий;
изменяемые структуры данных, доступные через глобальные переменные.

События превращаются в методы, передаваемые фреймворку для последующего вызова. Например, метод класса контроллера (RestController в Spring), слушателя (EventListener в Swing), реализация Runnable для таймера и т.д.

В контексте бэкендов информационных систем самыми распространёнными видами событий являются:

получение запроса по сети (@RestController + @*Mapping в случае разработки на Spring). Сейчас популярностью пользуется протокол запросов в REST-стиле, но SOAP, gRPC, CORBA и т.п. также попадают в эту категорию;
появление сообщения в очереди (@JmsListener);
доменное событие или событие приложения (@EventListener);
наступление определённого момента времени (@Scheduled). Два основных типа таких событий:
- наступление заранее известного момента времени (например, полночь вторника);
- истечение определённого времени с момента в прошлом (например, истечение суток с момента создания предыдущего бэкапа).