Как нарисовать архитектуру приложения: схема, которую поймут все

Зачем рисовать архитектуру#

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

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

• Ввод новичков. Человек видит систему целиком до того, как откроет первый файл с кодом.
• Обсуждение изменений. Спорить о новой очереди проще, когда все смотрят на одну и ту же картинку и показывают пальцем, куда её поставить.
• Оценка рисков. Видно, какие части держат на себе всё остальное и где одна точка отказа.
• Разговор с бизнесом. Руководителю не нужны классы и таблицы, но нужно понять, почему задача «просто добавить кнопку» затрагивает три системы.

Кому нужна схема и какой уровень детализации выбрать#

Главная ошибка — пытаться показать всё на одной схеме: и пользователей, и базы, и классы. Такую картинку не поймёт никто. Удобнее думать уровнями, как на карте: сначала страна, потом город, потом улица. Этот подход хорошо описывает модель C4, которую предложил Саймон Браун: четыре уровня, каждый следующий — «приближение» одного блока предыдущего.

Что показать на схеме#

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

Отдельно подумайте о характере каждой связи. Синхронный вызов — клиент ждёт ответа: сайт обращается к API, API читает базу. Если вызываемая часть недоступна, падает и вызывающая. Асинхронное взаимодействие — сообщение кладут в очередь и идут дальше, обработка случится позже. Эти две связи ведут себя совершенно по-разному при сбоях, поэтому на схеме их нужно различать с первого взгляда — например, сплошной и пунктирной линией.

Чего на схеме контейнеров быть не должно: отдельных классов, настроек серверов, IP-адресов и всех двадцати таблиц базы. Если без них никак, это другая схема и другой уровень.

Как нарисовать архитектуру приложения: шаг за шагом#

1. 1

   Определите читателя и вопрос

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

2. 2

   Нарисуйте контекст

   Система — одним блоком в центре, вокруг — люди и внешние системы. Подпишите, что идёт по каждой связи: «заказы», «оплата», «уведомления».

3. 3

   Перечислите контейнеры

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

4. 4

   Сгруппируйте по зонам

   Клиенты, сервисы, данные — или по командам, которые за них отвечают. Группа сразу показывает границы ответственности и разгружает схему от лишних цветов.

5. 5

   Проведите и подпишите связи

   Стрелка — от того, кто вызывает, к тому, кого вызывают. На каждой связи — протокол или суть: HTTPS, SQL, gRPC, «события». Синхронное — сплошной линией, асинхронное — пунктиром.

6. 6

   Добавьте легенду

   Короткий блок в углу: что значат цвета, пунктир и иконки. Без легенды договорённости знает только автор.

7. 7

   Проверьте на живом сценарии

   Пройдите по схеме путь одного заказа или одного запроса. Если на каком-то шаге непонятно, куда идти дальше, — на схеме не хватает связи.

8. 8

   Покажите коллегам

   Лучшая проверка — человек, который систему не писал. Его вопросы покажут, что на схеме неочевидно.

Как сделать всё это на доске NodePanel — с иконками, метками, группами и анимированными связями — подробно в руководстве «Схема архитектуры сервиса».

Обозначения: чтобы схему читали без автора#

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

• Подписи на каждой связи. Стрелка без подписи заставляет гадать, что по ней идёт и синхронно ли это.
• Технология в описании блока. «API заказов · Go» говорит больше, чем просто «Бэк».
• Цвет — по зоне или по владельцу, а не ради красоты. Если цвет ничего не значит, лучше один цвет на группу.
• Границы — группами. Рамка «Сервис доставки» показывает, что внутри — наше, а снаружи — чужие системы.
• Внешние системы — нейтральным цветом, чтобы сразу было видно, что их поведение вы не контролируете.
• Легенда в углу — даже если кажется, что всё очевидно.

Пример: схема веб-сервиса доставки еды#

Возьмём условный сервис доставки: покупатели заказывают еду на сайте и в клиенте для iOS и Android, курьеры отмечают статусы, оплата идёт через внешнего провайдера. Нарисуем два первых уровня.

Как держать схему актуальной#

Схема, которая врёт, хуже, чем никакой: ей верят и принимают неверные решения. Устаревает она незаметно — добавили очередь, перенесли файлы в другое хранилище, а картинку поправить забыли. Помогает сочетание привычек и инструментов.

• Назначьте владельца. У каждой схемы — человек, который отвечает за её точность. Обычно это техлид команды.
• Правьте схему в той же задаче, в которой меняется архитектура, — как документацию и тесты.
• Сверяйте раз в квартал. Откройте схему на встрече команды и пройдитесь по блокам: всё ли ещё так.
• Держите дату обновления в названии или в углу схемы — читатель сразу видит, насколько ей можно доверять.

Диаграммы как код. Небольшую схему можно хранить текстом Mermaid прямо в репозитории — тогда она меняется в том же запросе на слияние, что и код, и проходит ревью. Как устроен этот язык, разобрано в статье синтаксис Mermaid: примеры и шпаргалка. В NodePanel такой текст блок-схемы вставляется на доску блоками и связями, а доска копируется обратно в текст.

Схема из исходников. Карта кода в NodePanel разбирает папку или zip-архив проекта прямо в браузере — код не запускается и не уходит на сервер — и строит доски: страницы, маршруты API, вызовы с фронта, таблицы базы и архитектуру (сервисы из docker-compose и зависимости между папками кода). Понимает JavaScript, TypeScript, Python, PHP, Go, Java, Kotlin, C#, Ruby и Rust. Это хорошая отправная точка для уровней контейнеров и компонентов, и при повторной загрузке новое и исчезнувшее помечаются метками. Но карта показывает то, что видно в коде одного проекта: внешние системы, людей и смысл связей на уровне контекста всё равно дорисовывает человек. Подробности — в документации карты кода.

Частые ошибки#

• Всё на одной схеме. Пользователи, контейнеры, классы и таблицы вместе — получается паутина, которую никто не читает. Разведите уровни по разным схемам.
• Связи без подписей. Непонятно, что по ним идёт и ждёт ли вызывающий ответа.
• Нет внешних систем. Схема выглядит самодостаточной, а потом выясняется, что без почтового сервиса не работает регистрация.
• Абстрактные названия. «Сервис 1», «Модуль Б», «Бэк» — читателю нужно знать, что это и на чём сделано.
• Цвета без смысла. Пять цветов без легенды выглядят ярко, но ничего не сообщают.
• Схема ради схемы. Нарисовали к сдаче проекта и больше не открывали. Схема, которой не пользуются, устаревает первой.
• Инфраструктура вперемешку с логикой. Балансировщики, сети и серверы важны, но это отдельная схема развёртывания.

Чек-лист схемы архитектуры#

• Понятно, для кого схема и на какой вопрос отвечает.
• Выбран один уровень детализации, лишнего с других уровней нет.
• Есть все клиенты, сервисы, хранилища и внешние системы этого уровня.
• У каждого блока — понятное имя, у контейнеров — технология.
• Каждая связь направлена и подписана: протокол или суть.
• Синхронные и асинхронные связи различаются с первого взгляда.
• Зоны или владельцы показаны группами, внешние системы отделены.
• Есть легенда и дата обновления.
• По схеме прошли один живой сценарий от начала до конца.
• У схемы есть владелец, и она обновляется вместе с кодом.

Собрать первую схему можно прямо сейчас — без регистрации, в песочнице на главной. А если нужна доска для команды, где схему правят и обсуждают вместе, — на странице схема архитектуры ПО онлайн. Чтобы во время разбора сбоя видеть только упавший компонент и его соседей, пригодится режим «Фокус».