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

Сущность с именем Customer может означать плательщика, получателя заказа или человека, который оставил заявку. Пока эти роли живут в одной переменной, ошибка кажется косметической. После релиза она превращается в путаницу в правилах доступа, API и отчётах. Перед продакшеном проверьте доменные имена как часть поведения системы, а не как украшение кода.

Что именно проверять

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

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

Чек-лист перед релизом

1. Назовите роль, а не просто участника. Если в сценарии есть покупатель, получатель, плательщик и представитель компании, не сводите их к одному User или Customer. Для каждого имени спросите: какую роль этот объект играет именно здесь? Проверка: участники команды могут по названию отличить, чьи права или данные используются.
2. Сверьте термин с языком бизнеса. Найдите слово в требованиях, интерфейсе, договорах или рабочих инструкциях. Если команда говорит «возврат», а модель — Cancellation, выясните, это одно действие или разные процессы. Проверка: владелец процесса узнаёт термин без перевода с внутреннего жаргона.
3. Уберите неоднозначные сокращения. Addr, Proc и Dt экономят несколько символов, но заставляют читателя угадывать. Исключение — устоявшиеся сокращения, которые одинаково понимают все участники проекта. Проверка: новый разработчик может объяснить имя без подсказки автора.
4. Проверьте, что существительное не маскирует действие. Сущность хранит состояние или идентичность; команда просит систему выполнить действие; событие сообщает о том, что уже произошло. Если OrderUpdate иногда означает запрос на изменение, а иногда — состоявшееся изменение, имя скрывает важное различие. Проверка: по названию понятно, это просьба, факт или объект данных.
5. Уточните смысл статусов. Active, Closed и Done часто кажутся очевидными, пока не появляются исключения. Укажите, что именно закрыто, кем и при каком условии. Проверка: для каждого значения можно назвать переход, который его устанавливает, и допустимые следующие состояния.
6. Сопоставьте имена на границах системы. Сравните модель, схему базы, API, сообщения очереди и названия в интерфейсе. Они не обязаны совпадать буквально: внешний контракт может иметь собственные ограничения. Но преобразование должно быть явным. Проверка: в коде или документации понятно, почему одно понятие называется по-разному.
7. Поищите дубли смысла. Account, Profile и CustomerRecord могут оказаться тремя названиями одной сущности — или тремя разными объектами. Не объединяйте их только ради единообразия: сначала сравните жизненный цикл, владельца данных и правила изменения. Проверка: для каждого похожего имени команда может объяснить отличие.
8. Проверьте имена на отрицательных примерах. Посмотрите, как они читаются для отменённого заказа, гостя без аккаунта, частичного возврата или повторной оплаты. Если имя становится ложным в обычном состоянии системы, оно слишком узкое. Проверка: крайний случай не требует переименовывать объект или трактовать его смысл задним числом.

Три способа разбирать спорные имена

Не каждое расхождение решается заменой слова. Выберите подход по цене ошибки и по тому, где имя видно.

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

Хорошее доменное имя не просто понятно автору. Оно помогает следующему человеку заметить, когда система делает не то, что обещает бизнес-процесс.

Как провести ревью без переименования всего проекта

1. Выберите один сценарий, который меняется в релизе, и выпишите его ключевые понятия: участники, действия, состояния и результаты.
2. Проследите каждое понятие через модель, хранилище, API и события. Отметьте места, где смысл меняется или название не совпадает.
3. Для каждого спорного имени запишите короткое определение и пример того, что к нему не относится. Это обнаружит скрытые разногласия быстрее, чем голосование за «красивое» слово.
4. Разделите решения на блокирующие релиз и косметические. Блокируйте выпуск, если неоднозначность может изменить права, сумму, статус операции или смысл внешнего контракта. Остальные замечания внесите в план улучшений.
5. Перед слиянием проверьте миграции, совместимость API и потребителей событий. Переименование в коде не гарантирует, что старое имя можно сразу убрать из базы или контракта.

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

Что чаще всего ломается

Слово общее, а правила разные

Например, «активный клиент» может означать действующий договор для отдела продаж и пользователя с недавним входом для продуктовой аналитики. Одно имя в двух контекстах создаёт впечатление, что метрики сопоставимы. Разведите определения по контекстам или используйте разные термины там, где это влияет на решение.

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

Внутреннее имя можно поменять отдельно от поля публичного API, но это не означает, что изменение безопасно. Клиенты могут зависеть от прежнего поля, а потребители очереди — от названия события. До релиза установите, кто читает контракт, как долго нужна обратная совместимость и в каком порядке обновятся производители и потребители.

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

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

Сноска. Повсеместный язык — согласованный набор терминов предметной области, которым пользуются и бизнес-участники, и команда разработки. Он не требует одинаковых имён во всех слоях системы, но требует, чтобы различия и преобразования были понятны.

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

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