[Перевод] Документирование архитектуры: введение
Привет, меня зовут Владимир Иванов, и я архитектор ПО в компании EPAM. В своей работе мне постоянно приходится документировать программные решения, которые предстоит создать. Я решил поделиться некоторыми аспектами этой деятельности с вами, ведь вам тоже это может пригодиться.
Как вы рисуете диаграммы для вашего ПО? На какие вопросы они должны ответить? Зачем рисовать что-либо вообще? Давайте разберёмся.
Одна из обязанностей архитектора решений заключается в документировании архитектуры, чтобы передать её всем заинтересованным сторонам проекта: руководителю проекта, техническому директору, спонсору проекта, командам разработчиков, QA и другим. Это необходимо для того, чтобы:
- понять, из каких компонентов состоит система;
- как эти компоненты коммуницируют друг с другом;
- как и где размещены разные элементы;
- соответствует ли требованиям система в целом.
Отсутствие этой информации может легко привести к нарушениям соблюдения сроков проекта, сверхурочной работе или отмене.
Photo by ThisisEngineering RAEng / Unsplash
РАССМОТРИМ ПРИМЕРЫ
Любое ПО довольно сложное. И первое, что можно сделать, чтобы задокументировать его — попытаться нарисовать какую-то диаграмму, которая бы включала всё. Конечно, эта попытка сразу бы провалилась. Представьте, что мы хотим задокументировать какое-то относительно простое решение, скажем, мой блог. Он работает на Ghost CMS, данные хранятся в базе данных MySQL; в качестве веб-сервера используется Apache. Запросы обрабатываются веб-сервером, все запросы перенаправляются с http на https и отправляются в CMS. CMS проверяет токены и запрашивает содержимое базы данных, включая страницы, сообщения в блогах и плагины. Все три компонента работают в виртуальной машине в GCP в сети по умолчанию в отдельной организации. Система доступна читателям, контент-менеджерам, которые могут добавлять новый контент и редактировать текущий. Системные администраторы могут изменять систему через облачную консоль. Если включить всю эту информацию в одну диаграмму, вот что получится:
Возможно кто-то скажет, что это вполне приличная диаграмма, однако у неё всё же есть ряд недостатков:
- Перегруженная. Чтобы ответить на какой-то конкретный вопрос, нужно долго искать детали.
- Неполная. Попробуйте, опираясь на диаграмму, ответить на вопросы: в скольких регионах развёрнута система; резервная копия создаётся в виртуальной машине или в базе данных; где хранятся изображения; как пользователи проходят аутентификацию. Вы не найдёте ответы на эти вопросы в диаграмме.
- Противоречивая. Много непонятных условных обозначений. Зачем нужны зелёные, синие и жёлтые прямоугольники? Что они означают?
Я хотел поговорить о представлениях архитектуры (views) и «точках зрения»(viewpoints), как это описано в книге «Документировании архитектуры программного обеспечения» SEI, но это слишком академичный подход. Поэтому сокращу свою мысль до следующих утверждений:
- Вы не можете разместить всю информацию на одном изображении.
- Более того, вы не должны этого делать.
- Вместо этого вы предоставляете набор картинок, чтобы каждая из них идеально подходила для конкретного стейкхолдера, человека, заинтересованного в вашем проекте.
Есть несколько подходов к этому (Модули-Компоненты и Разъёмы-Распределения, Подход C4 и т. д.), Неважно, что вы выберете. Главное, чтобы один человек одновременно получал максимум информации за минимальный период времени.
РАЗДЕЛИТЕ ПРОБЛЕМЫ
Если говорить про нашу систему — блог, то у нас есть следующие заинтересованные стороны (они же стейкхолдеры):
· спонсор проекта,
· автор блога,
· системный администратор,
· контент-менеджер,
· читатель.
И у каждого свои запросы:
Можно сказать, что спонсор проекта вообще не интересуется диаграммами: ему требуется только стоимость эксплуатации в долларах. Однако системный администратор хочет видеть диаграммы, отвечающие на следующие вопросы:
С кем взаимодействует система?
Эта диаграмма называется контекстной диаграммой (Context Diagram, по модели C4), которая показывает именно то, с какими агентами общается система. Здесь есть блок «Аналитика». Я забыл о ней, когда рисовал первую диаграмму, но, глядя на определённый уровень, можно сосредоточиться на определённых аспектах и ничего не пропустить.
Как и где система развернута?
Deployment Diagram
На этой диаграмме видно, что решение развернуто на облачной платформе Google, на одной виртуальной машине в одной сети в пределах одного региона, доступ защищен облачным IAM. В основном она отвечает на вопрос, сколько денег примерно стоит решение (20–30 долларов в месяц в зависимости от региона и размера виртуальной машины), видно, что оно плохо масштабируется и требует перепроектирования в случае резкого увеличения нагрузки. Кроме того, нет резервной копии БД.
Но эта диаграмма не показывает, какие компоненты развернуты на виртуальной машине, для этого нужна другая.
Таким образом, мы фокусируемся на определённых аспектах одновременно. Согласитесь, так гораздо легче понять информацию.
Какова функциональность системы?
На этой схеме видно, какие функции CMS блога доступны. Так, контент-менеджеры и авторы блогов могут создавать посты и страницы, загружать изображения и встраивать сторонний контент. Также видно, что CMS сама выполняет аутентификацию пользователей.
Получается, мы смогли ответить на большинство вопросов с помощью трёх простых диаграмм.
РЕЗЮМЕ
В этой статьей я хотел показать, как определить проблемы и предоставить соответствующие Views. Конечно, в по-настоящему крупном проекте до вывода продукта в продакшн ещё многое предстоит сделать того, что обычно содержится в документе, который называется «Документация архитектуры решения». Об этом расскажу в следующей публикации.
