Files
mtusi2026lab2/openspec/notes/architecture-patterns-python.md
T
Artyom 6d8b76b447
Application / Линт, типы и собственные тесты (pull_request) Canceled after 0s
Application / Стенд Compose, smoke, рестарт и отказы зависимостей (pull_request) Canceled after 0s
Skeleton contracts / contracts (pull_request) Canceled after 0s
lab2
2026-10-30 12:32:42 +03:00

350 lines
54 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Паттерны разработки на Python — рабочая заметка
Источник: Гарри Персиваль, Боб Грегори. «Паттерны разработки на Python: TDD, DDD и событийно-ориентированная архитектура» (Architecture Patterns with Python), Питер, 2022, 336 с.
Файл: `~/Library/Mobile Documents/com~apple~CloudDocs/Книги/Паттерны разработки на Python.pdf`. **Номер страницы PDF = номер страницы книги (смещение 0)** — ссылки ниже кликаются напрямую.
Ремарка о стеке (дальше не повторяется): все примеры книги показаны на конкретном веб-фреймворке, ORM и pub/sub-хранилище. Ниже они обобщены до ролей — «точка входа», «ORM», «брокер сообщений». Стек выбирается отдельно, ни один паттерн от него не зависит.
Формула книги (Рич Хикки, с. 65): при вводе каждого паттерна спрашивать «что мы за это получаем и чего это стоит». Ни один паттерн в книге не подаётся как обязательный.
---
## 1. Модель предметной области (Domain Model)
Слой, где живёт вся бизнес-логика, выраженный языком бизнеса и свободный от инфраструктуры.
**Задача.** Бизнес-логика расползается по всем слоям (контроллеры, «менеджеры», хранимки), её невозможно найти, понять и изменить. Разработчики начинают со схемы БД, а объектная модель появляется с запозданием — «на первом месте должно быть поведение, которое управляет требованиями к хранилищу» (с. 29).
Строительные блоки: **сущность** (entity) — идентичность сохраняется при смене атрибутов; **объект-значение** (value object) — немутируемый, полностью определяется атрибутами, взаимозаменяем; **служба предметной области** (domain service) — глагол, который не принадлежит ни одной сущности, обычная функция. Исключения тоже часть языка предметной области.
| Применять | Не применять |
|---|---|
| Сложная бизнес-логика, много правил и крайних случаев | Приложение — простая CRUD-оболочка над БД («модель предметной области или репозиторий вам не нужны», с. 71) |
| Правила меняются чаще, чем инфраструктура | Логика тождественна схеме данных — тогда чтение и запись связаны, и разделение не окупается (с. 236) |
| Нужны юнит-тесты как живая документация правил | Работает график с. 72: для простых доменов ORM/Active Record дешевле, кривые пересекаются только при росте сложности |
**Связи.** Требует «Репозиторий», чтобы остаться не осведомлённой о хранении. Требует «Агрегат», чтобы задать границу согласованности. Заменяет анемичную модель + толстые сервисы. Позже отдаёт побочные эффекты «Событиям предметной области».
Отдельная таблица «плюсы/минусы» для главы 1 в книге отсутствует — компромисс сформулирован в главе 2 (табл. 2.1, рис. 2.6) и в «Итогах части I».
---
## 2. Репозиторий (Repository)
Абстракция над постоянным хранением: коллекция объектов, как будто целиком лежащая в памяти.
**Задача.** Модель предметной области не должна знать о БД. Минимальный интерфейс — `add()` и `get()`. Список/удаление/обновление в идеале не нужны: удаление — мягкое (метод домена), обновление — забота UoW.
| Применять (плюсы) | Не применять (минусы) |
|---|---|
| Простой интерфейс между хранилищем и доменом | ORM и так частично устраняет связанность: сменить одну СУБД на другую будет довольно легко, хотя поменять внешние ключи может оказаться непросто |
| Тривиально подделывается для юнит-тестов (fake = обёртка над `set`) | Ручное отображение объектов на таблицы — дополнительная работа и код |
| Модель пишется до планирования хранения — фокус на бизнес-задаче, миграции откладываются | Ещё один слой косвенности: рост стоимости сопровождения и «фактор WTF» для тех, кто паттерна не видел |
| Полный контроль над схемой БД, она остаётся простой | Для CRUD-обёртки — не нужен вовсе |
**Связи.** Реализует принцип инверсии зависимостей на уровне данных: ORM импортирует модель, а не наоборот. `AbstractRepository` — **порт**, конкретная и поддельная реализации — **адаптеры**. Один агрегат = один репозиторий, репозиторий возвращает **только** агрегаты (гл. 7). Начиная с гл. 6 доступ к репозиториям выдаёт UoW, а не точка входа. Начиная с гл. 8 репозиторий ведёт `.seen` — множество загруженных агрегатов, откуда UoW собирает события.
Эвристика (с. 70): «если делать подделки трудно, то абстракция, вероятно, слишком сложная».
---
## 3. Сервисный слой / варианты использования (Service Layer, Use Cases)
Оркестровка: тонкий API приложения, где каждый вариант использования — одна функция.
**Задача.** Логика оркестровки (достать → проверить → вызвать домен → сохранить) заползает в контроллеры. Типовая функция слоя: извлечь объекты из репозитория, проверить предусловия, вызвать службу предметной области, сохранить изменения.
Не путать со **службой предметной области**: доменная служба выражает бизнес-концепцию, сервисный слой — способ использования приложения; сервисный слой часто вызывает доменную службу.
| Применять (плюсы) | Не применять (минусы) |
|---|---|
| Единое место для всех сценариев использования | Приложение исключительно веб — контроллеры и так единственная точка сбора сценариев |
| Домен спрятан за API — его можно свободно перерабатывать | Ещё один слой абстракции |
| «Всё про HTTP» отделено от «всё про предметную область» | Слишком много логики в сервисном слое → антипаттерн «анемичная модель» |
| Вместе с репозиторием даёт быстрые тесты выше уровня домена | Часто хватает «толстых моделей, тонких контроллеров» — вытолкнуть логику из контроллера вниз, в модель, без промежуточного слоя |
**Связи.** Требует «Репозиторий» (зависит от абстракции, не от реализации). До гл. 6 связан с сессией БД — развязывается через UoW. Аргументы выражаются **примитивами**, не доменными объектами (гл. 5) — иначе тесты слоя остаются связанными с доменом. В гл. 9 функции сервисного слоя становятся **обработчиками сообщений** (`services.py` → `handlers.py`), и разница между «службой» и «обработчиком» исчезает.
Совет из книги: вводить слой после того, как заметили оркестровку в контроллерах, а не заранее.
---
## 4. Абстракции и выбор швов (гл. 3)
Отделять «что сделать» от «как сделать»: функциональное ядро + императивная оболочка.
**Задача.** Высокоуровневый код сцеплен с вводом-выводом, тесты медленные и громоздкие, добавить режим `--dry-run` или другой бэкенд невозможно.
Приём: представить состояние внешнего мира простой структурой данных, а результат работы — списком команд-намерений; чистое ядро принимает и возвращает структуры данных, оболочка выполняет ввод-вывод.
Таблицы компромиссов у главы нет — вместо неё **четыре вопроса-эвристики** (с. 89):
1. Какой знакомой структурой данных представить состояние запутанной системы, и какая одна функция может её вернуть?
2. Где провести грань, вырезать **шов**, чтобы вставить абстракцию?
3. Как разделить код на компоненты с разными обязанностями? Какие неявные концепции сделать явными?
4. Каковы зависимости и какова ключевая бизнес-логика?
**Связи.** Это обоснование для всех остальных абстракций книги: репозиторий, UoW, шина сообщений — частные случаи. «Проектирование с учётом тестопригодности означает проектирование с учётом расширяемости» (с. 87).
---
## 5. TDD по слоям: подделки против имитаций, повышенная и пониженная передачи
Тесты — в первую очередь практика проектирования, во вторую — практика тестирования.
**Определения (врезка в гл. 3, с. 87).** **Имитация** (mock) проверяет, *как* нечто использовалось (`assert_called_once_with`), лондонская школа. **Подделка** (fake) — рабочая реализация только для тестов (репозиторий в памяти), утверждения делаются о *конечном состоянии*, классическая школа. Авторы твёрдо на стороне классиков: избыток имитаций скрывает предмет теста.
**Спектр тестов (рис. 5.1).** Тесты домена: эффективная обратная связь по дизайну, точечный охват, высокий барьер для изменений, хрупкие. Тесты API: широкий охват, низкий барьер, но ничего не говорят о дизайне объектов. Тесты сервисного слоя — компромисс посередине.
**Передачи.** *Пониженная* — тесты прямо на модель: новый проект, особенно сложная задача, нужно нащупать дизайн и получить документацию. *Повышенная* — тесты на сервисный слой: обычная фича или багфикс, меньше связанности, шире охват, свобода рефакторить модель.
Таблицы у главы нет; вместо неё врезка **«Эмпирические правила для разных типов тестов»** (с. 119):
| Уровень | Сколько | Зачем |
|---|---|---|
| Сквозной (E2E) | ~1 на функциональное свойство | Показать, что все движущиеся части склеены |
| Сервисный слой | Основная масса | Все крайние случаи бизнес-логики, ввод-вывод подделан |
| Модель предметной области | Малое ядро | Самая эффективная обратная связь по дизайну; удалять без сожаления, когда покрыто выше |
| Несчастливые пути | 1 сквозной на все + много юнит-тестов | Обработка ошибок трактуется как отдельное функциональное свойство |
**Связи.** Работает только при наличии сервисного слоя и подделок репозитория/UoW. «Каждая строка кода в тесте удерживает систему в определённой форме, словно капля клея» (с. 111). Признак недоработанного сервисного слоя: в его тестах приходится напрямую собирать доменные объекты.
---
## 6. UoW — единица работы (Unit of Work)
Абстракция идеи атомарной операции; контекстный менеджер, внутри которого либо всё, либо ничего.
**Задача.** Сервисный слой напрямую держит сессию БД; точка входа общается сразу с тремя слоями. UoW оставляет точке входа две задачи: создать UoW и вызвать службу.
Фиксация **явная**, откат — по умолчанию: единственный путь к изменению состояния — полный успех и явный commit; любой ранний выход оставляет систему в безопасном состоянии.
| Применять (плюсы) | Не применять (минусы) |
|---|---|
| Хорошая абстракция атомарности; блоки кода видны глазами | ORM/фреймворк, вероятно, уже даёт такую абстракцию (сессия + контекстный менеджер) — можно просто передавать сессию |
| Явный контроль границ транзакции, отказ безопасен по умолчанию | Откаты, многопоточность, вложенные транзакции требуют отдельного продумывания — «выглядит легко» обманчиво |
| Единая точка доступа ко всем репозиториям | |
| Позже — место сбора и публикации событий | |
**Связи.** Требует «Репозиторий» (предоставляет его наружу) и завершает связку с «Сервисным слоем»: один вариант использования = один UoW, успешный или неуспешный целиком. Требуется «Агрегатом» для соблюдения инвариантов на уровне БД. В гл. 8 UoW становится издателем событий, в гл. 10 — источником очереди сообщений (`collect_new_events`).
---
## 7. Агрегат и границы согласованности (Aggregate, Consistency Boundary)
Кластер связанных объектов, изменяемый как единое целое; единственная публичная точка входа в своё поддерево модели.
**Задача.** **Ограничение** — правило, лимитирующее возможные состояния; **инвариант** — условие, всегда истинное. Соблюдать инварианты при параллельной записи, не блокируя всю таблицу. Агрегат очерчивает минимальный кусок модели, который должен быть согласован атомарно; всё, что вне его, согласуется в конечном счёте.
Правило выбора: граница вокруг наименьшего числа объектов, которые обязаны быть согласованы; ей нужно хорошее имя из языка предметной области. Правильного ответа нет — выбор пересматривается, если упирается в производительность.
**Конкурентность.** Оптимистическая блокировка через номер версии на агрегате (конфликт ловится, операция повторяется) против пессимистической — блокировка строк/`SELECT FOR UPDATE` (конфликта не будет, но возможны тупики и просадка). Номер версии книга размещает **в домене**: сервисный слой раздваивает ответственность между слоями, а UoW/репозиторий могут сделать это, лишь допустив, что изменились все агрегаты, — и наращивают версию там, где это не нужно.
| Применять (плюсы) | Не применять (минусы) |
|---|---|
| Явно делит классы модели на «публичные» и «внутренние» | Третий тип доменного объекта поверх сущности и объекта-значения — рост порога входа |
| Моделирование вокруг явных границ снимает проблемы производительности ORM | Правило «менять только один агрегат за транзакцию» — большой сдвиг в мышлении |
| Единственная ответственная точка за инварианты — проще рассуждать о системе | Работать с итоговой согласованностью между агрегатами сложно |
**Связи.** **Один агрегат = один репозиторий**, репозиторий возвращает только агрегаты. Требует UoW для атомарности. Порождает потребность в «Событиях предметной области»: если процесс пересекает границу агрегатов, его нельзя выполнить одной транзакцией. Диагностика из эпилога (с. 285): нужда атомарно обновить два агрегата означает, что граница выбрана неверно.
Соседняя концепция — **ограниченный контекст** (bounded context): одно и то же слово в разных контекстах значит разное; модель включает только данные, нужные для её расчётов. Выбор агрегатов = выбор контекста, в котором они живут.
---
## 8. События предметной области (Domain Events)
Немутируемые классы данных — факты о произошедшем, зарегистрированные моделью.
**Задача.** Побочное требование («когда товара нет — уведомить закупки») некуда положить: в контроллере — не его дело, в модели — зависимость от инфраструктуры, в сервисном слое — нарушение принципа единственной обязанности. Признак нарушения: работу функции нельзя описать без «затем» и «и».
Модель **регистрирует** факт на языке предметной области; реагировать на него — обязанность кого-то другого.
**Три схемы публикации** (номера вариантов в тексте главы и в её резюме не совпадают, поэтому лучше различать их по издателю):
- публикует **сервисный слой**, забирая события из модели — проще всего, работает;
- **модель порождает, сервисный слой публикует** — логика «когда инициировать» живёт рядом с правилом;
- публикует **UoW**, обходя `.seen` после фиксации — выбор авторов: сервисный слой полностью чист, но механизм «загадочный».
| Применять (плюсы) | Не применять (минусы) |
|---|---|
| Хороший способ развести несколько действий в ответ на один запрос | Ещё один механизм; вариант с публикацией из UoW изящен, но неочевиден — из вызова commit не видно, что уйдёт письмо |
| Обработчики отцеплены от стержневой логики, их реализацию легко менять | Скрытая обработка выполняется **синхронно** — неожиданные просадки на веб-эндпоинтах |
| События хорошо ложатся на деловой язык, годятся для работы со стейкхолдерами | Событийный поток размазан по цепочке обработчиков — нет одного места, где видно, как выполняется запрос |
| | Риск циклических зависимостей и бесконечных циклов между обработчиками |
**Связи.** **Заменяет** исключения как поток управления: «если вы реализуете события предметной области, то не инициируйте исключения для описания той же концепции» (с. 169). Требует UoW (границы транзакции) и репозитория (`.seen`). Даёт агрегатам способ влиять друг на друга без длинных транзакций на несколько таблиц. Требует «Шину сообщений» как маршрутизатор.
---
## 9. Шина сообщений и обработчики (Message Bus, Handlers)
Словарь «тип сообщения → список обработчиков»; немая инфраструктура, ничего не знающая о смысле событий.
**Задача.** Дать событиям адресатов и позволить обработчикам порождать новые события, не превращая код в цепочку прямых вызовов. Дальше — радикальный шаг гл. 9: **входы в систему тоже становятся сообщениями**, функции сервисного слоя становятся обработчиками, различие «внутреннее/внешнее» исчезает. Обработчиков у одного события может быть несколько; они могут инициировать другие события.
Важно: шина обрабатывает по одному обработчику за раз. Цель не параллелизм, а концептуальное разделение задач и минимально малый UoW.
| Применять (плюсы) | Не применять (минусы) |
|---|---|
| Обработчики и службы — одно и то же, конструкций меньше | Непредсказуемость для веб-процесса: заранее не известно, когда всё закончится |
| Изящная структура данных на входе в систему | Неизбежное дублирование между объектами модели и событиями: поле добавляется минимум в двух местах |
| Сложные требования добавляются без архитектурных изменений — только новые события и обработчики | |
**Связи.** Требует «События предметной области». Поглощает «Сервисный слой» (`services.py` → `handlers.py`). Требует разделения на команды и события (гл. 10), иначе непонятно, что обязано выполниться. В гл. 13 превращается из модуля-одиночки в класс с внедрёнными обработчиками. Тестировать сначала «от края до края» и переходить к изолированным юнит-тестам обработчиков (через поддельную шину) только по мере усложнения цепочек.
---
## 10. Команды против событий (Commands vs Events)
Два вида сообщений, обрабатываемых одной шиной по разным правилам.
| | Событие | Команда |
|---|---|---|
| Имя | Прошедшее время («заказ размещён») | Повелительное наклонение («разместить заказ») |
| Смысл | Факт о прошлом | Намерение, чего мы хотим от системы |
| Отправка | Всем слушателям, отправитель их не знает | Одному получателю |
| Обработчиков | Много | Ровно один |
| Отказ | Независимый: логируется, повторяется, поток не прерывает | Заметный: исключение всплывает к отправителю |
**Задача.** Отделить то, что обязано выполниться (команда пользователя, меняющая один агрегат), от того, что можно доделать позже (уведомления, проекции, обновление соседних агрегатов). Успех команды не зависит от успеха обработчиков событий — занятый почтовый сервер не должен мешать принять оплату.
Восстановление: повторные попытки с экспоненциальной задержкой; каждая попытка начинается с согласованного состояния благодаря UoW.
| Применять (плюсы) | Не применять (минусы) |
|---|---|
| Видно, что обязано выполниться, а что можно привести в порядок позже | Семантическая граница между командой и событием тонкая, споры о ней бывают жаркими |
| Имя «CreateBatch» честнее, чем «BatchCreated», для входа в систему | Отказы допускаются намеренно: система становится менее понятной и требует более качественного мониторинга |
**Связи.** **Заменяет** события-как-входы из гл. 9 (`Allocate` ← `AllocationRequired`, `CreateBatch` ← `BatchCreated`). Требует агрегата как границы согласованности — именно он гарантирует, что отказ обработчика не оставит систему в противоречивом состоянии. Требует UoW для атомарности каждой попытки. Известен также как паттерн «Обработчик команд» (Command Handler).
---
## 11. Событийно-управляемая архитектура и интеграция служб (гл. 8–11, внешние события — гл. 11)
Службы интегрируются асинхронными сообщениями через брокер, а не синхронными вызовами API.
**Антипаттерн.** Резать систему по **существительным** (Заказы, Партии, Клиенты), давать каждой таблице микросервис и CRUD-интерфейс поверх анемичной модели. Граф вызовов быстро запутывается в обе стороны, а сетевой отказ одной службы бьёт по надёжности другой — «распределённый комок грязи».
**Лекарство.** Думать **глаголами**: не «система заказов», а «процесс размещения заказа». Микросервисы — такие же границы согласованности, как агрегаты: служба принимает внешние команды, публикует события, остальные слушают. Внутренние и внешние события держать раздельно; исходящие обязательно валидировать.
Архитектурно это то же приложение: сервисный слой + UoW, перенастроенные как асинхронный процессор сообщений. Потребитель событий транслирует внешние сообщения во внутренние команды, издатель выталкивает внутренние события наружу.
| Применять (плюсы) | Не применять (минусы) |
|---|---|
| Не даёт вырасти распределённому комку грязи | Совокупный поток информации труднее увидеть; логический процесс размазан по уведомлениям и неявен в коде |
| Службы отцеплены: проще менять существующие и добавлять новые | Конечная согласованность — новая концепция, с которой надо уметь работать |
| Отказ части системы не блокирует остальные | Надёжность доставки: выбирать между «как минимум один раз» и «как максимум один раз» |
**Связи.** Тот же аппарат, что для внутренних событий, только транспорт другой. Требует агрегатов (границы), команд/событий (что обязано, что нет), шины сообщений. Микросервисы **не обязательны** для остальных паттернов: «эти методы появились примерно на десять лет раньше микросервисов» (с. 287).
**Мелкий шрифт (эпилог, «Выстрел в ногу»).** Надёжный обмен сообщениями организовать очень сложно; лёгкий pub/sub из примеров ненадёжен и не годится как общецелевой транспорт. Мелкие независимо отказывающие транзакции требуют мониторинга и воспроизведения событий (см. паттерн Outbox). Идемпотентность обработчиков в книге не рассмотрена, а на практике обязательна. Схемы событий будут меняться — нужен способ версионирования и публикации схемы для потребителей.
---
## 12. CQRS — разделение обязанностей команд и запросов
Чтение и запись — разные задачи, поэтому у них разные модели.
**Задача.** Модель предметной области построена под запись: инварианты, транзакционная согласованность, сложная логика. Для чтения она неудобна и медленна — приходится дописывать вспомогательные методы в репозиторий и агрегат, гонять фильтрацию в приложении вместо БД.
| | Сторона чтения | Сторона записи |
|---|---|---|
| Поведение | Простое чтение | Сложная бизнес-логика |
| Кешируемость | Хорошая | Непригодна |
| Согласованность | Может быть устаревшей | Обязана быть транзакционной |
**Ключевой аргумент.** Устаревшее чтение безопасно: данные устаревают в момент открытия страницы, и любое размещение всё равно перепроверяет текущее состояние при записи. Никакая система не согласована с реальностью — бизнес-процессы на крайние случаи нужны в любом случае. Поэтому согласованность чтения разумно менять на производительность и горизонтальное масштабирование (реплики чтения не нужно согласовывать между собой).
Более слабая версия принципа — **CQS**: функция либо меняет состояние, либо отвечает на вопрос, но не то и другое сразу (частный случай — веб-паттерн POST/Redirect/GET).
| Вариант модели чтения | Плюсы | Минусы |
|---|---|---|
| Через существующий репозиторий | Простой согласованный подход | Просадки на сложных запросах; в репозиторий и модель лезут ненужные вспомогательные методы |
| Запросы через ORM | Переиспользуются конфигурация БД и определения модели | Ещё один язык запросов со своими причудами; риск `SELECT N+1` |
| Ручной SQL в отдельном модуле представлений | Точный контроль над производительностью, стандартный синтаксис | Изменения схемы надо вносить и в запросы, и в определения ORM; сильно нормализованные схемы всё равно упираются в join'ы |
| Отдельное денормализованное хранилище чтения, обновляемое обработчиками событий | Реплики только для чтения масштабируются легко; запросы предельно просты | Самый сложный вариант |
**Не применять**, если приложение — простой CRUD: чтение и запись там тесно связаны, ни модель предметной области, ни CQRS не нужны. Полномасштабный CQRS с отдельным хранилищем — крайний случай; выделение представлений в отдельный модуль «только для чтения» полезно само по себе.
**Связи.** Сторона чтения **сознательно обходит** репозиторий и модель предметной области — книга разбирает обе «очевидные альтернативы» и отвергает их. Модель чтения обновляется обработчиками событий, то есть **требует** событий и шины. Модель чтения перестраиваема: прогнать текущее состояние стороны записи через тот же обработчик. Интеграционный тест пишется через шину сообщений — тогда он переживает смену реализации хранилища чтения.
---
## 13. Инверсия зависимостей (DIP) — правило зависимостей
Формулировка (с. 26): (1) высокоуровневые модули не зависят от низкоуровневых, оба зависят от абстракций; (2) абстракции не зависят от деталей, детали зависят от абстракций.
**Высокоуровневые модули** — то, что интересует организацию (пациенты, сделки, инциденты). **Низкоуровневые** — то, что ей неинтересно: файловые системы, сокеты, протоколы. «Зависит от» шире, чем «импортирует»: это знание одного модуля о другом.
Смысл — менять бизнес-логику и инфраструктуру независимо: правки в домене не должны тормозить из-за миграций, а шардирование БД не должно требовать правок в бизнес-слое.
**Порты и адаптеры в терминах книги.** Термин «луковая архитектура» книга не использует; её словарь — **порты и адаптеры**, **гексагональная/чистая архитектура**, «выворачиваем трёхслойную архитектуру наизнанку».
| Понятие | Что это в книге |
|---|---|
| Порт | Интерфейс между приложением и абстрагируемым: абстрактный базовый класс либо просто утиный тип (имена методов и типы аргументов) |
| Адаптер | Реализация за этим интерфейсом |
| Первичные (ведущие) адаптеры | Точки входа: HTTP API, CLI, потребитель событий, **тесты** |
| Вторичные (ведомые) адаптеры | Репозиторий, издатель событий, отправка уведомлений — всё, что смотрит наружу из системы |
Каталоги, отражающие это правило: `domain/`, `service_layer/`, `adapters/`, `entrypoints/`; порт обычно лежит рядом со своими адаптерами.
**Проверка правила зависимостей.** Домен не импортирует ничего инфраструктурного; ORM импортирует модель, а не наоборот; сервисный слой зависит от абстрактного репозитория/UoW; конкретные реализации подключаются на внешнем краю системы.
---
## 14. Внедрение зависимостей и сценарий начальной загрузки (DI, Bootstrap)
Одно место, где приложение собирается: `bootstrap.py` — точка сборки (composition root).
**Задача.** До гл. 13 книга обходится без DI-фреймворка вообще. Проблема возникает, когда зависимостей становится несколько: неявные зависимости через импорт приходится глушить `mock.patch` в каждом тесте, а явные — руками протаскивать через каждую точку входа (веб, потребитель событий, тесты), дублируя проводку.
Сценарий начальной загрузки обязан: объявить зависимости по умолчанию с возможностью переопределить; выполнить одноразовую инициализацию (маппинги ORM, логирование); внедрить зависимости в обработчики; вернуть готовую шину сообщений.
Внедрение делается замыканиями или частичным применением. Книга показывает и «магический» вариант (инспекция сигнатур), и полностью ручной список лямбд — авторы отмечают, что ручной вариант жизнеспособен и при десятках обработчиков.
Таблицы компромиссов у главы нет; из «Выводов»:
| Стоит | Не стоит |
|---|---|
| Адаптеров несколько и проводка дублируется по точкам входа | Один-два адаптера и никакого дублирования — явная передача аргументов дешевле |
| Нужно одно место для разумных умолчаний и для подмены адаптеров подделками в тестах | |
| Есть **цепочки** зависимостей (у зависимостей свои зависимости) или внедрение в разных местах — тогда оправдан и полноценный DI-фреймворк | Внедрение только в обработчики — «ручной» DI достаточен, фреймворк избыточен |
**Рецепт «правильного» адаптера (с. 267).** 1) определить API абстрактным базовым классом; 2) реализовать настоящий; 3) сделать подделку для юнит-тестов и тестов обработчиков; 4) найти «менее поддельную» версию для контура (тестовый сервер сервиса); 5) протестировать её интеграционно.
**Связи.** **Заменяет** проводку в точках входа: они теперь только транслируют вход в команды и передают их шине. Требует, чтобы шина стала классом с внедрёнными обработчиками. Не то же самое, что DIP: DIP — правило направления зависимостей, DI — механика их подстановки.
---
## Сквозная логика книги
**Как складываются слои.** Домен (сущности, объекты-значения, агрегаты, доменные службы, события) ← сервисный слой / обработчики (варианты использования, оркестровка, UoW) ← точки входа (HTTP, CLI, потребитель событий, тесты). Наружу — адаптеры (репозиторий, издатель событий, уведомления). Всё собирается загрузчиком.
**Правило зависимостей.** Стрелки всегда указывают внутрь, к домену. Домен ничего не знает о слоях снаружи. Каждое пересечение границы идёт через порт: сервисный слой зависит от `AbstractRepository`/`AbstractUnitOfWork`, а не от их реализаций; тесты и продакшн подставляют разные адаптеры за одним и тем же портом. Книга описывает это как «выворачивание трёхслойной архитектуры наизнанку»: слой БД перестаёт быть фундаментом и становится деталью на внешнем краю.
**Направление развития по книге.** Модель предметной области → репозиторий (снимаем БД) → сервисный слой (снимаем HTTP) → UoW (снимаем сессию) → агрегат (границы согласованности) → события (снимаем побочные эффекты) → шина (входы становятся сообщениями) → команды/события (что обязано, что нет) → внешние события (границы служб) → CQRS (отделяем чтение) → загрузчик (собираем всё в одном месте). Каждый шаг вводится **после** того, как показана боль без него, — порядок в проекте разумно повторять.
**Когда весь аппарат не нужен.**
- «Если ваше приложение представляет собой простую CRUD-обёртку вокруг базы данных, то модель предметной области или репозиторий вам не нужны» (с. 71).
- «Если ваше приложение по сути является простой обёрткой CRUD вокруг базы данных и вряд ли будет чем-то большим в обозримом будущем, то вам эти паттерны не нужны. Используйте [фреймворк] и дальше и избавьте себя от многих хлопот» (с. 158).
- График с. 72: при низкой сложности домена ORM/Active Record дешевле; кривые пересекаются только при её росте. Слои косвенности стоят сложности, дублирования и порога входа для новых разработчиков.
- CQRS не нужен там, где чтение и запись концептуально совпадают.
- Микросервисы не требуются ни одним из паттернов.
**Как внедрять в существующий комок грязи (эпилог).**
1. Сформулировать проблему: трудно менять? тормозит? необъяснимые баги? Без цели не расставить приоритеты и не убедить команду.
2. Продавать как «налог на архитектуру» под конкретную новую функциональность: три недели чистки под полугодовой проект защитить легко.
3. Начать с **сервисного слоя**: выписать варианты использования (имена в повелительном наклонении), у каждого — своя транзакция, свои предусловия, свой атомарный успех/провал.
4. Дублирование на этом шаге допустимо и даже желательно: скопировать код в новое место, там привести в порядок, потом переключить вызовы. «Лучше дублировать код, чем иметь варианты использования, вызывающие друг друга в длинной цепочке».
5. Вытащить ввод-вывод и доступ к данным из модели в варианты использования.
6. Дальше — агрегаты и ограниченные контексты, затем события; переход к службам — по паттерну «Душитель» (Strangler).
---
## Карта глав
| Гл. | Стр. | Паттерн / тема |
|---|---|---|
| Введение | 21 | Комок грязи, инкапсуляция и абстракции, разделение на слои, **принцип инверсии зависимостей** |
| 1 | 32 | **Модель предметной области**: сущность, объект-значение, служба предметной области |
| 2 | 53 | **Репозиторий**; порты и адаптеры; табл. 2.1 и график компромиссов (с. 72) |
| 3 | 74 | Связанность и **выбор абстракций**; функциональное ядро / императивная оболочка; **подделки против имитаций** (с. 87) |
| 4 | 90 | **Сервисный слой** и первая точка входа; структура каталогов; табл. 4.1 |
| 5 | 109 | **TDD на повышенной и пониженной передачах**; тестовый спектр; эмпирические правила по типам тестов (с. 119) |
| 6 | 120 | **UoW**; явная фиксация и откат по умолчанию; табл. 6.1 |
| 7 | 136 | **Агрегат и границы согласованности**; инварианты; оптимистическая конкурентность; ограниченные контексты; табл. 7.1; итоги части I (с. 157) |
| 8 | 162 | **События предметной области и шина сообщений**; три схемы публикации; табл. 8.1 |
| 9 | 180 | **Всё приложение — шина сообщений**; службы становятся обработчиками; табл. 9.1 |
| 10 | 200 | **Команды и обработчики команд**; различия в обработке ошибок; повторные попытки; табл. 10.1 и 10.2 |
| 11 | 211 | **Внешние события, интеграция служб**; распределённый комок грязи; табл. 11.1 |
| 12 | 226 | **CQRS**; модель чтения; четыре варианта представлений; табл. 12.1 и 12.2 |
| 13 | 246 | **Внедрение зависимостей и сценарий начальной загрузки**; рецепт «правильного» адаптера (с. 267) |
| Эпилог | 268 | Как внедрять в существующую систему; паттерн «Душитель»; вопросы редакторов; **«Выстрел в ногу»** (с. 287) |
| Прил. А | 290 | **Сводная диаграмма и таблица компонентов** — лучшая одностраничная шпаргалка книги |
| Прил. Б | 292 | Шаблонная структура проекта |
| Прил. В | 302 | Полная замена инфраструктуры при неизменном домене |
| Прил. Г | 308 | Репозиторий и UoW поверх «толстого» фреймворка |
| Прил. Д | 318 | Валидация; паттерн «Обеспечение» (precondition) |