← Все статьи

C4 для интернет-магазина: контекст и контейнеры с понятными границами

· 9 мин чтения

Как построить согласованные C4 Level 1 и Level 2 диаграммы для интернет-магазина. Разбираем определение границ контейнеров, типы связей и критерии проверки. Пример PlantUML и таблица ответственности сервисов.

Когда интернет-магазин растет, количество взаимодействий между компонентами быстро превышает способность человека держать всю схему в голове. Новый разработчик не понимает, почему сервис заказов пишет в базу данных напрямую, а не через шину событий. Аудитор спрашивает, где именно обрабатывается платёж и кто гарантирует его атомарность. 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 — не нарисовать квадратики, а правильно разрезать систему на контейнеры. Плохая граница приводит к тому, что сервисы начинают зависеть друг от друга через прямые обращения к базам данных или общие таблицы. Хорошая граница определяется тремя критериями:

  1. Доменная изоляция: каждый контейнер отвечает за один бизнес-концепт. Catalog Service знает о товарах, но не знает о том, кому продан товар. Order Service знает о заказе, но не знает, сколько стоит товар в инвентаре (он получает цену из Catalog Service).
  2. Независимое развертывание: если изменение в Catalog Service требует деплоя Order Service, значит, граница нарушена. Они должны общаться через стабильный контракт (API или событие).
  3. Единая точка отказа: если падает 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 для фиксации причин, почему граница прошла именно там, а не там. Это создаст живую документацию, которая будет расти вместе с вашей системой.