Как происходит архитектурная документация
Что проверяют
Документируете ли вы архитектуру так, чтобы ей реально пользовались, или это разовый документ, который устаревает через месяц. Следом обычно спрашивают, как вы фиксируете архитектурные решения и что держит документацию актуальной.
Как отвечать
Опишите процесс на своём проекте, опираясь на распространённые практики:
- C4 model: четыре уровня детализации. Context показывает систему среди пользователей и внешних систем, Container показывает приложения и хранилища (ASP.NET Core API, воркер, PostgreSQL, очередь), Component раскрывает один контейнер, Code вручную обычно не рисуют;
- ADR: короткая запись о решении, например почему выбрали RabbitMQ, а не прямые HTTP-вызовы. Структура: контекст, решение, последствия, статус. Старые записи не переписываются, их заменяют новыми;
- docs as code: Markdown и диаграммы кодом (PlantUML, Mermaid, Structurizr DSL) лежат в репозитории рядом с решением, изменения идут через pull request и ревью;
- контракты: OpenAPI-описание генерируется из кода. В шаблонах .NET 9 для этого пакет
Microsoft.AspNetCore.OpenApi, раньше по умолчанию стоял Swashbuckle. Для библиотек пишут XML-комментарии///, включаютGenerateDocumentationFileи собирают сайт через DocFX; - шаблон: arc42, если нужен полный документ с разделами про качество, риски и развёртывание.
Актуальность держится на процессе: изменение архитектуры без обновления схемы или ADR не проходит ревью. Правила слоёв можно закрепить тестами через NetArchTest или ArchUnitNET, тогда документ и код не расходятся.
Где спотыкаются
Рассказывают про большой документ в вики, написанный в начале проекта. Интервьюер сразу спросит, когда его обновляли последний раз.
Смешивают уровни на одной диаграмме: внешние системы, классы и таблицы вместе. Такую схему никто не может прочитать.
Документируют только «что», а не «почему». Через год никто не помнит, зачем выбран именно этот подход, и решение переделывают, наступая на те же грабли.