ADR и документирование архитектуры (C4)
↑ 8.2 Архитектурные стили и DDD · ← Предыдущая
Зачем это на собесе
Как вы фиксируете и объясняете архитектурные решения — важно для senior и техлида.
Объяснение
ADR (Architecture Decision Record) — короткий документ об одном решении: контекст, варианты, решение, последствия. Хранится в репозитории рядом с кодом и не редактируется после принятия (замещается новым ADR).
# ADR-007: Брокер сообщений — Kafka вместо RabbitMQ
Статус: принято (2025-06-12) · Заменяет: — · Участники: команда платформы
## Контекст
Нужен replay событий и поток 20k msg/s; несколько независимых потребителей.
## Варианты
1. RabbitMQ — проще эксплуатация, нет replay.
2. Kafka — replay, масштабирование партициями, сложнее эксплуатация.
## Решение
Kafka (KRaft), 3 брокера, retention 7 дней.
## Последствия
+ replay, масштабирование; − эксплуатационная сложность, нужен Schema Registry.
Пересмотреть при падении нагрузки ниже 2k msg/s.Модель C4 — иерархия диаграмм архитектуры:
| Уровень | Что показывает | Аудитория |
|---|---|---|
| 1. System Context | система и её окружение (пользователи, внешние системы) | все |
| 2. Container | приложения и хранилища внутри системы (API, БД, брокер) | разработчики, ops |
| 3. Component | компоненты внутри контейнера | разработчики |
| 4. Code | классы (обычно не рисуют) |
Инструменты: Structurizr, PlantUML, Mermaid, draw.io; «диаграммы как код» лежат в репозитории.
Прочее: arc42-шаблон, README сервиса, runbook, OpenAPI/AsyncAPI, карта контекстов, диаграммы последовательностей для ключевых потоков.
Нюансы и подводные камни
- Документация устаревает: держите рядом с кодом, включайте в ревью, генерируйте где возможно.
- ADR фиксирует «почему», а не «как»: код и так показывает «как».
- Не документируйте всё: только значимые решения и диаграммы, которые читают.
- Диаграмма без легенды и уровня детализации вводит в заблуждение.
Практика
- Напишите три ADR для решений вашего проекта (брокер, хранилище, аутентификация).
- Нарисуйте C4 уровня Context и Container для своей системы.
- Внедрите шаблон ADR и добавьте его в процесс ревью.
Вопросы с ответами
Что такое ADR и зачем он нужен?
Краткая запись архитектурного решения с контекстом и последствиями, чтобы команда понимала причины и могла пересмотреть решение.
Что такое C4?
Иерархия диаграмм (контекст, контейнеры, компоненты, код) для описания архитектуры на разных уровнях детализации.