de_DEen_USes_ESfa_IRfr_FRhi_INid_IDjapl_PLpt_PTru_RUvizh_CNzh_TW

Масштабирование до самого мелкого уровня: понимание диаграмм кода C4 – что это такое, когда они приносят пользу и практические примеры PlantUML

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

Диаграмма кода — этоУровень 4— самый глубокий и детализированный уровень в модели C4 Саймона Брауна.

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

Он показывает:

  • Классы, интерфейсы, перечисления, записи, или другие конструкции на уровне кода, реализующие конкретныйкомпонент (с уровня 3).

  • Связи между этими классами (наследование, композиция, зависимость, реализация интерфейсов и т.д.).

  • Ключевыеэлементы проектирования такие как шаблоны, применяемые внутри компонента (например, репозитории, сервисы, DTO, доменные сущности, фабрики).

На практике этот уровень почти всегда являетсядиаграммой классов UML (или упрощённой версией), ориентированной на один (или очень мало) компонентов.

Важное уточнение:

  • Уровень 4 — этоне не о всей кодовой базе.

  • Онненеобходимо показывать каждый класс.

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

  • Официальная рекомендация C4:желательно автоматически генерируемаяиз исходного кода (с помощью инструментов, таких как Doxygen, Javadoc + плагины UML, yWorks, Structurizr, CodeSee и др.), а не вручную нарисованная.

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

Создавайте диаграммы уровня 4 сдержанно — только в этих случаях:

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

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

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

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

  • Вы уже вложили средства вавтоматическая генерацияинструменты — поэтому поддержка уровня 4 почти не стоит ничего.

  • Команда согласилась, что«живая документация»на уровне классов имеет значение для этой конкретной подсистемы.

НЕ создавайте диаграммы уровня 4, когда:

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

  • У вас уже естьхорошие юнит-тесты/тесты интеграции, четкие интерфейсы, иобъяснительные комментарии.

  • Большинство команды легко ориентируются в коде.

  • Стоимость поддержки превышает выгоду (рукописные диаграммы классов быстро устаревают).

Саймон Браун и большинство практиков подчеркивают:Большинство команд никогда не нуждаются в уровне 4. Уровни 1 + 2покрывают 80–90% потребностей в коммуникации;Уровень 3обращается со значительной частью оставшегося. Уровень 4 — исключение, а не правило.

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

  • Мост между архитектурой ↔ реализацией— Показывает, как высокий уровень компонентов на самом деле реализован в коде.

  • Уточнить сложную внутреннюю архитектуру— Выявляет использование паттернов (Стратегия, Фабрика, Декоратор, Репозиторий), нарушения слоистости, тесную связь или изящное моделирование домена.

  • Поддержка аудитов и соответствия — Показывает, что архитектурные решения реализуются на уровне кода.

  • Содействие обсуждениям по рефакторингу и миграции — Структуры классов до и после делают предложения осязаемыми.

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

  • Автоматически генерируемые версии становятся «живой документацией» — Если инструменты на месте, они остаются точными почти без усилий.

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

  1. Выберите ОДИН компонент — Обычно из диаграммы уровня 3, где внутренняя сложность оправдывает увеличение.

  2. Определите: ручная или автоматическая генерация?

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

    • Автоматическая → предпочтительна (PlantUML по-прежнему можно использовать для стилизации/настройки вывода).

  3. Сосредоточьтесь на основном — Покажите:

    • Ключевые классы/интерфейсы

    • Важные отношения (→ зависимость, — композиция, <| реализация, ^ наследование)

    • Агрегаты, сущности, объекты значений (по стилю DDD)

    • Критические паттерны или антипаттерны, которые вы хотите выделить

  4. Держите его маленьким — Максимум 8–15 классов. Если больше → разбейте на узконаправленные диаграммы (например, «фрагмент аутентификации», «сущности обработки заказов»).

  5. Лучшие практики

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

    • Используйте синтаксис PlantUML classDiagram — чистый и версионируемый.

    • Добавьте примечаниядля неочевидных решений (например, «Использует анемичную модель домена — запланированная рефакторизация»).

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

    • Храните в репозитории → рассматривайте как код (сдавайте файлы .puml рядом с компонентом).

    • Используйте умеренно — один на сложный компонент, а не на каждый микросервис.

    • Объединяйте сдинамическими видами (последовательность/сотрудничество), если поток во время выполнения важнее статической структуры.

Пример PlantUML — Компонент аутентификации (расширение стиля Big Bank plc)

Вот реальный пример уровня 4, фокусирующийся наКомпонент безопасности / аутентификации из ранее представленных диаграмм API-приложения.

@startuml
title C4 Уровень 4 – Диаграмма кода: Аутентификация внутри API-приложения

skinparam monochrome true
skinparam shadowing false
skinparam class {
  BackgroundColor White
  BorderColor Black
  ArrowColor Black
}

абстрактный класс AuthenticationProvider {
  + authenticate(credentials): Authentication
}

class JwtAuthenticationProvider {
  - tokenProvider: JwtTokenProvider
  - userDetailsService: UserDetailsService
  + authenticate(credentials): Authentication
}

class JwtTokenProvider {
  - secretKey: String
  - validityInMilliseconds: long
  + generateToken(userDetails): String
  + validateToken(token): boolean
  + getUsernameFromToken(token): String
}

интерфейс UserDetailsService {
  + loadUserByUsername(username): UserDetails
}

class DatabaseUserDetailsService {
  - userRepository: UserRepository
  + loadUserByUsername(username): UserDetails
}

class UserRepository {
  + findByUsername(username): Optional<User>
}

class User {
  - username: String
  - passwordHash: String
  - roles: Set<Role>
}

class JwtAuthenticationToken << (T,orchid) Authentication >> {
  - principal: UserDetails
  - credentials: Object
  - authorities: Collection<GrantedAuthority>
}

' Связи
JwtAuthenticationProvider -up-> JwtTokenProvider : использует
JwtAuthenticationProvider -up-> UserDetailsService : использует
DatabaseUserDetailsService .up.|> UserDetailsService
DatabaseUserDetailsService --> UserRepository : использует
UserRepository --> User : возвращает

JwtAuthenticationToken .up.|> Authentication

note right of JwtAuthenticationProvider
  Основной поток аутентификации для сессий на основе JWT без состояния
end note

note bottom of JwtTokenProvider
  Подписывает и проверяет JWT с использованием HS512
end note

@enduml

Эта небольшая диаграмма:

  • Фокусируется исключительно на внутренних аспектах аутентификации

  • Показывает ключевые классы, интерфейсы и зависимости

  • Выделяет шаблоны (провайдер, репозиторий)

  • Использует примечания для контекста

Вставьте в любой рендерер PlantUML — настройте под вашу предметную область (например, замените JWT на OAuth2, добавьте классы MFA и т.д.).

Напоминание по итогам: Уровень 4 мощный, норедкий. Используйте его осознанно, отдавайте предпочтение автоматической генерации, и никогда не позволяйте ему превращаться в пустую работу. Большая часть ценности C4 исходит из уровней 1–3. Удачного (выборочного) моделирования!

Ресурс

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