Хабр, привет!
Нас зовут Дмитрий Фролов и Владимир Мясников.

Мы стандартизировали подход по документированию внутренних систем в команде интеграционного тестирования Мир Plat.Form с помощью «Модели С4».

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

Давайте разберемся, что такое «Модель С4» и какие задачи она помогает решать. С чего начать, если вам поступила задача задокументировать «большую» систему – читайте под катом.

Дисклеймер

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

Что такое модель С4

Модель С4 – подход к моделированию архитектуры системы, в котором основной акцент нацелен на простоту нотации и различные уровни абстракции.

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

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

Рисунок 1. Различные уровни абстракции для лучшего понимания архитектуры системы. Рисунок позаимствован с сайта https://c4model.com/.
Рисунок 1. Различные уровни абстракции для лучшего понимания архитектуры системы. Рисунок позаимствован с сайта https://c4model.com/.

Обзор уровней абстракции

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

Уровень 1. Диаграмма контекста

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

Цели диаграммы – ответить на следующие вопросы:

  • Какие пользователи используют документируемую систему?

  • С какими системами взаимодействует документируемая система?

  • Для чего нужны взаимодействия с другими системами?

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

Уровень 2. Диаграмма контейнеров

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

Цели диаграммы – ответить на следующие вопросы:

  • Какие технологии использует система?

  • Из каких контейнеров состоит система?

  • Как контейнеры взаимодействую между собой?

  • Как контейнеры взаимодействую с внешними системами?

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

Легенда для диаграммы контейнеров
Контейнер -  некоторая самостоятельная часть системы, например «Мобильное приложение».
Контейнер - некоторая самостоятельная часть системы, например «Мобильное приложение».
Хранилище данных.
Хранилище данных.
Брокер или очередь сообщений.
Брокер или очередь сообщений.
Группа контейнеров из которых состоит документируемая система.
Группа контейнеров из которых состоит документируемая система.

А также все элементы из «Диаграммы контекста».

Уровень 3. Диаграмма компонентов

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

Цели диаграммы – ответить на следующие вопросы:

  • Из каких компонентов состоит контейнер?

  • Как компоненты взаимодействуют между собой?

  • Как компоненты взаимодействуют с внешними системами?

  • Как пользователи взаимодействуют с компонентами?

Легенда для диаграммы компонентов
Компонент -  абстракция, из которых состоит контейнер.
Компонент - абстракция, из которых состоит контейнер.
Хранилище данных.
Хранилище данных.
Брокер или очередь сообщений.
Брокер или очередь сообщений.
Группа компонентов, из которых состоит контейнер.
Группа компонентов, из которых состоит контейнер.
Пользователь документируемой системы.
Пользователь документируемой системы.
Внешняя система, с которой взаимодействует документируемая система.
Внешняя система, с которой взаимодействует документируемая система.
Отношение между элементами диаграммы. Стрелка направлена от вызывающего к вызываемому.
Отношение между элементами диаграммы. Стрелка направлена от вызывающего к вызываемому.

Уровень 4. Диаграмма кода

Диаграмма кода используется для низкоуровневой детализации системы. На официальной странице модели С4 рекомендовано использовать UML Class diagram/Entity relationship diagram или схожие нотации.

Легенда для диаграммы кода

В рамках настоящей статьи мы не будем отдельно останавливаться на этих нотациях, так как это избыточно и выходит за границы модели С4.

Описываем свою первую систему

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

Моделирование диаграммы контекста

  • В центре диаграммы размещаем элемент «Система»;

  • В верхней части диаграммы размещаем «Пользователей» системы;

  • По периметру «Системы» размещаем элементы «Внешняя система»;

  • Между элементами проводим стрелки от вызывающего к вызываемому. Внутри стрелок описываем какую функцию выполняет взаимодействие.

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

Рисунок 2. Пример диаграммы контекста.
Рисунок 2. Пример диаграммы контекста.

Моделирование диаграммы контейнеров

  • В центре схемы размещаем элемент «Пунктирную рамку»;

  • «Фронт-системы» вписываем в верхнюю часть прямоугольника, «Бэк-системы» вписываем в центре, «Хранилища данных» в самом низу рамки;

  • Над «Рамкой» размещаем «Пользователей» системы;

  • По периметру «Прямоугольной рамки» размещаем «Внешние системы»;

  • Стрелками описываем все интеграции и их технологии.

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

Рисунок 3. Пример диаграммы контейнеров.
Рисунок 3. Пример диаграммы контейнеров.

Моделирование диаграммы компонентов

  • В центре схемы размещаем элемент «Пунктирную рамку»;

  • Внутри рамки размещаем «Компоненты», из которых состоит «Контейнер»;

  • Над «Рамкой» размещаем источники данных, в нижней части «Хранилища данных»;

  • По периметру рамки размещаем «Внешние системы» и «Контейнеры».

Рисунок 4. Пример диаграммы компонентов.
Рисунок 4. Пример диаграммы компонентов.

Моделирование диаграммы кода

Моделировании в нотациях UML Class diagramm/Entity relationship diagram выходит за рамки нашей статьи, так как мы рассматриваем только С4. Таким образом, во избежание избыточности, мы пропустим этот раздел.

Рисунок 5. Пример диаграммы кода (Entity relationship diagram в нотации Crow’s Foot).
Рисунок 5. Пример диаграммы кода (Entity relationship diagram в нотации Crow’s Foot).

Добавляем интерактивность

Для удобства навигации мы рекомендуем использовать интерактивные элементы. В этом разделе мы покажем свою реализацию на примере Confluence.

  • Создаем переход из «Диаграммы контекста» на «Диаграмму контейнеров», пример:

Переход из диаграммы контекста в диаграмму контейнеров.
Переход из диаграммы контекста в диаграмму контейнеров.
  • Создаем переход из «Диаграммы контейнеров» на «Диаграмму компонентов», пример:

Переход из диаграммы контейнеров в диаграмму компонентов.
Переход из диаграммы контейнеров в диаграмму компонентов.
  • Создаем переход из «Диаграммы компонентов» на «Диаграмму кода». Для «Компонентов» следует использовать UML Class diagram, для «Хранилищ данных» следует использовать «Диаграмму базы данных» или «Entity-relationship diagram». Ниже пример с ER-моделью:

Переход из диаграммы компонентов в ER-модель.
Переход из диаграммы компонентов в ER-модель.

Как мы адаптировали нотацию С4 для нужд команды

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

Используем единообразное расположение элементов:

  • Размещаем элемент «Пользователь» в верхней части диаграммы;

  • Размещаем «Хранилища данных» в нижней части диаграммы;

  • Размещаем «Внешние системы» по периметру, обычно слева и справа.

Стараемся делать небольшие диаграммы:

  • Стараемся чтобы диаграмма была размером А4, т.е. полностью умещалась на экран монитора или могла быть распечатана для обсуждения;

  • Если в диаграмме слишком много элементов, объединяем схожие элементы и декомпозируем на отдельной странице, как на примере ниже:

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

Не используем диаграмму компонентов:

Мы приняли решение внутри команды, что для наших целей (Интеграционное тестирование) не требуется диаграмма компонентов, и мы не будем тратить на нее время.

Используем диаграмму последовательности:

Мы приняли решение использовать диаграмму последовательности вместо UML Class diagram/Entity relationship diagram для описания интеграций между системами:

Описываем взаимодействие между системами с помощью диаграммы последовательности.
Описываем взаимодействие между системами с помощью диаграммы последовательности.

Декомпозируем список интеграций:

Если между системами много интеграций, нет смысла проводить 5 отдельных стрелочек. Мы оформляем интеграции как 1 стрелку и декомпозируем их на отдельной странице:

Декомпозируем интеграции на отдельной странице.
Декомпозируем интеграции на отдельной странице.

Вывод

Наша команда работает с десятками систем, и модель С4 позволяет нам сэкономить время на чтение и поиск документации. Мы можем получить всю нужную информацию буквально в 3-4 клика.

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

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

Итоговый результат
Итоговый результат

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

Комментарии (8)


  1. Myclass
    28.07.2022 15:42
    +1

    Спасибо за информацию. О такой нотации не слышал. Покапаюсь. Уверен, что будет полезно. Можно в двух-трех словах описать, чем это нотация будет лучше для использования, чем например BPMN? Например для последней есть куча реализаций например и с симуляцией, что очень помогает прогонять процесс перед тем, как они будут реализованы.


    1. Dima_Frolov Автор
      28.07.2022 15:59

      Привет, у них разная задача:

      • С4 - описать статичную архитектуру;

      • BPMN - описать процесс, последовательность.

      Мы на четвертом уровне описываем интеграционные процессы с помощью UML sequence, это аналог BPMN.

      Почему мы выбрали UML sequence, а не BPMN? Просто наши пользователи больше с этой нотацией знакомы=)


  1. syusifov
    28.07.2022 16:21
    -3

    каждый козел придумывает свой способ обхода огорода


    1. Myclass
      28.07.2022 18:25
      +3

      каждый козел придумывает свой способ обхода огорода

      Конечно это так, и изобретаются мноие вещи вновь и вновь. Но ведь это нас больше движет вперёд, чем тормозит. Вы ведь тоже не под DOS 1.0 работать хотите?

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


  1. ZaurTarchokov
    29.07.2022 10:19

    Какой макрос в Confluence используете для построения диаграмм?


    1. Dima_Frolov Автор
      29.07.2022 12:01

      Draw io + элементы "С4"


  1. stone_evil
    29.07.2022 10:33

    Вы используете какой-нибудь архитектурный репозиторий для моделей, или рисуете каждую из них "на коленке" и потом в confluence связываете url-ами?


    1. Dima_Frolov Автор
      29.07.2022 12:00

      Да используем, вот пример "Легенды" для нотации.