Документация на личном опыте: диаграммы и документы, чтобы не нужно было лазить в код
Привет, меня зовут Михаил Пискунов, и я уже более 15 лет работаю в области разработки проектов и системной аналитики.
Начинал свой путь как разработчик и тим-лид, а сегодня специализируюсь на проектировании и архитектуре сложных систем.
В этой статье я поделюсь своим опытом и расскажу про организацию документации проекта, чтобы она была минимальной и достаточной, без необходимости заглядывать в код.
Статья основана на личном опыте, не претендую на универсальность.
Вопрос документации не так прост, как кажется на первый взгляд.
В первую очередь он связан с архитектурой проекта, поскольку правильная документация должна соответствовать структуре и сложным процессам разработки системы.
Во вторую – с человеческим фактором, то есть с возможностями и компетенциями специалистов (аналитиков, разработчиков и других участников команды).
Первый шаг в документации – C4-модель
Когда возникает идея создать проект или заказчик приходит на платформу, первым делом становится создание схемы первого уровня C4-модели. Это простая диаграмма, на которой отображаются:
Сама платформа (можно показать крупные группы сервисов);
Пользователи, которые будут взаимодействовать с системой;
Внешние системы, с которыми будет работать платформа.
На этом этапе начинаются различия в подходах. Например, недавно у нашего вендора был митап по теме «ДБО» (Дистанционное банковское обслуживание – клиентский кабинет банка). После митапа один из коллег задал вопрос: «Считаете ли вы микросервисную архитектуру серебряной пулей?», имея в виду, является ли она универсальным и обязательным решением. Многие коллеги ответили, что нет: в большинстве случаев запуск монолитного проекта проще и логичнее, чем разработка микросервисной архитектуры.
Но есть один важный момент, который напрямую влияет на документацию. В случае монолитной архитектуры полноценная документация, которая позволит разобраться в проекте без просмотра кода, чаще всего отсутствует.
Документирование микросервисной архитектуры
Если проект строится на микросервисной архитектуре, следующим шагом становится схема второго уровня C4-модели. На ней архитектор проекта рисует:
Из каких элементов (микросервисов) состоит платформа;
Как взаимодействуют микросервисы друг с другом;
Как микросервисы обмениваются данными с внешними системами.
В микросервисной архитектуре связи между системами становятся сложнее, поэтому системные аналитики также разрабатывают:
Интеграционные спецификации (описание взаимодействия между системами);
API-спецификации (описание работы API с помощью OpenAPI / Swagger);
Sequence-диаграммы (UML-диаграммы, отображающие последовательность запросов между сервисами);
Паспорт микросервиса (описание его структуры, часто с использованием UML-диаграмм, Data Flow Diagram или части схемы второго уровня C4-модели).
Ещё один важный аспект - использование архитектурных паттернов (устоявшихся подходов). Например, каждый микросервис обычно имеет свою базу данных. Это позволяет системным аналитикам фиксировать структуру базы данных в виде:
Страницы в Confluence с текстовым описанием таблиц и полей;
ER-диаграммы, отображающей связи между таблицами.
Таким образом, документация микросервисного проекта охватывает хранение данных и интеграции, а за системную архитектуру отвечает архитектор.
Проблемы документирования монолитной архитектуры
Если проект строится по монолитной архитектуре, системные аналитики могут задокументировать только:
Большую базу данных и её связи (но такие схемы часто становятся нечитабельными);
Sequence-диаграммы взаимодействия с внешними сервисами (если такие вообще будут).
Основные проблемы документирования монолита:
Сложность понимания структуры БД. Представьте ватман с сотнями или тысячами таблиц и связей – разобраться в нём крайне трудно.
Высокая связанность компонентов. Разработчики часто напрямую обращаются к базе данных или сервисам, создавая жёсткие зависимости. Это приводит к тому, что любое изменение в коде может повлиять на весь проект.
Отсутствие технической документации. Аналитики не могут детально описать код, так как для этого требуется уровень знаний программистов (ОOП, паттерны проектирования, фреймворки и т. д.). В итоге документация не создаётся, и все разбираются в проекте, напрямую работая с кодом.
Какие инструменты нужны для документирования монолита
Для описания монолитной архитектуры необходим другой набор инструментов:
Диаграмма компонентов – показывает, какие части есть в системе и как они взаимодействуют;
Диаграмма классов и объектов – описывает работу ООП (объектно-ориентированного программирования) в проекте;
Sequence-диаграмма – детализирует порядок выполнения запросов и взаимодействие модулей (речь про интеграции с внешними сервисами или входящие запросы от фронтенда).
Но чтобы создать такую документацию, системные аналитики должны разбираться в языке программирования и фреймворке не хуже разработчиков. В реальности это невозможно. Аналитиков не обучают ООП, паттернам, ACID-принципам, транзакциям и другим специфическим вещам.
Ниже приведён типичный пример требований из вакансий для системных аналитиков. Как видно, от них не ожидают знаний, присущих разработчикам, таких как ООП, классы, наследование, паттерны программирования и т.д.
Ожидания от кандидатов:
- Опыт написания Use cases / User Strories
- Опыт использования методологий функционального, информационного и процессного моделирования в нотациях BPMN и UML
- Знание SQL на уровне базовых запросов
- Понимание и опыт работы с микросервисной архитектурой
- Понимание принципа работы очередей: rabbitMQ, Kafka
- Умение быстро разбирать формат сообщений и осваивать принципы любого протокола API
Даже у программистов на одном языке могут быть разные подходы. Пример из языка PHP:
В фреймворке Symfony используется паттерн Data Mapper для работы с базой данных;
В Laravel – Active Record.
Это совершенно разные подходы к работе с базой данных. Если даже не все разработчики знают такие нюансы, как их может знать аналитик? Как аналитик может составить полноценные диаграммы компонентов и диаграммы классов, если он не имеет представления о том, что происходит внутри "под капотом"?
Сравнительная таблица документации для различных архитектур проектов
Тип документации | Монолитная | Микросервисная архитектура |
C4-модель (уровень 1) для описания контекста использования платформы | Схему обычно рисуют для бизнеса или клиентов, поскольку для технических специалистов требуется больше конкретики | |
C4-модель (уровень 2) для описания контейнеров | Малоинформативна, так как напоминает уровень 1 | Самый важный документ по архитектуре проекта |
C4-модель (уровень 3) для описания компонентов системы | Схемы необходимы, иначе придётся использовать подход "First Code" и разбираться в исходном коде. Однако, на практике маловероятно, что у вас будут такие схемы, и это является проблемой. | Схемы создаются по необходимости или не создаются вовсе. Для системных аналитиков, как правило, важны данные о том, как микросервис хранит данные, какая в нём бизнес-логика и какие есть интеграции. Всё остальное остаётся на усмотрение разработчика. Поэтому подобных схем, скорее всего, либо не будет, либо они будут единичными. |
C4-модель (уровень 4) в виде диаграммы классов для описания программного кода (классы, методы, аттрибуты) | Системные аналитики такого не умеют, а разработчики обычно не имеют на это времени. Мне трудно представить, когда эта диаграмма может быть действительно необходима. Разве что для описания какого-то сервиса на основе статических классов, но это обычно остаётся на усмотрение программиста. В целом, у вас, скорее всего, не будет подобных схем, поскольку они не требуются на практике. | |
Диаграммы последовательности (Sequence) для описания интеграций | Нужны и будут, поскольку скорее всего ваш фронтенд будет обращаться к платформе через API, а также для описания интеграций с внешними сервис-провайдерами. | Очень важный элемент документации, и они точно будут в большом количестве, так как это основа описания взаимодействия между микросервисами, а также с фронтендом и внешними сервисами. |
ER-диаграммы для описания структуры базы данных | Обязательно будут, но целиком просмотреть базу данных будет сложно из-за большого количества таблиц. Поэтому вы вряд ли увидите всю ER-диаграмму проекта целиком; скорее всего, она будет фрагментированная и разделена на различные логические части. | Обязательно будут, при этом, благодаря разделению на микросервисы, схему базы данных каждого микросервиса можно будет просмотреть целиком, что очень удобно. |
Диаграмма развёртывания (Deployment Diagram) для отображения физического развертывания на сервере | Диаграмма развёртывания очень полезна для DevOps-команды. В монолитной архитектуре она будет содержать меньше компонентов и будет проще. В микросервисной архитектуре для каждого микросервиса будет своя диаграмма. | |
Диаграмма вариантов использования (Use Case Diagram) для описания кейсов использования | Use Cases являются важной частью описания вариантов использования в бизнес-требованиях. Поэтому подобные диаграммы регулярно встречаются в документации, независимо от архитектуры проекта. | |
Диаграмма данных (Data Flow Diagram, DFD) для иллюстрации потоков данных в системе, облегчая понимание процессов | Скорее всего, это будет использоваться редко. Используется только в случае, если нужно пояснить какой-то процесс и передачу данных в нём в общем виде. Например: Процесс "Оформление заказа" получает данные от "Пользователя", передаёт их в "Систему обработки заказов", а затем результат передаётся в "Систему платежей". | |
Диаграмма состояний (State Diagram) для отображения возможных состояний объекта (например, как меняется статус заказа) | На практике третий вид диаграмм по популярности у системных аналитиков. Например, можно показать, как меняется статус заказа: Статусы заказа: "Новый" → "Ожидает оплаты" → "Оплачен" → "Выполнен". | |
BPMN для описания бизнес-процессов | Очень важный и полезный инструмент для описания любых бизнес-процессов. Более того, без этих диаграмм не обойтись, если в проекте будет использоваться бизнес-процессинг на основе Camunda или какой-либо подобной системы. | |
Диаграмма объектов (Object Diagram), чтобы показать экземпляры классов и связи между ними | Почти никто не использует, поскольку это ещё сложнее, чем диаграммы классов. Системным аналитикам подобный уровень абстракции не нужен, а разработчики и сами всё знают, как делать в рамках своего языка программирования. Поэтому у вас такой документации, скорее всего, не будет, да и не нужно. | |
Диаграмма активности (Activity Diagram) для описания последовательности шагов в рабочем процессе системы | Иногда вспомогательно используют такую диаграмму для описания шагов, например, порядка действий: "Пользователь оформляет заказ" → "Система проверяет товар" → "Обработка платежа" → "Доставка". | |
Документация в других архитектурных подходах
Сервис-ориентированная архитектура по сути является набором монолитов или крупных сервисов, поэтому для каждого сервиса будет использоваться документация как для монолитной архитектуры, так и для микросервисной архитектуры, но в контексте сервисов.
Бессерверная (serverless) архитектура говорит о другом. Здесь речь идёт о том, что мы используем облачную архитектуру "под ключ" (например, Google, Amazon, Яндекс) и как будто у нас безлимитный большой сервер. На самом деле вычислительные ресурсы выделяются динамически под конкретные запросы, а не представляют собой некий «большой сервер». Чаще всего на serverless-архитектуре вырастают монолитные проекты, но нам ничего не мешает сделать микросервисную архитектуру. Поэтому набор документации будет зависеть от строения платформы, а сама "бессерверность" никак на не повлияет на состав документации.
Событийно-ориентированная архитектура подразумевает использование паттерна микросервисов "Event-Driven Architecture" (EDA). Это означает, что у нас используются микросервисы, и, соответственно, документация будет такой же, как для микросервисной архитектуры.
Выводы
Из-за сложности описания монолитных архитектур техническая документация в таких проектах чаще всего оказывается неполной. Разработчики и системные аналитики вынуждены обращаться к коду, чтобы разобраться в устройстве системы. Однако, когда функциональность выделяется в микросервис, команда сразу стремится задокументировать его работу. Это говорит о том, что необходимость в документации возникает на интуитивном уровне.
Поэтому, если вы планируете создавать монолит, будьте готовы к тому, что у вас, скорее всего, не будет полной документации. Конечно, какая-то документация всё же будет, но работа с исходным кодом по-прежнему останется вынужденной как для системных аналитиков, так и для разработчиков.
При разработке микросервисной архитектуры я рекомендую сразу создавать полную документацию, так как это не только полезно, но и приятно.
Какой подход к архитектуре я считаю оптимальным, расскажу в следующих статьях. Данная статья была посвящена исключительно документации.
Если у вас есть другое мнение или ваш опыт показывает, что документацию монолита можно без проблем составить системными аналитиками с текущим уровнем знаний, а также если у вас есть другие вопросы по теме — буду рад обсудить.
