Clean Architecture

Что это

Clean Architecture (Robert C. Martin, 2012) — набор правил организации кода в концентрические слои с жёстким Dependency Rule: исходный код во внутреннем круге никогда не упоминает имена из внешнего. Бизнес-логика (Entities + Use Cases) не знает ничего про Postgres, Express, React — они «детали», которые подключаются снаружи через интерфейсы.

Четыре слоя:

• Entities — доменные объекты с поведением (Order, Money, Customer). Самые стабильные правила.
• Use Cases — application-specific операции (CreateOrder, PayOrder). Оркестрируют entities + порты.
• Interface Adapters — Controllers / Presenters / Repositories. Переводят форматы.
• Frameworks & Drivers — Express, Postgres, Stripe SDK. Конкретные технологии.

Mental model

Зависимости в коде идут только внутрь. Если внутреннему слою нужен внешний — внутренний объявляет интерфейс (port), а внешний его реализует (adapter). Стрелка в коде идёт от outer к inner; стрелка вызова в runtime — от inner к outer. Это Dependency Inversion.

Практический критерий: «можно ли поднять use case в unit-тесте без Postgres, без HTTP, без Stripe?» Если да — Dependency Rule соблюдён. Если нет — слои протекают.

Что на диаграмме

Вложенные группы рисуют четыре кольца — снаружи внутрь: Frameworks & Drivers (Express, PostgreSQL, Stripe SDK) обёртывают Interface Adapters (HTTP Controller, PostgresOrderRepository, StripePaymentGateway, OrderPresenter), внутри них — Application Use Cases (CreateOrder UC, PayOrder UC + порты OrderRepository, PaymentGateway), и в самом центре — Entities (Order, Money VO, Customer).

Edges повторяют структуру кода, а не направление вызова в runtime:

• controller-http -> usecase-create — controller импортирует use case (внешний знает про внутренний — OK).
• usecase-create -> port-repo — use case вызывает порт, объявленный рядом с ним (внутри своего кольца).
• repo-impl -> port-repo — implements. Стрелка идёт от outer adapter к inner port — это и есть Dependency Inversion на диаграмме.
• repo-impl -> postgres — единственное место в системе, где живёт SQL.

В runtime пакет данных по edge repo-impl -> port-repo бежит в обратную сторону — это нормально (FlowBuilder автоматически анимирует reverse). Главное, что стрелка зависимости (кто кого знает в исходном коде) указывает строго внутрь.

Сценарии

Happy path POST /orders: запрос приходит из Express в HTTP Controller, тот зовёт CreateOrderUseCase через input boundary, use case применяет доменные правила на Order/Money, сохраняет через OrderRepository port — runtime-провод ведёт в PostgresOrderRepository, тот в Postgres. Результат поднимается обратно: use case вызывает Presenter, Presenter формирует ViewModel, controller возвращает 200 OK. Каждое кольцо знает только о следующем внутрь.

Unit-test use case без I/O: тест инжектит InMemoryOrderRepository вместо PostgresOrderRepository. Use case вызывает тот же OrderRepository port — меняется проводка, не код. Доменная логика на Order/Money работает на чистом языке (без фреймворков), in-memory adapter отвечает мгновенно, тест укладывается в ~5ms и не требует cleanup БД. Это и есть главный дивиденд Clean Architecture.

Замена PostgresOrderRepository на MongoOrderRepository: интерфейс OrderRepository port не меняется, поэтому use case, entities и controller не трогаем вообще. Меняется только outermost ring — провод от port к новой реализации, новый adapter, новый driver. Старая Postgres-ветка отмирает. Размер изменения локален «по конструкции», а не «по аккуратности».

Антипаттерн: entity импортирует Postgres driver напрямую (например, чтобы дёрнуть raw SQL ради «производительности»). Теперь Order нельзя протестировать без поднятого Postgres, и фреймворк диктует дизайн entity. Фикс — вернуть SQL в PostgresOrderRepository, а entity оставить чистой. Dependency Rule снова соблюдается, стрелки опять смотрят только внутрь.

Trade-offs (ADR: Clean vs Hexagonal vs Onion)

Status: Accepted. Все три архитектуры — изоморфные ответы на одну проблему («не дать фреймворку диктовать дизайн»). Выбор реально влияет на ~5%, не на 50%.

Decision:

• Маленький долгоживущий сервис, есть DDD → Hexagonal (меньше дисциплины, легче объяснить).
• Крупное .NET / JVM приложение, много controllers → Onion (естественный mapping на DI-контейнер).
• Сложный enterprise-домен с несколькими delivery channels (REST + gRPC + CLI + queue) и нужен явный input/output boundary → Clean (плата — Input/Output Boundary + Presenter поверх обычного UC).

Consequences: все три можно микшировать (Hexagonal core + Clean-style use case ports снаружи). Главное общее правило — Dependency Rule. Команда, не понимающая Dependency Inversion, одинаково сломает любой из трёх стилей.

За:

• Long-term maintainability; крупные рефакторинги локальны.
• Use cases тестируются без I/O — секунды вместо минут на CI.
• Команды свободно меняют adapters параллельно (frontend/db/payments).
• Переживает framework upgrades и смену поставщиков.

Против:

• Много интерфейсов и mapping-кода — over-engineering для CRUD.
• Скорость на старте ниже (вместо 1 файла — 4 + интерфейс).
• Дисциплина: новички ломают слои без code review.
• DTO → Entity → ViewModel — boilerplate, особенно если поля совпадают 1
  .

Реальные системы

• Microsoft eShopOnContainers — публичная reference-архитектура на .NET, ровный Clean со всеми кольцами.
• NestJS — фреймворк, в котором layers легко выстроить (Controllers / Services / Repositories — естественный mapping).
• GitHub Mobile (по докладам) — clean layers поверх SwiftUI / Jetpack Compose.
• Robert Martin's FitNesse — цитируется автором как референс.
• Apollo (Capital One) — публичный кейс с Clean Architecture в финтехе.
• Spring-приложения «Get Your Hands Dirty on Clean Architecture» (Tom Hombergs) — рабочий пример с Hexagonal/Clean гибридом.

Anti-patterns

• Anemic domain. Entities выродились в getter/setter DTO, вся логика в «service»-классах. Формально слои есть, по сути — Transaction Script.
• Leaky abstraction. OrderRepository.findAll() возвращает QueryBuilder или ResultSet — use case теперь знает про БД.
• God use case. Один интерактор на 500 строк делает 5 операций. Чините через decomposition + domain events.
• Bypassing layers. Controller дёргает Repository напрямую, обходя use case. «Это же просто GET» — через полгода это уже половина системы.
• Mapping fatigue. DTO ↔ Entity ↔ ViewModel mapping 1
  для каждого поля без выгоды. Лекарство — копировать только там, где формат реально расходится.
• Framework leakage. @Entity, @Column JPA-аннотации прямо в core entities. Теперь Entity знает про Hibernate.
• Use case в use case. Один UC зовёт другой UC напрямую → coupling и циклы. Лучше — domain events или общий доменный сервис.
• Тесты против адаптеров вместо use cases. Mock всего подряд, ничего не проверяет реальное поведение.

Когда НЕ использовать

• Простой CRUD / MVP / prototype. Если приложение в основном переливает JSON в SQL и обратно, четыре кольца + Presenter дают только overhead.
• Маленькая команда, короткий горизонт. До 1 года жизни и 2–3 разработчиков выигрыш от изоляции не окупает дисциплины.
• Тривиальная бизнес-логика. Admin panel, marketing site, internal tooling — здесь полезнее быть близко к фреймворку (Rails-way / Django-way).
• «Clean ради Clean». Если команда не понимает Dependency Inversion, формальное соблюдение слоёв превратится в карго-культ с DTO-фабриками.

Не путайте Clean Architecture с запретом на use case orchestration: иногда правильно вызвать другой use case или общий доменный сервис; запрещено только тащить фреймворк внутрь.

Дальше читать

• [CONCEPT]hexagonal-ports-adapters — родительская идея (2005), минимальная версия того же подхода.
• [CONCEPT]onion-architecture — близкий родственник, популярный в .NET-мире.
• [CONCEPT]ddd-tactical — entities/aggregates/value objects как наполнение внутреннего кольца.
• [CONCEPT]modular-monolith — Clean часто живёт внутри одного модуля модульного монолита.

Книги и статьи:

• Robert C. Martin — The Clean Architecture (blog, 2012) — оригинальный пост.
• Robert C. Martin — Clean Architecture: A Craftsman's Guide (2017).
• Tom Hombergs — Get Your Hands Dirty on Clean Architecture (Spring-пример).
• Mark Seemann — Dependency Injection Principles, Practices, and Patterns.
• Vladimir Khorikov — критические статьи на enterprisecraftsmanship.com (где Clean over-engineering, где нет).