Clean Architecture на ASP.NET Core
Модель и масштаб — Основы БД, опорные темы, проектирование БД, пакетная работа. Карта — о разделе.
Круги зависимостей, сущности и use cases — в чистой архитектуре.
Здесь — как это выглядит в Visual Studio на базе открытого шаблона jasontaylordev/CleanArchitecture и документации cleanarchitecture.jasontaylor.dev.
Где применяют эталонный шаблон
Теория Uncle Bob отвечает на вопрос "куда направлены зависимости". Шаблон Jason Taylor показывает рабочую раскладку решения — отдельные проекты Domain, Application, Infrastructure, Web, оркестрация через MediatR, валидация FluentValidation, данные через EF Core, локальный запуск через .NET Aspire (AppHost).
Шаблон устанавливается как NuGet-шаблон:
dotnet new install Clean.Architecture.Solution.Template
dotnet new ca-sln -cf none -db sqlite -o MyApp
dotnet run --project .\src\AppHost
Параметры -cf (Angular / React / API only) и -db (SQLite, PostgreSQL, SQL Server) меняют оболочку, ядро слоёв остаётся тем же.
Четыре проекта и правило зависимостей
| Проект | Папка | Роль | Зависит от |
|---|---|---|---|
| Domain | src/Domain | Сущности, value objects, domain events, перечисления | — |
| Application | src/Application | Команды, запросы, обработчики, интерфейсы портов, валидаторы | Domain |
| Infrastructure | src/Infrastructure | DbContext, EF-конфигурации, внешние сервисы | Application |
| Web | src/Web | HTTP endpoints, middleware, OpenAPI, DI-регистрация | Application, Infrastructure |
Дополнительно — AppHost (Aspire) — оркестратор для разработки — поднимает Web, БД, дашборд наблюдаемости.
Правило: ссылки на проекты идут только внутрь. Domain не знает про ASP.NET и EF. Application объявляет IApplicationDbContext; Infrastructure его реализует.
Сопоставление с построением систем на классах: там та же логика может жить в папках одного репозитория; шаблон жёстко разносит сборки, чтобы компилятор не дал "случайно" импортировать Microsoft.EntityFrameworkCore в домен.
Vertical slice — одна папка — один сценарий
В Application код группируют по фиче, а не по типу файла:
Application/
└── TodoLists/
├── Commands/
│ ├── CreateTodoList/
│ │ ├── CreateTodoList.cs ← команда + handler
│ │ └── CreateTodoListCommandValidator.cs
│ └── DeleteTodoList/
└── Queries/
└── GetTodos/
├── GetTodosQuery.cs
└── GetTodosQueryHandler.cs
Открыть CreateTodoList — значит увидеть весь сценарий "создать список" без поиска по Services/ и Repositories/.
Domain
Сущность хранит инварианты; value object Colour инкапсулирует допустимые значения:
// Domain/Entities/TodoList.cs (упрощённо)
public class TodoList
{
public int Id { get; set; }
public string? Title { get; set; }
public Colour Colour { get; set; } = Colour.White;
public IList<TodoItem> Items { get; private set; } = new List<TodoItem>();
}
Application — команда и обработчик
Код ITЗагрузка примера кода…
Обработчик оркестрирует домен и порт сохранения. SQL и HTTP здесь отсутствуют.
Web — тонкий endpoint
public static async Task<Created<int>> CreateTodoList(ISender sender, CreateTodoListCommand command)
{
var id = await sender.Send(command);
return TypedResults.Created($"/{nameof(TodoLists)}/{id}", id);
}
ISender — фасад MediatR: endpoint не знает конкретный CreateTodoListCommandHandler. Подробнее про pipeline и валидацию — в MediatR и cross-cutting в Application.
Где живут интерфейсы
| Абстракция | Слой | Пример |
|---|---|---|
| Репозиторий / контекст БД | Application | IApplicationDbContext |
| Реализация EF | Infrastructure | ApplicationDbContext |
| HTTP, OpenAPI | Web | TodoLists endpoints |
| Регистрация DI | Infrastructure + Web | AddInfrastructure(), AddWebServices() |
Интерфейс порта в Application — каноничный вариант для Clean Architecture: прикладной слой задаёт контракт, инфраструктура подстраивается. В Построение систем на основе классов и объектов встречаются примеры с интерфейсом в Infrastructure — это допустимо для маленьких проектов, но в enterprise-шаблоне предпочтительнее порт в Application.
Cross-cutting — pipeline behaviours
HTTP-слой (middleware, endpoint filters) и бизнес-цепочка (policy pipeline) разведены в ASP.NET — где жить логике. Ниже — реализация policy pipeline через MediatR в Application.
Валидация, логирование и замер времени выполнения вешаются на MediatR pipeline, а не в каждый handler:
Код ITЗагрузка примера кода…
Команда проходит цепочку до Handle: сначала FluentValidation, затем бизнес-логика. Контроллер остаётся без if (!ModelState.IsValid) для доменных правил.
Aspire и точка входа
Локально приложение стартует из src/AppHost: Aspire поднимает Web API, контейнер с БД (при PostgreSQL/SQL Server) и открывает dashboard с URL и логами. Это связывает чистую архитектуру с узлом приложений .NET Aspire: топология "сервис + БД" описана в коде, а не в README.
В проде Web деплоится отдельно; AppHost — инструмент разработки и интеграционных сценариев.
Тестирование
| Уровень | Что проверяем | Зависимости |
|---|---|---|
| Unit | Handler + домен | Mock IApplicationDbContext или in-memory |
| Integration | HTTP → pipeline → БД | WebApplicationFactory, Testcontainers / Respawn |
Шаблон использует NUnit, Shouldly, Moq; для БД — сброс состояния между тестами (Respawn). См. также интеграционные тесты ASP.NET Core.
Юнит-тест handler'а CreateTodoList без Kestrel и Docker — прямой вызов Handle с подменённым контекстом; тот же приём, что в сквозном примере todo в 2132.
Когда шаблон уместен
| Ситуация | Рекомендация |
|---|---|
| Корпоративный API, 2+ года жизни, несколько разработчиков | Четыре проекта + vertical slices оправданы |
| CRUD на 3–5 сущностей, один разработчик, срок до 6 месяцев | Достаточно одного проекта со слоями в папках или Minimal API без четырёх сборок |
| Нужны отдельные read/write модели и масштаб чтения | Добавить CQRS осознанно, не "по умолчанию" |
| Микросервис с одной ответственностью | Урезать: Domain + Application + один host, без SPA-проектов |
MediatR, AutoMapper и четыре сборки — инструменты, не требование чистой архитектуры. Минимальный каркас из Чистая архитектура выражает те же правила зависимостей.
Антипаттерны
| Симптом | Почему ломает CA | Что делать |
|---|---|---|
[Table], [JsonProperty] на entity | Домен привязан к EF/JSON | Конфигурация в IEntityTypeConfiguration, DTO в Web |
DbContext в handler через new | Нет DI и подмены в тестах | Инжектировать IApplicationDbContext |
| SQL в endpoint | Presentation знает персистентность | sender.Send(command) |
"God" ApplicationService на 800 строк | Смешаны сценарии | Разбить на команды/запросы по папкам |
Shared со всем подряд | Скрытые зависимости наружу | Только примитивы ядра; фичи — в slice |
| Валидация только в UI | Домен обходят через API | FluentValidation + инварианты в entity |
| AutoMapper в Domain | Зависимость от инфраструктуры маппинга | Профили в Application или Web |
ADR и эволюция
В репозитории шаблона решения фиксируют как Architecture Decision Records (docs/decisions/) — выбор БД, аутентификация, структура тестов. Тот же приём описан в документации как инструмент проектирования и оценке альтернатив.
При форке шаблона под продукт имеет смысл оставить формат ADR — через год команда вспомнит, почему выбрали SQLite, а не "потому что так в примере".
Карта материалов энциклопедии
| Тема | Статья |
|---|---|
| Теория кругов и порты | Чистая архитектура — Чистая архитектура |
| Папки, типы классов, DI | Построение систем на основе классов и объектов — Построение на классах |
| CQRS | CQRS |
| MediatR, pipeline | MediatR и pipeline в слое Application — MediatR |
| ASP.NET Web API | Первая программа на ASP.NET Core |
| EF Core | Entity Framework Core — первая программа |
| Aspire | Экосистема .NET-приложений — платформа .NET |
| GRASP на границе HTTP | GRASP и паттерн ADR для веб-бэкенда |
Итог
Шаблон jasontaylordev/CleanArchitecture — практический эталон для .NET — зависимости внутрь, сценарии в vertical slices, порты в Application, адаптеры в Infrastructure и Web. Его стоит разбирать после Чистая архитектура, проходя один сценарий (например CreateTodoList) от endpoint до таблицы в БД. Для собственного продукта шаблон можно упростить, сохранив правило зависимостей — оно важнее количества проектов в solution.
Внешние источники: GitHub · Документация · Architecture overview