Когда интернет-магазин растет, количество взаимодействий между компонентами быстро превышает способность человека держать всю схему в голове. Новый разработчик не понимает, почему сервис заказов пишет в базу данных напрямую, а не через шину событий. Аудитор спрашивает, где именно обрабатывается платёж и кто гарантирует его атомарность. C4-model решает эту проблему, предлагая иерархию абстракции: сначала видимость системы снаружи (Level 1), затем её внутреннее разделение на исполняемые единицы (Level 2). В этой статье мы детально разбираем, как построить эти два уровня для типичного e-commerce, чтобы получить документы, которые реально используются командой, а не висят в вики как артефакт прошлого.
Ситуация и цель
Рассмотрим учебный проект «МагазинЭлектроники». Он состоит из веб-интерфейса, нескольких backend-сервисов и базы данных. Проблема: при добавлении новой функции (например, промокодов) разработчики спорят, куда её добавлять. Одни говорят, что это логика каталога, другие — что это логика оформления заказа. Причина спора — размытые границы ответственности. Наша цель — создать две диаграммы, которые однозначно определяют: кто за что отвечает и как данные перемещаются между этими зонами. Мы не будем рассматривать Level 3 (Components) и Level 4 (Code), так как для определения архитектурных границ достаточно первых двух уровней.
Уровень 1: System Context
Диаграмма контекста (System Context) показывает систему как единый чёрный ящик. Её задача — ответить на вопрос: «Кто взаимодействует с нашей системой и зачем?». На этом уровне мы не пишем про микросервисы, базы данных или очереди. Мы выделяем только акторов (человек или внешняя система) и суть взаимодействия.
Для нашего магазина акторами будут:
- Покупатель: просматривает товары, оформляет заказ, оплачивает.
- Администратор: управляет каталогом, видит статистику продаж.
- Платёжный шлюз: внешняя система, подтверждающая списание средств.
- Сервис доставки: внешняя система, принимающая заявки на курьера.
Важный нюанс: администратор и покупатель — это люди, а платёжный шлюз и доставка — это системы. В PlantUML для людей используется элемент `Person`, а для внешних систем — `System_Ext`. Это визуальное различие помогает читателю сразу понять, кто требует интерфейса, а кто — API-контракта. На этом уровне мы не указываем протоколы (HTTP, gRPC), так как это деталь реализации, которая важна на следующем уровне.
Уровень 2: Container Diagram
Диаграмма контейнеров (Container Diagram) вскрывает «чёрный ящик». Здесь мы определяем технологические единицы, которые могут быть собраны, запущены и управляемы независимо. В современном стеке контейнер — это чаще всего Docker-образ или отдельный процесс. Для нашего магазина контейнерами являются:
- Web Client: SPA на React/Vue, работает в браузере пользователя.
- API Gateway: единая точка входа, маршрутизирует запросы.
- Catalog Service: хранит и предоставляет данные о товарах.
- Order Service: управляет жизненным циклом заказа.
- Payment Service: интегрируется с платёжным шлюзом.
- Database: PostgreSQL, хранилище данных.
- Message Broker: RabbitMQ/Kafka для асинхронных событий.
Главная ценность этого уровня — показ зависимостей. Стрелки между контейнерами должны иметь подписи, указывающие на тип данных и протокол. Например, связь `Order Service` -> `Payment Service` подписывается как `HTTPS JSON: initiate_payment`. Это устраняет двусмысленность: теперь ясно, что это синхронный HTTP-вызов, а не сообщение в очереди.
Определение границ ответственности
Самая сложная часть C4 — не нарисовать квадратики, а правильно разрезать систему на контейнеры. Плохая граница приводит к тому, что сервисы начинают зависеть друг от друга через прямые обращения к базам данных или общие таблицы. Хорошая граница определяется тремя критериями:
- Доменная изоляция: каждый контейнер отвечает за один бизнес-концепт. Catalog Service знает о товарах, но не знает о том, кому продан товар. Order Service знает о заказе, но не знает, сколько стоит товар в инвентаре (он получает цену из Catalog Service).
- Независимое развертывание: если изменение в Catalog Service требует деплоя Order Service, значит, граница нарушена. Они должны общаться через стабильный контракт (API или событие).
- Единая точка отказа: если падает Message Broker, Order Service не должен стать недоступен для чтения своих заказов. Он может временно не отправлять уведомления, но основной функционал должен работать.
Рассмотрим спорный случай: где хранить историю заказов? Если история заказов лежит в базе данных Catalog Service, это ошибка. Каталог описывает «что продаём», а заказ — «кто купил». Эти данные живут в разных доменах. Поэтому Order Service имеет свою базу данных (или схему в общем PostgreSQL), и Catalog Service не имеет прямого доступа к этим данным. Если администратору нужна сводка, он запрашивает её через API Order Service, а не читает таблицу напрямую.
Типы связей и протоколы
На диаграмме контейнеров каждая связь (arrow) должна содержать информацию о том, как именно передаются данные. Это не просто декоративный элемент, а спецификация для разработчиков. Вот таблица, которая поможет выбрать правильный тип связи для различных сценариев в магазине:
| Сценарий взаимодействия | Тип связи | Протокол/Технология | Причина выбора |
|---|---|---|---|
| Покупатель загружает страницу товара | Синхронный запрос | HTTPS / JSON | Требуется немедленный ответ пользователю |
| Order Service подтверждает оплату | Синхронный вызов | HTTPS / JSON | Результат влияет на статус заказа сразу |
| Order Service уведомляет Delivery Service | Асинхронное событие | AMQP / JSON | Доставка не должна ждать подтверждения заказа |
| Analytics Service собирает логи | Поток данных | Kafka / Avro | Высокая нагрузка, требуется сохранение истории |
| Order Service читает данные товара | Синхронный запрос | gRPC / Protobuf | Внутренний вызов, высокая производительность |
Использование асинхронных сообщений (RabbitMQ/Kafka) для событий типа «order_created» критически важно для надёжности. Если Delivery Service временно недоступен, сообщение останется в очереди. При синхронном вызове Order Service получил бы ошибку 503 и мог бы ошибочно пометить заказ как неудачный. Таким образом, выбор протокола — это архитектурное решение о том, насколько устойчива система к сбоям смежных компонентов.
Практический пример: PlantUML
Ниже представлен код для создания обоих уровней. System_Boundary показывает границу программной системы, а не физического сервера. C4-контейнер обозначает исполняемое приложение или хранилище; он не обязан совпадать с Docker-контейнером. Здесь общая БД — учебное упрощение: ответственность за таблицы разделена между сервисами. Пример сохраняет обе внешние системы из диаграммы контекста — оплату и доставку. Код можно скопировать в редактор PlantUML для проверки.
Для просмотра создавайте отдельный документ PlantUML для каждого уровня: диаграмму контекста и диаграмму контейнеров.
@startuml
!include <C4/C4_Context>
title Контекст интернет-магазина
Person(customer, "Покупатель", "Выбирает и покупает товары")
Person(admin, "Сотрудник магазина", "Ведёт каталог")
System(shop, "Интернет-магазин", "Каталог и оформление заказов")
System_Ext(psp, "Платёжный провайдер", "Обрабатывает оплату")
System_Ext(delivery, "Служба доставки", "Доставляет заказ")
Rel(customer, shop, "Оформляет заказ", "HTTPS")
Rel(admin, shop, "Обновляет каталог", "HTTPS")
Rel(shop, psp, "Создаёт платёж", "HTTPS")
Rel(shop, delivery, "Передаёт доставку", "HTTPS")
@enduml
@startuml
!include <C4/C4_Container>
title Контейнеры интернет-магазина
Person(customer, "Покупатель")
System_Ext(psp, "Платёжный провайдер")
System_Ext(delivery, "Служба доставки")
System_Boundary(shop, "Интернет-магазин") {
Container(web, "Веб-приложение", "React", "Пользовательский интерфейс")
Container(gateway, "API-шлюз", "NGINX", "Маршрутизация запросов")
Container(catalog, "Сервис каталога", "Java", "Товары и цены")
Container(orders, "Сервис заказов", "Java", "Жизненный цикл заказа")
Container(payments, "Сервис платежей", "Java", "Связь с провайдером оплаты")
ContainerDb(db, "База данных", "PostgreSQL", "Данные магазина")
ContainerQueue(broker, "Брокер", "RabbitMQ", "События заказов")
}
Rel(customer, web, "Использует", "HTTPS")
Rel(web, gateway, "Запрашивает данные", "HTTPS/JSON")
Rel(gateway, catalog, "Читает каталог", "HTTP/JSON")
Rel(gateway, orders, "Создаёт заказ", "HTTP/JSON")
Rel(orders, payments, "Запрашивает оплату", "HTTP/JSON")
Rel(payments, psp, "Создаёт платёж", "HTTPS")
Rel(orders, delivery, "Передаёт доставку", "HTTPS")
Rel(orders, broker, "Публикует события", "AMQP")
Rel(catalog, db, "Читает и изменяет каталог", "SQL")
Rel(orders, db, "Читает и изменяет заказы", "SQL")
Rel(payments, db, "Читает и изменяет платежи", "SQL")
@enduml
В этом примере мы сознательно не показали связь `web` -> `catalog` напрямую. Все трафик идет через `gateway`. Это упрощает мониторинг и централизует аутентификацию. Также обратите внимание, что `payment` service общается с внешним миром (на Level 1), но на Level 2 он показан как внутренний контейнер, который инкапсулирует логику интеграции. Это позволяет заменить конкретного поставщика платежей (Visa/Mastercard) без изменения остальной архитектуры.
Проверка согласованности уровней
Две диаграммы считаются согласованными, если выполняется правило «соответствия гранулярности». Каждый внешний узел на Level 1 должен иметь своего «представителя» или группу представителей на Level 2. Если на Level 1 мы указали, что система общается с CRM, то на Level 2 должен быть контейнер (например, Integration Service), который содержит логику синхронизации с CRM. Если такого контейнера нет, диаграмма неполна.
Также важно проверить отсутствие «фантомных» связей. Если на Level 2 контейнер A вызывает контейнер B, но на Level 1 эти системы не показаны как взаимодействующие, возникает противоречие. Например, если Analytics Service (который не был показан на Level 1 как внешний) вдруг начинает писать в общую базу данных Order Service, это нарушение границ. Аналитика должна получать данные через события или выгрузки, а не читать рабочие таблицы операционной системы напрямую. Это сохраняет нормализацию данных и предотвращает блокировки.
Типичные ошибки при моделировании
- Монолитная база данных как центр вселенной: Часто рисуют все стрелки идущими к одной базе данных. Это скрывает логические зависимости. Лучше показать, что сервисы общаются через API, а база данных — это деталь реализации конкретного сервиса.
- Отсутствие подписей на стрелках: Стрелка без текста «как» передаются данные заставляет читателя гадать. Всегда указывайте протокол (HTTP, AMQP, TCP) и формат (JSON, Protobuf, CSV).
- Смешение уровней: Попытка показать классы Java или таблицы SQL на диаграмме контейнеров. Это перегрузка. Таблицы — это Level 3/4. На Level 2 мы показываем только «черные ящики» с технологической подписью.
- Игнорирование асинхронности: Моделирование всех процессов как последовательных вызовов. В реальном магазине большинство событий (email, SMS, обновление кэша) происходят асинхронно. Это нужно отражать через очередь сообщений.
Роль системного аналитика
Системный аналитик является главным автором этих диаграмм. Разработчики знают, *как* реализовать функцию, но аналитик знает, *зачем* она существует и какие бизнес-правила её ограничивают. Именно аналитик определяет, что считать отдельным доменом. Например, аналитик решит, что «Лояльность» — это отдельный сервис, а не часть профиля пользователя, потому что правила начисления баллов часто меняются независимо от правил регистрации. Эта бизнес-логика диктует границу контейнера. Аналитик также должен следить за тем, чтобы названия контейнеров отражали бизнес-значение («Order Service», а не «Module 42»), чтобы диаграмму могли читать менеджеры и заказчики.
Итог
Построение C4-диаграмм для интернет-магазина — это не просто художественное упражнение, а инструмент принятия решений. Чёткие границы контейнеров позволяют команде безопасно менять технологии внутри сервисов, зная, что внешние контракты останутся стабильными. Согласованность между Level 1 и Level 2 гарантирует, что никто не упустит важную интеграцию. Начните с простого: определите акторов, затем разбейте систему на 5-7 основных контейнеров, подпишите связи протоколами и проверьте, что каждая внешняя зависимость имеет внутреннего представителя. Используйте ADR для фиксации причин, почему граница прошла именно там, а не там. Это создаст живую документацию, которая будет расти вместе с вашей системой.
