Именование сущностей в домене: как не переписать модель

Если в интернет-магазине один разработчик называет покупателя Customer, другой — Client, а аналитика хранит его как Buyer, проблема появится не в словаре, а в поведении системы. Начнут расходиться права, статусы и бизнес-правила. Ниже — практика именования доменных сущностей для DDD-проектов без привязки к языку и фреймворку: как выбрать имя с первого раза, проверить его на реальных сценариях и понять, когда одинаковые слова не должны означать один объект.

Имя должно описывать роль, а не таблицу

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

Сущность — объект, который сохраняет свою идентичность во времени, даже если его свойства изменились. Заказ может перейти из статуса «создан» в «оплачен», но остаться тем же заказом. Имя должно помогать ответить на вопрос: кто или что участвует в этом бизнес-правиле.

Сравните:

• User — техническое и слишком широкое имя, если речь идёт о том, кто оформляет заказ;
• Customer — покупатель в контексте продаж;
• AccountHolder — владелец платёжного аккаунта, если это отдельная роль;
• SupportAgent — сотрудник, который обрабатывает обращения.

Эти объекты могут ссылаться на одну запись учётной записи, но бизнес-правила у них разные. Не стоит объединять их только потому, что у всех есть имя, электронная почта и идентификатор.

Хорошее доменное имя отвечает не на вопрос «что лежит в таблице», а на вопрос «какую ответственность объект несёт в этом сценарии».

Три подхода к выбору имени

Техническое имя из базы данных

Такой подход начинается с таблиц и DTO: User, OrderItem, PaymentStatus. Он быстро запускает разработку, особенно если ORM генерирует модели автоматически. Цена скорости — потеря смысла. Когда бизнес попросит различать резерв, заказ и отгрузку, техническое слово Order окажется слишком коротким и начнёт использоваться для нескольких объектов.

Перевод термина из требований

Здесь имя переводят почти дословно: «партнёр» становится Partner, «заявка» — Request, «исполнитель» — Executor. Подход лучше технического, но опасен ложными друзьями и разными значениями одного слова. В английском Request может быть и заявкой клиента, и HTTP-запросом, и внутренней просьбой сервиса.

Имя из бизнес-операции и инварианта

Надёжнее начать с действия: кто оформляет заказ, кто принимает оплату, кто подтверждает поставку. Затем зафиксировать правило, которое объект должен защищать. Например, «заявка на возврат» и «возврат товара» могут быть разными сущностями: первая ожидает решения, второй уже меняет остатки и движение денег.

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

Как проверить имя до написания кода

Проверка должна проходить не по списку красивых слов, а по сценариям. Возьмите три-четыре операции, в которых сущность участвует, и подставьте имя в обычные фразы. Если фраза звучит неестественно или допускает два толкования, имя ещё не готово.

1. Опишите роль. Закончите предложение: «Эта сущность нужна, чтобы…». Для Customer ответом может быть «оформлять покупки и получать возвраты», а не «хранить данные пользователя». Если получается описание таблицы, вернитесь к бизнес-сценарию.
2. Проверьте глаголы. Составьте фразы «сущность создаёт», «сущность подтверждает», «сущность отменяет». Если объект не может выполнить действие сам, возможно, вы назвали процесс, событие или справочное значение, а не сущность.
3. Отделите роли от идентичности. Спросите, может ли объект перестать быть участником процесса, но остаться тем же объектом. Если да, роль может быть свойством или отдельной моделью. Если нет, не смешивайте её с универсальным User.
4. Проверьте границы контекста. В продажах Order может быть заказом клиента, а на складе — заданием на комплектацию. Не переиспользуйте одно имя только ради общей библиотеки.
5. Проговорите имя вслух. Покажите его разработчику и эксперту бизнеса без поясняющего абзаца. Каждый должен описать один и тот же объект. Если объяснение начинается со слов «у нас это немного особый…», добавьте уточнение в имя или ограничьте его контекстом.

Сущность, значение, событие и справочник — не одно и то же

Частая ошибка — называть все объекты сущностями. У них разные признаки и жизненный цикл.

• Сущность имеет устойчивую идентичность: заказ остаётся тем же заказом после изменения адреса.
• Объект-значение описывает свойства без отдельной идентичности: сумма, диапазон дат или адрес могут сравниваться по содержимому.
• Событие сообщает о том, что уже произошло: OrderPaid не является заказом и не должен хранить его как собственное состояние.
• Справочник задаёт ограниченный набор значений: статус, тип доставки или код страны. Это не повод создавать универсальный объект Entity для каждой строки.

Если назвать событие сущностью, код начнёт менять прошлое вместо фиксации факта. Если назвать объект-значение сущностью, появятся лишние идентификаторы, таблицы и операции обновления.

Термин: ограниченный контекст (bounded context) — граница, внутри которой слово, модель и правила имеют согласованное значение. За её пределами тот же термин может описывать другой объект.

Что ломается из-за плохих имён

Один термин начинает означать несколько вещей

В начале проект использует Order для заказа. Потом в него добавляют поля склада, доставки и платежа. Через несколько месяцев любое изменение оплаты затрагивает складскую модель, потому что граница между объектами исчезла. Исправление обычно требует миграции данных, изменения API и согласования событий между сервисами.

Синонимы расходятся по слоям

Когда домен говорит «заявка», API использует Ticket, база — Request, а интерфейс — «обращение», поиск по коду перестаёт работать как инструмент понимания системы. Выберите один термин для конкретного контекста. Если разные команды используют разные слова намеренно, зафиксируйте соответствие и не прячьте его в неявных преобразованиях.

Аббревиатуры делают модель локальной

Mgr, Acct и Cfg экономят несколько символов, но усложняют ревью, поиск и подключение новых разработчиков. Исключение — устоявшаяся предметная аббревиатура, которую одинаково расшифровывают все участники проекта. Даже тогда расшифровку стоит записать в глоссаре.

Когда одинаковые имена всё-таки допустимы

Повторение имени в разных модулях не всегда ошибка. Customer в контексте продаж и Customer в контексте программы лояльности могут иметь разные поля, правила и идентификаторы. Ошибка начинается тогда, когда команда делает вид, что это одна универсальная модель, и передаёт её между подсистемами без явного преобразования.

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

Что делать дальше

Создайте небольшой глоссарий домена: термин, определение в одном предложении, контекст, запрещённые синонимы и пример операции. Подключите его к ревью требований и pull request: любое новое имя должно иметь сценарий, который оно описывает.

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