Ubiquitous Language: общий словарь команды
Ubiquitous Language: общий словарь команды
Каждый в команде называет одно и то же по-своему - и это медленно убивает проект. Поговорим о словаре, без которого DDD просто не работает.
Со стороны DDD выглядит как закрытый клуб бородатых архитекторов. Aggregate. Bounded Context. Ubiquitous Language. Звучит как заклинания, поэтому многие и не суются.
А идея под всем этим до смешного простая: код должен говорить на языке бизнеса, а не базы данных.
Вот так писать не надо: UpdateStatus(order, 3). Что такое 3? Отменён? Оплачен? Возвращён? Лезь в справочник, ищи.
А надо так: order.Cancel(). Читаешь код и понимаешь, что происходит в бизнесе. Не «строка в таблице со статусом 3», а «заказ отменили».
Начать можно с малого - с честных имён. Общие правила выбора имён - короткие, без аббревиатур, без лишних суффиксов - разбирались в уроке Имена в коде. Здесь речь про другое: имя должно приходить из разговора с бизнесом, а не из головы разработчика. Весь этот урок про то, как их выбирать.
Проблема: «А что ты имеешь в виду?»
Представь: дизайнер говорит «модуль», менеджер - «раздел», разработчик пишет Section, в базе лежит module_group, в API возвращается unit. Все про одно и то же. Но каждый раз, когда кто-то говорит «модуль», команда тратит 5 минут на уточнение: «Ты про раздел в курсе или про npm-модуль?»
Это не мелочь. Это системный источник багов. Вот реальный сценарий:
Менеджер: «Пользователь завершил курс, но ему не показался сертификат.»
Разработчик: «У него completed = true?»
Менеджер: «Да, все уроки пройдены.»
Разработчик: «А квизы?»
Менеджер: «Квизы? Я думал, "завершил" - это прошёл все уроки.»
Разработчик: «В коде completed = все уроки И все квизы.»
Баг не в коде. Баг в словах. У менеджера и разработчика разное понимание термина «завершил».
Что такое Ubiquitous Language
Ubiquitous Language (единый язык) - это набор терминов, которые:
- Одинаково понимают все - бизнес, разработчики, тестировщики, дизайнеры.
- Используются везде - в коде, API, документации, разговорах.
- Определены явно - у каждого термина есть чёткое определение.
ℹ️ Ubiquitous = повсеместный
Слово «ubiquitous» означает «встречающийся повсюду». Единый язык должен пронизывать всё: код, документацию, разговоры, тикеты, UI. Если в Jira написано «задание», в коде
Task, а в UI «упражнение» - язык не единый.
Пример: BackendStart
Вот как мы определяем термины на платформе BackendStart:
| Термин | Определение | НЕ путать с |
|---|---|---|
| Course | Учебный трек (Go, Docker, DDD) | program, module |
| Module | Раздел курса: группа уроков внутри курса | course, section |
| Lesson | Один урок внутри курса | lecture, topic, article |
| Quiz | Тест после урока (8-10 вопросов) | exam, test, assignment |
| Progress | Состояние прохождения курса учеником | stats, analytics |
| Completed | Все уроки курса пройдены; урок с квизом считается пройденным только после сдачи квиза | finished, done |
| Slug | URL-friendly идентификатор (ddd-lite) | id, code, key |
Обрати внимание: Completed имеет точное определение. Не «примерно все пройдено», а конкретное правило. Это убивает класс багов, описанный в начале.
Термины из этой таблицы дальше превращаются в типы. Причём не каждый - в структуру с ID: Slug не нуждается в идентификаторе, ему достаточно значения и правил формата, поэтому он становится самовалидирующимся объектом-значением, а не сущностью. Как выбрать между этими двумя вариантами, разбирается в уроке Entity и Value Object.
Naming-конфликты: реальные примеры
Пример 1: Lesson vs Lecture vs Topic
// ПЛОХО: три разных имени для одного понятия
type Lecture struct { ... } // в пакете api
type LessonItem struct { ... } // в пакете db
type Topic struct { ... } // в пакете domain
// в каждом месте - маппинг
func toLecture(t Topic) Lecture { ... }
func fromLessonItem(li LessonItem) Topic { ... }
// ПЛОХО: три разных имени для одного понятия
namespace App\Api;
final class Lecture { /* ... */ }
namespace App\Db;
final class LessonItem { /* ... */ }
namespace App\Domain;
final class Topic { /* ... */ }
// в каждом месте - маппинг
function toLecture(Topic $t): Lecture { /* ... */ }
function fromLessonItem(LessonItem $li): Topic { /* ... */ }
# ПЛОХО: три разных имени для одного понятия
class Lecture: ... # в пакете api
class LessonItem: ... # в пакете db
class Topic: ... # в пакете domain
# в каждом месте - маппинг
def to_lecture(t: Topic) -> Lecture: ...
def from_lesson_item(li: LessonItem) -> Topic: ...
Каждый маппинг - это место, где можно ошибиться. А ещё - когнитивная нагрузка: «LessonItem - это Topic или Lecture?»
// ХОРОШО: одно имя - Lesson - везде
type Lesson struct { ... } // domain
// в API: Lesson
// в базе: таблица lessons
// в UI: «Урок»
// ХОРОШО: одно имя - Lesson - везде
namespace App\Learning\Domain;
final class Lesson { /* ... */ }
// в API: Lesson
// в базе: таблица lessons
// в UI: «Урок»
# ХОРОШО: одно имя - Lesson - везде
class Lesson: ... # domain
# в API: Lesson
# в базе: таблица lessons
# в UI: «Урок»
Пример 2: User vs Student vs Learner
// ПЛОХО: кто есть кто?
type User struct { ... } // аутентификация
type Student struct { ... } // обучение
type Learner struct { ... } // аналитика
// один и тот же человек - три структуры
<?php
declare(strict_types=1);
// ПЛОХО: кто есть кто?
namespace App\Auth;
final class User { /* ... */ } // аутентификация
namespace App\Learning;
final class Student { /* ... */ } // обучение
namespace App\Analytics;
final class Learner { /* ... */ } // аналитика
// один и тот же человек - три класса
# ПЛОХО: кто есть кто?
class User: ... # аутентификация
class Student: ... # обучение
class Learner: ... # аналитика
# один и тот же человек - три класса
Решение: определить границы. User - в контексте аутентификации. Student - если мы решили, что в контексте обучения ученик называется Student. И зафиксировать это в глоссарии.
Такие границы в DDD называются Bounded Context: внутри каждой из них слово имеет ровно один смысл, а на стыке ставится переводчик, а не общая структура на все случаи. Как проводить эти границы и как контексты общаются между собой - в уроке Bounded Context.
Глоссарий: как создать и поддерживать
Глоссарий - это файл docs/glossary.md с определениями всех терминов домена.
# Глоссарий BackendStart
## Course (Курс)
Учебный трек, объединяющий уроки по одной теме.
Примеры: Go Basics, Docker, DDD Lite.
В коде: `domain.Course`. В базе: таблица `courses`.
## Module (Модуль)
Раздел курса: группа уроков внутри одного курса.
Не путать с самим курсом.
## Lesson (Урок)
Один учебный материал внутри курса. Содержит текст в Markdown.
Порядок уроков определяется полем `order`.
В коде: `domain.Lesson`. В базе: таблица `lessons`.
## Quiz (Квиз)
Тест после урока. Содержит 8-10 вопросов с вариантами ответов.
Квиз считается пройденным, если набран его проходной балл
(сейчас на BackendStart это 100%: все ответы верные).
В коде: `domain.Quiz`. В базе: таблица `quizzes`.
## Progress (Прогресс)
Состояние прохождения курса конкретным учеником.
Включает: пройденные уроки, пройденные квизы, дату начала.
Completed = все уроки курса пройдены (урок с квизом - только после сдачи квиза).
## Slug
URL-friendly идентификатор. Формат: строчные буквы, дефис вместо пробелов.
Примеры: `ddd-lite`, `go-basics`, `entity-vo`.
⚠️ Глоссарий - живой документ
Глоссарий не пишется один раз и не забрасывается. Обновляй его при каждом добавлении нового понятия. Лучшее место для обсуждения - code review: «Ты назвал это
Program. В глоссарии этоCourse. Поправь или обоснуй новый термин.»
Как такой словарь выглядит для целой доменной модели и что из него в итоге вырастает - объекты-значения, агрегат, события с именами в прошедшем времени - показано в мини-проекте трека.
UL в коде: naming conventions
Единый язык влияет на всё: имена структур, пакетов, методов, переменных.
Структуры - существительные из домена
// ПЛОХО: технические имена
type CourseDTO struct { ... }
type LessonModel struct { ... }
type ProgressEntity struct { ... }
// ХОРОШО: доменные имена (суффиксы не нужны в domain-пакете)
package domain
type Course struct { ... }
type Lesson struct { ... }
type Progress struct { ... }
<?php
declare(strict_types=1);
// ПЛОХО: технические имена
namespace App\Learning\Dto;
final class CourseDto { /* ... */ }
namespace App\Learning\Model;
final class LessonModel { /* ... */ }
namespace App\Learning\Entity;
final class ProgressEntity { /* ... */ }
// ХОРОШО: доменные имена (суффиксы не нужны в Domain-namespace)
namespace App\Learning\Domain;
final class Course { /* ... */ }
final class Lesson { /* ... */ }
final class Progress { /* ... */ }
# ПЛОХО: технические имена
class CourseDTO: ...
class LessonModel: ...
class ProgressEntity: ...
# ХОРОШО: доменные имена (суффиксы не нужны в domain-пакете)
# learning/domain.py
class Course: ...
class Lesson: ...
class Progress: ...
Методы - глаголы из домена
// ПЛОХО: технические глаголы
func (p *Progress) SetCompleted() { ... }
func (p *Progress) UpdateLessonStatus(id string, done bool) { ... }
// ХОРОШО: бизнес-глаголы
func (p *Progress) CompleteLesson(lessonID string) error { ... }
func (p *Progress) PassQuiz(quizID string, score int) error { ... }
func (p *Progress) IsCompleted(totalLessons int) bool { ... }
final class Progress
{
// ПЛОХО: технические глаголы
public function setCompleted(): void { /* ... */ }
public function updateLessonStatus(string $id, bool $done): void { /* ... */ }
// ХОРОШО: бизнес-глаголы
public function completeLesson(string $lessonId): void { /* ... */ }
public function passQuiz(string $quizId, int $score): void { /* ... */ }
public function isCompleted(int $totalLessons): bool { /* ... */ }
}
class Progress:
# ПЛОХО: технические глаголы
def set_completed(self) -> None: ...
def update_lesson_status(self, lesson_id: str, done: bool) -> None: ...
# ХОРОШО: бизнес-глаголы
def complete_lesson(self, lesson_id: str) -> None: ...
def pass_quiz(self, quiz_id: str, score: int) -> None: ...
def is_completed(self, total_lessons: int) -> bool: ...
CompleteLesson - это то, что скажет менеджер. UpdateLessonStatus - это то, что скажет разработчик, думающий о базе. Ровно та же разница, что между UpdateStatus(order, 3) и order.Cancel().
У такого метода-глагола есть и вторая роль: он единственная точка входа для изменения состояния, и внутри него же проверяются правила («урок не из этого курса», «урок уже пройден»). Почему сеттеры эти правила обходят, а метод из единого языка - нет, разбирается в уроке Aggregates и инварианты.
Пакеты - контексты домена
// ПЛОХО: технические пакеты
package models
package helpers
package utils
package managers
// ХОРОШО: доменные пакеты
package course // всё про курсы
package progress // всё про прогресс
package quiz // всё про квизы
package auth // всё про аутентификацию
<?php
declare(strict_types=1);
// ПЛОХО: технические namespaces
namespace App\Models;
namespace App\Helpers;
namespace App\Utils;
namespace App\Managers;
// ХОРОШО: доменные namespaces (Symfony bundle-структура)
namespace App\Course; // всё про курсы
namespace App\Progress; // всё про прогресс
namespace App\Quiz; // всё про квизы
namespace App\Auth; // всё про аутентификацию
# ПЛОХО: технические пакеты
from app.models import Course
from app.helpers import slugify
from app.utils import now
from app.managers import ProgressManager
# ХОРОШО: доменные пакеты
from app.course import Course # всё про курсы
from app.progress import Progress # всё про прогресс
from app.quiz import Quiz # всё про квизы
from app.auth import User # всё про аутентификацию
Рефакторинг: от плохих имён к UL
Вот полный пример рефакторинга Go-кода с учётом единого языка. По сути это тот же переход от «строки в таблице» к бизнес-действию, только на масштабе целого пакета:
// БЫЛО: имена не из домена
package handlers
import (
"encoding/json"
"net/http"
"gorm.io/gorm"
)
type CourseController struct {
db *gorm.DB
}
func (c *CourseController) HandleGetModules(w http.ResponseWriter, r *http.Request) {
var items []ModuleRecord
c.db.Where("program_id = ?", r.URL.Query().Get("program_id")).Find(&items)
var result []ModuleResponse
for _, item := range items {
result = append(result, ModuleResponse{
Code: item.Code,
Label: item.Label,
NumUnits: item.UnitCount,
})
}
json.NewEncoder(w).Encode(result)
}
// БЫЛО: имена не из домена
namespace App\Controllers;
final class CourseController
{
public function __construct(private readonly EntityManagerInterface $em) {}
public function handleGetModules(Request $request): JsonResponse
{
$programId = $request->query->get('program_id');
$items = $this->em->getRepository(ModuleRecord::class)
->findBy(['programId' => $programId]);
$result = [];
foreach ($items as $item) {
$result[] = [
'code' => $item->code,
'label' => $item->label,
'numUnits' => $item->unitCount,
];
}
return new JsonResponse($result);
}
}
# БЫЛО: имена не из домена
# handlers/course.py
# Request/JsonResponse - условные типы веб-слоя; в FastAPI/Django это view-функция.
from sqlalchemy.orm import Session
class CourseController:
def __init__(self, db: Session) -> None:
self.db = db
def handle_get_modules(self, request: Request) -> JsonResponse:
program_id = request.query.get("program_id")
items = (
self.db.query(ModuleRecord)
.filter(ModuleRecord.program_id == program_id)
.all()
)
result = []
for item in items:
result.append({
"code": item.code,
"label": item.label,
"numUnits": item.unit_count,
})
return JsonResponse(result)
// СТАЛО: имена из единого языка
package course
import (
"context"
"encoding/json"
"net/http"
)
// В domain-пакете
type Course struct {
ID string
Slug string
Title string
TotalLessons int
}
// В application-пакете
type ListCoursesUseCase struct {
courses CourseRepository
}
func (uc *ListCoursesUseCase) Execute(ctx context.Context) ([]Course, error) {
return uc.courses.FindAll(ctx)
}
// В handler-пакете.
// Внешний контракт API не меняем: клиенты по-прежнему получают
// code, label и numUnits. Меняются только внутренние имена.
type courseResponse struct {
Code string `json:"code"`
Label string `json:"label"`
NumUnits int `json:"numUnits"`
}
func (h *Handler) ListCourses(w http.ResponseWriter, r *http.Request) {
courses, err := h.listCourses.Execute(r.Context())
if err != nil {
http.Error(w, "internal error", http.StatusInternalServerError)
return
}
resp := make([]courseResponse, 0, len(courses))
for _, c := range courses {
resp = append(resp, courseResponse{
Code: c.Slug,
Label: c.Title,
NumUnits: c.TotalLessons,
})
}
json.NewEncoder(w).Encode(resp)
}
<?php
declare(strict_types=1);
// СТАЛО: имена из единого языка
namespace App\Learning\Domain;
final class Course
{
public function __construct(
public readonly string $id,
public readonly string $slug,
public readonly string $title,
public readonly int $totalLessons,
) {}
}
namespace App\Learning\Application;
final class ListCoursesUseCase
{
public function __construct(
private readonly CourseRepository $courses,
) {}
/** @return Course[] */
public function execute(): array
{
return $this->courses->findAll();
}
}
namespace App\Learning\Http;
final class CourseController
{
public function __construct(
private readonly ListCoursesUseCase $listCourses,
) {}
public function listCourses(): JsonResponse
{
// Внешний контракт API не меняем: клиенты по-прежнему получают
// code, label и numUnits. Меняются только внутренние имена.
$result = [];
foreach ($this->listCourses->execute() as $course) {
$result[] = [
'code' => $course->slug,
'label' => $course->title,
'numUnits' => $course->totalLessons,
];
}
return new JsonResponse($result);
}
}
# СТАЛО: имена из единого языка
from dataclasses import dataclass
from typing import Protocol
# В domain-пакете: course/domain.py
@dataclass
class Course:
id: str
slug: str
title: str
total_lessons: int
class CourseRepository(Protocol):
def find_all(self) -> list[Course]: ...
# В application-пакете: course/application.py
class ListCoursesUseCase:
def __init__(self, courses: CourseRepository) -> None:
self._courses = courses
def execute(self) -> list[Course]:
return self._courses.find_all()
# В handler-пакете: course/http.py
class Handler:
def __init__(self, list_courses: ListCoursesUseCase) -> None:
self._list_courses = list_courses
def list_courses(self, request: Request) -> JsonResponse:
try:
courses = self._list_courses.execute()
except Exception:
return JsonResponse("internal error", status=500)
# Внешний контракт API не меняем: клиенты по-прежнему получают
# code, label и numUnits. Меняются только внутренние имена.
return JsonResponse([
{"code": c.slug, "label": c.title, "numUnits": c.total_lessons}
for c in courses
])
Что изменилось:
Module->Course(в старом коде «модулем» звали то, что в глоссарии называется Course; настоящий Module у нас - раздел внутри курса)Program-> убрано (это был лишний уровень)Unit->LessonCode->SlugLabel->TitleController->Handler(так принято в Go-проектах по аналогии сhttp.Handler; в PHP и Python можно оставить Controller)
Одна оговорка про границы. Единый язык обязателен внутри домена, а во внешнем контракте API поля живут своей жизнью: их нельзя переименовать одним коммитом, не сломав клиентов. Поэтому переименование Code в Slug внутри не должно тянуть за собой правку JSON-ответа - между доменом и внешним миром для этого и стоит слой переносчиков, описанный в уроке про DTO и маппинг.
Анти-паттерны единого языка
1. Транслитерация
// ПЛОХО: русские слова в латинице
type Urok struct { ... }
type Kurs struct { ... }
func (p *Progress) ZavershitUrok(id string) { ... }
// ХОРОШО: английские термины из глоссария
type Lesson struct { ... }
type Course struct { ... }
func (p *Progress) CompleteLesson(id string) error { ... }
<?php
declare(strict_types=1);
// ПЛОХО: русские слова в латинице
final class Urok { /* ... */ }
final class Kurs { /* ... */ }
final class Progress
{
public function zavershitUrok(string $id): void { /* ... */ }
}
<?php
declare(strict_types=1);
// ХОРОШО: английские термины из глоссария
final class Lesson { /* ... */ }
final class Course { /* ... */ }
final class Progress
{
public function completeLesson(string $id): void { /* ... */ }
}
# ПЛОХО: русские слова в латинице
class Urok: ...
class Kurs: ...
class Progress:
def zavershit_urok(self, lesson_id: str) -> None: ...
# ХОРОШО: английские термины из глоссария
class Lesson: ...
class Course: ...
class Progress:
def complete_lesson(self, lesson_id: str) -> None: ...
2. Аббревиатуры без контекста
// ПЛОХО: что такое LP? CP? UPR?
type LP struct { ... }
func GetCP(uid string) *UPR { ... }
// ХОРОШО: полные имена
type LessonProgress struct { ... }
func GetCourseProgress(userID string) (*UserProgress, error) { ... }
<?php
declare(strict_types=1);
// ПЛОХО: что такое LP? CP? UPR?
final class LP { /* ... */ }
function getCp(string $uid): UPR { /* ... */ }
// ХОРОШО: полные имена
final class LessonProgress { /* ... */ }
function getCourseProgress(string $userId): UserProgress { /* ... */ }
# ПЛОХО: что такое LP? CP? UPR?
class LP: ...
def get_cp(uid: str) -> UPR: ...
# ХОРОШО: полные имена
class LessonProgress: ...
def get_course_progress(user_id: str) -> UserProgress: ...
3. Смешение языков в одном идентификаторе
// ПЛОХО: микс русского и английского
func PoluchitSpisokUrokov() { ... } // транслитерация + английский
func GetУроки() { ... } // английский + кириллица
// ХОРОШО: один язык
func ListLessons() { ... }
<?php
declare(strict_types=1);
// ПЛОХО: микс русского и английского
function poluchitSpisokUrokov(): array { /* ... */ } // транслитерация + английский
function getУроки(): array { /* ... */ } // английский + кириллица
// ХОРОШО: один язык
function listLessons(): array { /* ... */ }
# ПЛОХО: микс русского и английского
def poluchit_spisok_urokov() -> list: ... # транслитерация + английский
def get_уроки() -> list: ... # английский + кириллица
# ХОРОШО: один язык
def list_lessons() -> list: ...
🚫 Смешение языков - красная линия
Если в коде встречается транслитерация или кириллица в идентификаторах - это сигнал, что единый язык не определён. Остановись, создай глоссарий, согласуй термины с командой.
Как синхронизировать UL в команде
- Глоссарий в репозитории -
docs/glossary.md, ревьюится как код. - Code review - проверяй не только логику, но и именование. «Ты назвал это
program, у нас этоcourse.» - PR-шаблон - добавь чекбокс: «Новые термины добавлены в глоссарий».
- Onboarding - первое, что читает новый разработчик - глоссарий.
- Рефакторинг при расхождении - если обнаружил несоответствие, исправь сразу, не копи техдолг.
<!-- .gitlab/merge_request_templates/default.md -->
## Checklist
- [ ] Код соответствует единому языку (glossary.md)
- [ ] Новые термины добавлены в глоссарий
- [ ] Нет транслитерации и аббревиатур без контекста
Мини-задание
- Составь глоссарий из 10 терминов для своего проекта (или BackendStart): термин + определение в 1 строку
- Найди в коде 3 места, где одно и то же понятие названо по-разному, и унифицируй
- Добавь в PR-шаблон чекбокс проверки единого языка
- Проверь свой код на транслитерацию и аббревиатуры - замени на термины из глоссария
- Покажи глоссарий коллеге (или ментору) и обсуди: все ли термины понятны?