Спроектируйте модель, затем код.

Карта доменов

Знакомство с новой системой всегда начинается с вопроса, зачем она и что делает. Это вопросы о смысле, а не об устройстве. Но первым ответом обычно оказывается инфраструктура: контроллеры, сервисы, репозитории, миграции. Предметной области за ними не разглядеть.

Карта доменов — это ответ на первый вопрос. На ней — только области, из которых состоит система: StoreDomain — управление заказами, BillingDomain — биллинг, MessagingDomain — рассылки. Такой ответ без деталей охватывает систему целиком и помещается в голове — как первая опора.

Сущности выражают домен

В домене две главные вещи: Entity — заказ, клиент, позиция — и Action, именованные операции над ними. Ни контроллеров, ни таблиц, ни прочей инфраструктуры. Это позволяет спуститься на шаг глубже и удержать фокус на бизнес-намерениях системы, а не на технической реализации.

Entity — обычный класс: имя, типизированные поля и больше ничего. Он ничего не знает ни про ORM, ни про таблицы, ни про то, откуда придут данные, — его единственная задача описать объект реального мира так, как о нём говорят: у заказа есть сумма и валюта, у клиента — имя и почта. Поля бывают двух родов: простые — строка, число, дата — и ссылки на другие Entity, потому что у заказа есть клиент и есть позиции. Вторые и превращают набор отдельных классов в модель — о них следующий раздел. При этом поведения у Entity нет: он только описывает, а всё, что с объектом делают, живёт в Action.

Связи явно задают владение

Из чего домен состоит, уже понятно. А как он держится и что не даёт связям разойтись?

Связь описывают двумя вещами: насколько крепко объекты держатся друг за друга — композиция, агрегация или ассоциация — и сколько объектов стоит с каждой стороны, один или несколько. Каждая сущность объявляет связь целиком: и свою сторону, и встречную, с типом и кратностью у обеих. Поэтому достаточно посмотреть на одну сущность, чтобы увидеть все её отношения сразу. На старте система сверяет каждую пару — разошлись, и запуск останавливается. Иногда второй стороны нет: связь смотрит за пределы своей базы. Это тоже можно, но объявляется явно.

Lifecycle контролирует каждый переход

Пока статус — просто строка, ничто не мешает заказу попасть из черновика сразу в доставленные. Что разрешено, а что нет, живёт в голове у команды или в комментарии, который давно устарел.

В AOA эти правила перестают быть устными: состояния заказа и переходы между ними объявляются рядом с самой сущностью как конечный автомат — черновик, оплачен, отправлен, доставлен, а отмена возможна только из первых двух. Это не рекомендация: если перехода нет в списке, его не существует, и заказ не может оказаться доставленным, не будучи оплаченным. Сам конечный автомат проверяется на старте: состояние, в которое нельзя попасть, или переход в никуда останавливают запуск задолго до того, как через систему пройдёт первый заказ.

Автомат объявляется сам по себе: какие состояния может принимать заказ и какие переходы между ними разрешены. Один раз, отдельно от любой сущности.

Теперь его можно применить: у OrderEntity поле status перестаёт быть строкой и получает тип OrderLifecycle. Строка принимала любое значение — этот тип только те, до которых есть путь.

Resources задают границу хранилища

Модель описывает предметную область, но с базами данных напрямую не работает: она не должна зависеть от их реализации. Значит, кто-то другой должен доставать данные из реальной базы — и класть обратно.

Это и есть работа Resource. Он держит всё, что должно жить между вызовами: соединение, пул, клиента. Его дело — открыть, выполнить, вернуть; бизнес-правил внутри нет. Через эту границу проходят сущности. Одна и та же модель может быть представлена сразу в нескольких Resource: один читает из SQL, другой из NoSQL, третий из чужого HTTP-сервиса, и все возвращают тот же OrderEntity. Код бизнес-логики не знает, какой вариант Resource был использован: ни имени таблицы, ни диалекта, ни формата ответа в него не попадает. Поэтому сменить хранилище — значит поменять только Resource.

Проекции формируют нужный срез

Одна и та же сущность читается из базы то целиком, то частично, то вообще одним идентификатором. Обычный ответ на это — зоопарк DTO, по отдельному классу на каждый случай.

Обычный подход — заводить свой DTO под каждый метод ресурса. В отличие от обычных словарей это даёт статическую защиту от опечаток в именах полей. Но у подхода есть другая сторона: исходная сущность распадается на множество мелких DTO, и модель предметной области сохраняется только в документации и на чертежах, которые устаревают ещё до первого релиза.

Идея AOA в том, чтобы не отказываться от целостной модели: операции ресурса возвращают сами её объекты, как они объявлены. Поля читаются через именованные атрибуты, как у DTO, но новых классов не появляется — и положить в модель поле, которого в ней нет, становится невозможно. Её актуальность подтверждает тот же код, который ею пользуется, а ERD рисуется прямо из неё.

Поэтому вводится понятие проекции данных: когда метод ресурса читает сущность не целиком, он возвращает ту же самую сущность, но поля, не прочитанные из базы, помечены как недоступные. При первой же попытке их использовать система выдаст понятное исключение, а не промолчит.

get_order(order_id) → OrderEntity

Очевидный случай — вся сущность, каждое поле загружено; класс модели, используемый ровно так, как объявлен.

find_orders(query) → list[OrderEntity]

Тонкая коллекция — загружен только id каждого заказа; чтение любого другого поля вызвало бы ошибку.

get_full_order_info(order_id) → OrderEntity

Глубокий случай — заказ плюс его вложенные сущности, каждая загружена до своей частичной глубины (id загружается всегда, это ключ).