de_DEen_USes_ESfa_IRfr_FRhi_INid_IDjapl_PLpt_PTru_RUvizh_CNzh_TW

Глубокое погружение в уровень 3 модели C4: Освоение диаграмм компонентов для раскрытия внутренней структуры и ответственности

Что такое диаграмма компонентов C4?

Диаграмма компонентов — этоУровень 3в модели C4 Саймона Брауна. Она фокусируется наодном конкретном контейнере (с диаграммы контейнеров уровня 2), чтобы показать:

The Ultimate Guide to C4 Model Visualization with Visual Paradigm's AI Tools - ArchiMetric

  • Логические составные частилогические строительные блоки (компоненты), из которых состоит этот контейнер.

  • Как эти компонентывзаимодействуют друг с другом.

  • Ответственности итехнологии реализации (на более высоком уровне, чем классы — думайте о Spring Beans, модулях, сервисах, контроллерах, фасадах и т.д.).

  • Ключевыеинтерфейсы иликонтракты между компонентами (часто подразумеваемые через отношения).

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

Примеры компонентов:

  • REST-контроллер / Веб-контроллер

  • Сервис / Сценарий использования / Прикладной сервис

  • Репозиторий / Объект доступа к данным

  • Модель домена / Сущность

  • Безопасность / Модуль аутентификации

  • Отправитель уведомлений

  • Фасад внешней системы

  • Движок бизнес-правил

  • Слой кэширования

Схема остаетсялогической / достаточно независимой от реализации— без атрибутов классов, сигнатур методов или полных деталей классов UML (это уровень 4 кода, который опционален и редок).

Когда создавать диаграмму компонентов

Создавать (и поддерживать) диаграмму компонентовтолько когда:

  • Выбранный контейнер —достаточно сложныйчтобы его внутренняя структура не была очевидной из названия и описания.

  • Новые члены команды (особенно разработчики backend) часто спрашивают: «Как на самом деле реализована функция X внутри этого сервиса/API?»

  • Вырефакторите, разделяете, илиизвлекаетелогику внутри контейнера и хотите уточнить границы/ответственность.

  • Вы проводите детальныеобсуждения архитектуры, обзоры кода, или передача обязанностей в режиме on-call для конкретного контейнера.

  • Вы хотите документировать ключевые архитектурные решения внутри контейнера (например, архитектура в виде шестигранника, вертикальные срезы, разделение CQRS, точка контроля безопасности).

  • Вы выявили технический долг, божественные классы, или жесткая связанность внутри контейнера и хотите визуализировать текущее состояние до очистки.

  • Вы внедряете старших разработчиков/архитекторов, которым нужно быстро понять структуру модулей.

НЕТ создавать диаграммы компонентов для:

  • Простые контейнеры (CRUD API с одним контроллером + одной службой + одним репозиторием — очевидная структура).

  • Большинство микросервисов (часто настолько малы, что уровень контейнера достаточен).

  • Контейнеры фронтенда (приложения React/Vue — обычно лучше показывать с помощью деревьев компонентов или storybook).

  • Когда уровень 2 (контейнер) + хорошая структура кода/именование уже передают всё необходимое.

Симон Браун рекомендует: Большинство команд могут остановиться на уровне 1 + 2. Переходить на уровень 3 только для сложных / рискованных / ключевых / с высокой частотой изменений контейнеров.

Зачем использовать диаграммы компонентов? (Ключевые преимущества)

  • Уточняет внутренние обязанности — Показывает разделение ответственности (например, контроллеры против служб против доступа к данным против внешней интеграции).

  • Выявляет связанность и зависимости — Позволяет увидеть «бог-компоненты», циклические зависимости или чрезмерную зависимость от кода инфраструктуры.

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

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

  • Позволяет проводить обзоры архитектуры и моделирование угроз — Указывает, где происходят валидация, авторизация, логирование и т.д.

  • Архитектура как код — При хранении в PlantUML → версионируется вместе с кодовой базой, сравнимый, подлежит проверке в запросах на изменение.

  • Масштабирует коммуникацию — Старшие разработчики заботятся о ответственности компонентов; младшие — о том, куда поместить новый код.

Как создать отличную диаграмму компонентов (пошаговое руководство + лучшие практики)

  1. Выберите ОДИН контейнер — Начните с самого сложного или критически важного (часто основной API / сервис бэкенда).

  2. Скопируйте контекст с уровня 2 — Включите внешних участников (другие контейнеры, люди, внешние системы), взаимодействующие с этим контейнером.

  3. Нарисуйте границу контейнера — Используйте Граница_Контейнера в PlantUML, чтобы чётко обозначить «внутри этого контейнера».

  4. Определите компоненты — Задайте вопросы:

    • Какие основные модули / Spring Beans / пакеты / ограниченные контексты находятся внутри?

    • Где приходят входящие запросы? (контроллеры/обработчики)

    • Где организуется бизнес-логика?

    • Где происходит доступ к данным / кэширование / валидация?

    • Где обрабатываются общие вопросы (безопасность, логирование)?

    • Есть ли фасады / слои защиты от коррупции для устаревших/внешних систем?

  5. Добавьте технологию и краткое описание — Название, технология (Spring Service, .NET Handler, Go Module и т.д.), краткое назначение (менее 15 слов).

  6. Определите взаимодействия — Покажите направление и цель (использует, вызывает, читает из, публикует события). Протокол часто опускается на этом уровне.

  7. Рекомендуемые практики

    • Ограничьте охват — Максимум 6–12 компонентов на диаграмму. Если больше → создайте направленные поддиаграммы (например, «срез аутентификации»).

    • Давайте осмысленные имена — Предпочтение отдается «Сервису размещения заказов» вместо «OrderService».

    • Покажите ответственность, а не классы — Избегайте перечисления каждого класса; группируйте логически.

    • Используйте иконки умеренно — Только если они уточняют технологию (иконки Spring, .NET).

    • Включите легенду — Помогает новым читателям.

    • Сохраняйте чистоту компоновки — РАСПОЛОЖЕНИЕ_С_ЛЕГЕНДОЙ(), РАСПОЛОЖЕНИЕ_СВЕРХУ_ВНИЗ().

    • Версия в репозитории — Файлы .puml рядом с кодом контейнера.

    • Итерируйте — Обновляйте во время спринтов рефакторинга или ежеквартальных проверок архитектуры.

Пример PlantUML – API-приложение системы интернет-банкинга (стиль классического банка Big Bank plc)

Вот пример промышленного уровня, использующий официальную библиотеку C4-PlantUML — наиболее часто упоминаемый реальный пример.

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml

title Диаграмма компонентов: Система интернет-банкинга — API-приложение

' Акторы / внешние элементы на уровне контейнера
Container(spa, "Одностраничное приложение", "JavaScript & Angular", "Предоставляет пользовательский интерфейс интернет-банкинга через браузер")
Container(mobile, "Мобильное приложение", "iOS/Android", "Предоставляет ограниченные функции мобильного банкинга")
ContainerDb(database, "Банковская база данных", "PostgreSQL", "Хранит предпочтения пользователей, кэшированные данные, сессии")
System_Ext(mainframe, "Основная банковская система", "Мейнфрейм – основные счета и транзакции")

' Контейнер, в который мы увеличиваем
Container_Boundary(api, "API-приложение") {
    Component(signInCtrl, "Контроллер входа", "Spring MVC REST-контроллер", "Обрабатывает аутентификацию и создание сессии")
    Component(accountsCtrl, "Контроллер сводки счетов", "Spring MVC REST-контроллер", "Предоставляет балансы и сводки счетов")
    Component(resetPwdCtrl, "Контроллер сброса пароля", "Spring MVC REST-контроллер", "Управляет процессом сброса пароля")
    
    Component(security, "Компонент безопасности", "Spring Bean", "JWT-токены, хеширование паролей, проверка ролей")
    Component(accountService, "Компонент управления счетами", "Spring Bean / Сервис", "Организует запросы к счетам и бизнес-правила")
    Component(mainframeFacade, "Фасад банковской системы мейнфрейма", "Spring Bean", "Слой антикоррупции для устаревшего мейнфрейма")
    Component(emailNotifier, "Компонент уведомлений по электронной почте", "Spring Bean", "Отправляет подтверждающие и сбросные письма")
}

' Связи внутри границы
Rel(signInCtrl, security, "Использует")
Rel(accountsCtrl, accountService, "Использует")
Rel(resetPwdCtrl, security, "Использует")
Rel(resetPwdCtrl, emailNotifier, "Использует")
Rel(accountService, mainframeFacade, "Использует")
Rel(accountService, database, "Читает из и записывает в", "JDBC")
Rel(mainframeFacade, mainframe, "Использует", "XML/HTTPS")
Rel(emailNotifier, database, "Читает предпочтения пользователя", "JDBC")

' Входящие вызовы от фронтендов
Rel(spa, signInCtrl, "Использует", "JSON/HTTPS")
Rel(spa, accountsCtrl, "Использует", "JSON/HTTPS")
Rel(spa, resetPwdCtrl, "Использует", "JSON/HTTPS")
Rel(mobile, signInCtrl, "Использует", "JSON/HTTPS")
Rel(mobile, accountsCtrl, "Использует", "JSON/HTTPS")
Rel(mobile, resetPwdCtrl, "Использует", "JSON/HTTPS")

LAYOUT_WITH_LEGEND()
LAYOUT_LEFT_RIGHT()

@enduml

Это отображается:

  • Четкая граница вокруг контейнера API

  • Логическая группировка контроллеров, сервисов, фасадов

  • Точные ответственности

  • Ключевые взаимодействия и зависимости

  • Автоматическая легенда для удобочитаемости

Вставьте в рендерер PlantUML (онлайн или IDE) — настройте имена/технологии для вашей системы.

Используйте этот шаблон в качестве отправной точки. Цель всегда эффективная коммуникация в команде — а не красота диаграммы. Удачного моделирования!

Ресурс диаграммы компонентов C4

Эта статья также доступна на Deutsch, English, Español, فارسی, Français, English, Bahasa Indonesia, 日本語, Polski, Portuguese, Việt Nam, 简体中文 and 繁體中文