Документирование архитектуры: введение

Автор оригинала: Vladimir Ivanov
  • Перевод

Привет, меня зовут Владимир Иванов, и я архитектор ПО в компании EPAM. В своей работе мне постоянно приходится документировать программные решения, которые предстоит создать. Я решил поделиться некоторыми аспектами этой деятельности с вами, ведь вам тоже это может пригодиться.


Как вы рисуете диаграммы для вашего ПО? На какие вопросы они должны ответить? Зачем рисовать что-либо вообще? Давайте разберёмся.



Одна из обязанностей архитектора решений заключается в документировании архитектуры, чтобы передать её всем заинтересованным сторонам проекта: руководителю проекта, техническому директору, спонсору проекта, командам разработчиков, QA и другим. Это необходимо для того, чтобы:


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

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



Photo by ThisisEngineering RAEng / Unsplash


Рассмотрим примеры


Любое ПО довольно сложное. И первое, что можно сделать, чтобы задокументировать его — попытаться нарисовать какую-то диаграмму, которая бы включала всё. Конечно, эта попытка сразу бы провалилась. Представьте, что мы хотим задокументировать какое-то относительно простое решение, скажем, мой блог. Он работает на Ghost CMS, данные хранятся в базе данных MySQL; в качестве веб-сервера используется Apache. Запросы обрабатываются веб-сервером, все запросы перенаправляются с http на https и отправляются в CMS. CMS проверяет токены и запрашивает содержимое базы данных, включая страницы, сообщения в блогах и плагины. Все три компонента работают в виртуальной машине в GCP в сети по умолчанию в отдельной организации. Система доступна читателям, контент-менеджерам, которые могут добавлять новый контент и редактировать текущий. Системные администраторы могут изменять систему через облачную консоль. Если включить всю эту информацию в одну диаграмму, вот что получится:



Возможно кто-то скажет, что это вполне приличная диаграмма, однако у неё всё же есть ряд недостатков:


  • Перегруженная. Чтобы ответить на какой-то конкретный вопрос, нужно долго искать детали.
  • Неполная. Попробуйте, опираясь на диаграмму, ответить на вопросы: в скольких регионах развёрнута система; резервная копия создаётся в виртуальной машине или в базе данных; где хранятся изображения; как пользователи проходят аутентификацию. Вы не найдёте ответы на эти вопросы в диаграмме.
  • Противоречивая. Много непонятных условных обозначений. Зачем нужны зелёные, синие и жёлтые прямоугольники? Что они означают?

Я хотел поговорить о представлениях архитектуры (views) и “точках зрения”(viewpoints), как это описано в книге "Документировании архитектуры программного обеспечения" SEI, но это слишком академичный подход. Поэтому сокращу свою мысль до следующих утверждений:


  1. Вы не можете разместить всю информацию на одном изображении.
  2. Более того, вы не должны этого делать.
  3. Вместо этого вы предоставляете набор картинок, чтобы каждая из них идеально подходила для конкретного стейкхолдера, человека, заинтересованного в вашем проекте.
    Есть несколько подходов к этому (Модули-Компоненты и Разъёмы-Распределения, Подход C4 и т. д.), Неважно, что вы выберете. Главное, чтобы один человек одновременно получал максимум информации за минимальный период времени.

Разделите проблемы


Если говорить про нашу систему — блог, то у нас есть следующие заинтересованные стороны (они же стейкхолдеры):
· спонсор проекта,
· автор блога,
· системный администратор,
· контент-менеджер,
· читатель.


И у каждого свои запросы:



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


С кем взаимодействует система?



Эта диаграмма называется контекстной диаграммой (Context Diagram, по модели C4), которая показывает именно то, с какими агентами общается система. Здесь есть блок "Аналитика". Я забыл о ней, когда рисовал первую диаграмму, но, глядя на определённый уровень, можно сосредоточиться на определённых аспектах и ​​ничего не пропустить.


Как и где система развернута?



Deployment Diagram


На этой диаграмме видно, что решение развернуто на облачной платформе Google, на одной виртуальной машине в одной сети в пределах одного региона, доступ защищен облачным IAM. В основном она отвечает на вопрос, сколько денег примерно стоит решение (20-30 долларов в месяц в зависимости от региона и размера виртуальной машины), видно, что оно плохо масштабируется и требует перепроектирования в случае резкого увеличения нагрузки. Кроме того, нет резервной копии БД.
Но эта диаграмма не показывает, какие компоненты развернуты на виртуальной машине, для этого нужна другая.
Таким образом, мы фокусируемся на определённых аспектах одновременно. Согласитесь, так гораздо легче понять информацию.


Какова функциональность системы?



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


Резюме


В этой статьей я хотел показать, как определить проблемы и предоставить соответствующие Views. Конечно, в по-настоящему крупном проекте до вывода продукта в продакшн ещё многое предстоит сделать того, что обычно содержится в документе, который называется «Документация архитектуры решения». Об этом расскажу в следующей публикации.

EPAM
Компания для карьерного и профессионального роста

Похожие публикации

Комментарии 2

    +2

    Что-то вроде обо всем, а по факту ни о чем.


    Хочется увидеть конкретики, инструментарий и подходы, которые можно применять в работе.

      +1
      Мне кажется, что если дать развёрнутый комментарий к статье, то он будет больше самого текста.
      Поэтому напишу кратко:
      1. Автору спасибо за затронутую тему — тема интересная и актуальная, надеюсь серия будет продолжена.
      2. Согласен с тезисом, что давать читателю ту информацию, которая соответствует области его интересов наиболее корректно. Только, как мне кажется, это относится в первую очередь к специализированным stakeholders, а часто бывает запрос от топ-а или какого-нить заказчика такой «дайте, пожалуйста, информацию про систему одной картинкой, ну максимум двумя — чтобы всё ключевое было отражено» — и такая bullshit диаграмма как раз должна быть очень полезна (возможно, что делать её нужно не архитектору, а команде из архитектора, дизайнера и т.п.) — делают же инфографику по сложным всяким штукам. Так что и такие диаграммы нужны. То, что не удалось автору на первой диаграмме показать все аспекты – ну что ж, есть куда развиваться .
      3. Касательно примеров. Текст примеров и вопросы, которые должны быть отражены на соответствующих диаграммах вполне понятны, тогда как сами диаграммы получения ответов на вопросы требуют усилия. Например, деплоймент — из него должно быть понятно, что, где и как размещено.

        Ок, что мы видим на диаграмме:
        • браузер
        • Протокол HTTPs
        • Google Cloud Platform
        • Регион – Европа (уже надо приложить усилия, чтобы понять – а зачем здесь регион?)
        • Сеть по-умолчанию (зачем она нужна здесь?)
        • Вычислительный узел (что это?)
        • Cloud IAM
        • И три пиктограммы – шестиугольники – два побольше, один поменьше (и опять непонятно, что это)


        А что должна показать диаграмма по мнению автора
        « В основном она отвечает на вопрос, сколько денег примерно стоит решение (20-30 долларов в месяц в зависимости от региона и размера виртуальной машины), видно, что оно плохо масштабируется и требует перепроектирования в случае резкого увеличения нагрузки. Кроме того, нет резервной копии БД.».
        Давайте разберём:
        • Из диаграммы не следуют стоимость — просто потому, что там она не указана. Скорее стоимость будет указана не на диаграмме, а документедокументе с расчётом общей стоимости владения системой или стоимостью её обслуживания (именно это будет интересно спонсору, а не диаграмма развёртывания), где будут расписаны все статьи расходов — инфраструктура, лицензии, саппорт и т.п… Напротив, из самой первой диаграммы хотя бы можно понять, что это именно виртуальная машина GCP, что какие специалисты возможно потребуются для обслуживания
        • Из диаграммы не очевидно, плохо или хорошо может быть масштабируемо решение (так как не понятно, что такое вычислительный узел и что он в себя включает) и скорее всего для понимания этого, нужно указать в явном виде, что вычислительный узел только один или же наоборот их может быть несколько.
        • Из диаграммы не видно не то, что нет резервной копии БД, а даже что такая БД есть. Зато это видно из первой диаграммы, которая приведена в качестве примера «как не стоит делать».
        • Ну и уж конечно не видно (на мой, разумеется, взгляд), что решение требует перепроектирования в случае резкого увеличения нагрузки.



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

      P.S.
      А причём здесь hub GCP? нет ни слова, связанного с какими-то аспектами работы GCP (с тем же успехом, здесь можно оставить любого облачного провайдера, предоставляющего IaaS).

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

      Самое читаемое