forked from mtusi2026/mtusi2026lab3
Bring the Claude Code settings, the lint hook, the opsx commands and skills, the architecture notes, the lab 1 and lab 2 specs and the archived lab 1 and lab 2 changes into the lab 3 skeleton, so lab 3 continues the same spec history instead of starting from scratch. Rewrite AGENTS.md and the openspec context and rules for lab 3: HAProxy in front of several stateless API replicas, X-Instance-Id on every response, a mandatory Idempotency-Key for messages shared by all replicas through PostgreSQL, explicit stop-one and restart hooks, Out of scope moved to labs 4-7 plus Swarm and HA storage, and rules on retry policy, timeout chains and replica-local state. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
350 lines
54 KiB
Markdown
350 lines
54 KiB
Markdown
# Паттерны разработки на 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) |
|