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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Вывод

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

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

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

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