Aggregates и инварианты: правила, которые нельзя нарушать

Aggregates и инварианты: правила, которые нельзя нарушать

Когда данные становятся невалидными, бизнес теряет деньги, а ты - выходные. Aggregates - про правила, которые код просто не даёт нарушить.

Проблема: данные разъезжаются

Представь: у пользователя BackendStart прогресс курса - 147%. Или он «завершил» урок, которого нет в треке. Или две горутины одновременно обновили прогресс и одно обновление потерялось.

Всё это происходит, когда бизнес-правила разбросаны по handler'ам, сервисам и middleware. Никто не контролирует целостность данных на уровне домена. Aggregate решает эту проблему.

Что такое Aggregate

Aggregate - группа связанных объектов, которые меняются как единое целое. У каждого агрегата есть Aggregate Root - единственная точка входа для всех изменений.

Ключевая идея: внешний код никогда не обращается к внутренним объектам агрегата напрямую. Все изменения проходят через корень.

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

Aggregate Root: внешний use case вызывает методы только корня CourseProgress; LessonProgress скрыты внутри агрегата

// CourseProgress - Aggregate Root.
// Внешний код работает ТОЛЬКО через методы этой структуры.
type CourseProgress struct {
    id         string
    userID     string
    courseID   string
    lessons    map[string]*LessonProgress // внутренние объекты
    percent    int
    startedAt  time.Time
    completedAt *time.Time
}

// LessonProgress - внутренний объект агрегата.
// Внешний код НЕ должен создавать или менять его напрямую.
type LessonProgress struct {
    lessonID    string
    completed   bool
    completedAt *time.Time
}
<?php
declare(strict_types=1);

namespace App\Learning\Domain;

use DateTimeImmutable;

// CourseProgress - Aggregate Root.
// НЕ readonly: агрегат мутируется (percent, completedAt, lessons).
// Внешний код работает ТОЛЬКО через методы этого класса.
final class CourseProgress
{
    /**
     * @param array<string, LessonProgress> $lessons
     * @param object[]                       $events
     */
    public function __construct(
        private readonly string $id,
        private readonly string $userId,
        private readonly string $courseId,
        private array $lessons,           // внутренние объекты
        private int $percent,
        private readonly DateTimeImmutable $startedAt,
        private ?DateTimeImmutable $completedAt = null,
        private array $events = [],
    ) {}
}

// LessonProgress - внутренний объект агрегата.
// Внешний код НЕ должен создавать или менять его напрямую.
final class LessonProgress
{
    public function __construct(
        public readonly string $lessonId,
        private bool $completed = false,
        private ?DateTimeImmutable $completedAt = null,
    ) {}

    public function isCompleted(): bool { return $this->completed; }

    public function markCompleted(DateTimeImmutable $at): void
    {
        $this->completed = true;
        $this->completedAt = $at;
    }
}
from dataclasses import dataclass, field
from datetime import datetime


@dataclass
class LessonProgress:
    """Внутренний объект агрегата.

    Внешний код НЕ должен создавать или менять его напрямую.
    """

    lesson_id: str
    completed: bool = False
    completed_at: datetime | None = None


@dataclass
class CourseProgress:
    """Aggregate Root.

    Внешний код работает ТОЛЬКО через методы этого класса.
    Поля с подчёркиванием - приватные по соглашению (аналог lowercase в Go).
    """

    _id: str
    _user_id: str
    _course_id: str
    _lessons: dict[str, LessonProgress]  # внутренние объекты
    _percent: int = 0
    _started_at: datetime = field(default_factory=datetime.now)
    _completed_at: datetime | None = None

Инварианты: правила, которые всегда истинны

Инвариант - бизнес-правило, которое агрегат обязан поддерживать в любой момент времени. Если инвариант нарушен, данные невалидны.

Инварианты BackendStart для CourseProgress:

  1. Процент прогресса всегда в диапазоне 0..100
  2. Нельзя завершить урок, которого нет в курсе
  3. Нельзя завершить уже завершённый урок повторно
  4. Процент пересчитывается автоматически при завершении урока
// courseLessons - список допустимых уроков курса (передаётся при создании).
func NewCourseProgress(id, userID, courseID string, courseLessons []string) *CourseProgress {
    lessons := make(map[string]*LessonProgress, len(courseLessons))
    for _, lid := range courseLessons {
        lessons[lid] = &LessonProgress{lessonID: lid}
    }
    return &CourseProgress{
        id:        id,
        userID:    userID,
        courseID:  courseID,
        lessons:   lessons,
        percent:   0,
        startedAt: time.Now(),
    }
}

func (cp *CourseProgress) CompleteLesson(lessonID string) error {
    // Инвариант 2: урок должен существовать в курсе
    lp, exists := cp.lessons[lessonID]
    if !exists {
        return fmt.Errorf("lesson %s does not belong to course %s", lessonID, cp.courseID)
    }

    // Инвариант 3: нельзя завершить повторно
    if lp.completed {
        return fmt.Errorf("lesson %s already completed", lessonID)
    }

    now := time.Now()
    lp.completed = true
    lp.completedAt = &now

    // Инвариант 1 и 4: пересчёт процента (всегда 0..100)
    cp.recalcPercent()

    return nil
}

func (cp *CourseProgress) recalcPercent() {
    total := len(cp.lessons)
    if total == 0 {
        cp.percent = 0
        return
    }

    done := 0
    for _, lp := range cp.lessons {
        if lp.completed {
            done++
        }
    }

    cp.percent = (done * 100) / total

    if cp.percent == 100 {
        now := time.Now()
        cp.completedAt = &now
    }
}
<?php
declare(strict_types=1);

namespace App\Learning\Domain;

use DateTimeImmutable;
use DomainException;

final class CourseProgress
{
    // courseLessons - список допустимых уроков курса (передаётся при создании).
    /** @param string[] $courseLessons */
    public static function start(
        string $id,
        string $userId,
        string $courseId,
        array $courseLessons,
    ): self {
        $lessons = [];
        foreach ($courseLessons as $lid) {
            $lessons[$lid] = new LessonProgress($lid);
        }
        return new self(
            $id,
            $userId,
            $courseId,
            $lessons,
            0,
            new DateTimeImmutable(),
        );
    }

    public function completeLesson(string $lessonId): void
    {
        // Инвариант 2: урок должен существовать в курсе
        if (!isset($this->lessons[$lessonId])) {
            throw new DomainException(sprintf(
                'lesson %s does not belong to course %s',
                $lessonId,
                $this->courseId,
            ));
        }
        $lp = $this->lessons[$lessonId];

        // Инвариант 3: нельзя завершить повторно
        if ($lp->isCompleted()) {
            throw new DomainException(sprintf('lesson %s already completed', $lessonId));
        }

        $lp->markCompleted(new DateTimeImmutable());

        // Инвариант 1 и 4: пересчёт процента (всегда 0..100)
        $this->recalcPercent();
    }

    private function recalcPercent(): void
    {
        $total = count($this->lessons);
        if ($total === 0) {
            $this->percent = 0;
            return;
        }
        $done = 0;
        foreach ($this->lessons as $lp) {
            if ($lp->isCompleted()) {
                $done++;
            }
        }
        $this->percent = intdiv($done * 100, $total);
        if ($this->percent === 100) {
            $this->completedAt = new DateTimeImmutable();
        }
    }
}
from datetime import datetime


class DomainError(Exception):
    """Нарушение инварианта агрегата."""


class CourseProgress:
    # course_lessons - список допустимых уроков курса (передаётся при создании).
    def __init__(
        self,
        progress_id: str,
        user_id: str,
        course_id: str,
        course_lessons: list[str],
    ) -> None:
        self._id = progress_id
        self._user_id = user_id
        self._course_id = course_id
        self._lessons = {lid: LessonProgress(lesson_id=lid) for lid in course_lessons}
        self._percent = 0
        self._started_at = datetime.now()
        self._completed_at: datetime | None = None

    @property
    def percent(self) -> int:
        return self._percent

    def complete_lesson(self, lesson_id: str) -> None:
        # Инвариант 2: урок должен существовать в курсе
        lp = self._lessons.get(lesson_id)
        if lp is None:
            raise DomainError(
                f"lesson {lesson_id} does not belong to course {self._course_id}"
            )

        # Инвариант 3: нельзя завершить повторно
        if lp.completed:
            raise DomainError(f"lesson {lesson_id} already completed")

        lp.completed = True
        lp.completed_at = datetime.now()

        # Инвариант 1 и 4: пересчёт процента (всегда 0..100)
        self._recalc_percent()

    def _recalc_percent(self) -> None:
        total = len(self._lessons)
        if total == 0:
            self._percent = 0
            return

        done = sum(1 for lp in self._lessons.values() if lp.completed)

        self._percent = (done * 100) // total

        if self._percent == 100:
            self._completed_at = datetime.now()

Обрати внимание: recalcPercent - приватный метод. Внешний код не может установить произвольный процент. Инвариант защищён на уровне структуры.

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

🚫 Не давай внешнему коду менять внутренности агрегата

Если handler может напрямую выставить progress.percent = 200 или изменить LessonProgress.completed - инварианты ничего не стоят. Все поля агрегата должны быть неэкспортируемыми (lowercase в Go), а изменения - только через методы Aggregate Root.

Правила проектирования агрегатов

Правило 1: агрегаты должны быть маленькими

Плохо: агрегат User содержит всё - профиль, прогресс всех курсов, все результаты квизов, историю платежей.

// Плохо: гигантский агрегат
type User struct {
    id        string
    profile   Profile
    courses   []CourseProgress  // все курсы
    quizzes   []QuizResult      // все квизы
    payments  []Payment         // все платежи
    sessions  []Session         // все сессии
}
<?php
declare(strict_types=1);

namespace App\Learning\Domain;

// Плохо: гигантский агрегат
final class User
{
    /**
     * @param CourseProgress[] $courses
     * @param QuizResult[]     $quizzes
     * @param Payment[]        $payments
     * @param Session[]        $sessions
     */
    public function __construct(
        private readonly string $id,
        private Profile $profile,
        private array $courses,   // все курсы
        private array $quizzes,   // все квизы
        private array $payments,  // все платежи
        private array $sessions,  // все сессии
    ) {}
}
from dataclasses import dataclass


# Плохо: гигантский агрегат
@dataclass
class User:
    _id: str
    _profile: Profile
    _courses: list[CourseProgress]  # все курсы
    _quizzes: list[QuizResult]      # все квизы
    _payments: list[Payment]        # все платежи
    _sessions: list[Session]        # все сессии

Проблема: при любом изменении прогресса загружаются платежи и сессии. Конкурентный доступ блокирует агрегат всего пользователя.

// Хорошо: маленький фокусированный агрегат
type CourseProgress struct {
    id       string
    userID   string   // ссылка по ID, а не вложенный User
    courseID  string   // ссылка по ID, а не вложенный Course
    lessons  map[string]*LessonProgress
    percent  int
}
<?php
declare(strict_types=1);

namespace App\Learning\Domain;

// Хорошо: маленький фокусированный агрегат
final class CourseProgress
{
    /** @param array<string, LessonProgress> $lessons */
    public function __construct(
        private readonly string $id,
        private readonly string $userId,   // ссылка по ID, а не вложенный User
        private readonly string $courseId, // ссылка по ID, а не вложенный Course
        private array $lessons,
        private int $percent,
    ) {}
}
from dataclasses import dataclass


# Хорошо: маленький фокусированный агрегат
@dataclass
class CourseProgress:
    _id: str
    _user_id: str    # ссылка по ID, а не вложенный User
    _course_id: str  # ссылка по ID, а не вложенный Course
    _lessons: dict[str, LessonProgress]
    _percent: int

Правило 2: ссылайся на другие агрегаты по ID

Агрегат CourseProgress не содержит объект User или Course целиком. Он хранит только userID и courseID. Это снижает связанность и упрощает хранение.

Правило 3: один агрегат - одна транзакция

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

ℹ️ Это рекомендация, а не закон - и полезно знать, почему

Правило сформулировали Эванс и Вернон, и оно спасает от двух реальных проблем: раздутых транзакций, блокирующих полтаблицы, и агрегатов, которые невозможно разнести по сервисам. Но это эвристика проектирования, а не свойство математики - вокруг неё до сих пор идёт спор, и реализации, где несколько агрегатов меняются в одной транзакции, существуют (например, когда доменные события обрабатываются синхронно, внутри той же транзакции).

Практический порядок вопросов, если правило начинает мешать:

  1. не выбраны ли границы агрегата неверно? Нужда постоянно менять два агрегата вместе - первый признак того, что это один агрегат, разрезанный пополам. Или наоборот: один раздутый агрегат, из которого пора выделить второй;
  2. точно ли нужна строгая атомарность? Часто «одновременно» в требовании означает «в течение секунды», и тогда событие плюс идемпотентный обработчик решают задачу без общей транзакции;
  3. и только если оба ответа не помогли - да, можно закоммитить два агрегата одной транзакцией, зная цену: они теперь связаны и в одной базе, и в одном сервисе, и разнести их потом будет дорого.

Чего делать точно не стоит - обходить правило через репозиторий, добавляя метод, который меняет два агрегата «одним запросом». Тогда инварианты не проверяет никто.

Обрати внимание, кто в примере ниже загружает агрегат, сохраняет его и публикует событие: это не сам агрегат, а сценарий поверх него. Почему такое разделение обязательно и чем этот сценарий отличается от доменного сервиса - в уроке Domain Service vs Application Service.

// Хорошо: одна транзакция - один агрегат
func (uc *CompleteLessonUseCase) Execute(userID, courseID, lessonID string) error {
    progress, err := uc.progressRepo.Get(userID, courseID)
    if err != nil {
        return err
    }

    if err := progress.CompleteLesson(lessonID); err != nil {
        return err
    }

    // Одна транзакция сохраняет один агрегат
    if err := uc.progressRepo.Save(progress); err != nil {
        return err
    }

    // Для побочных эффектов (обновить статистику курса) - событие.
    // Упрощение: если процесс упадёт между Save и Publish, событие потеряется.
    // Надёжный вариант - outbox, он разобран в уроке Domain Events.
    uc.eventBus.Publish(LessonCompleted{
        UserID:   userID,
        CourseID: courseID,
        LessonID: lessonID,
    })

    return nil
}
<?php
declare(strict_types=1);

namespace App\Learning\Application;

// Хорошо: одна транзакция - один агрегат
final class CompleteLessonUseCase
{
    public function __construct(
        private readonly ProgressRepository $progressRepo,
        private readonly EventBus $eventBus,
    ) {}

    public function execute(string $userId, string $courseId, string $lessonId): void
    {
        $progress = $this->progressRepo->get($userId, $courseId);

        $progress->completeLesson($lessonId);

        // Одна транзакция сохраняет один агрегат
        $this->progressRepo->save($progress);

        // Для побочных эффектов (обновить статистику курса) - событие.
        // Упрощение: если процесс упадёт между save и publish, событие потеряется.
        // Надёжный вариант - outbox, он разобран в уроке Domain Events.
        $this->eventBus->publish(new LessonCompleted(
            userId: $userId,
            courseId: $courseId,
            lessonId: $lessonId,
        ));
    }
}
# Хорошо: одна транзакция - один агрегат
class CompleteLessonUseCase:
    def __init__(self, progress_repo: ProgressRepository, event_bus: EventBus) -> None:
        self._progress_repo = progress_repo
        self._event_bus = event_bus

    def execute(self, user_id: str, course_id: str, lesson_id: str) -> None:
        progress = self._progress_repo.get(user_id, course_id)

        progress.complete_lesson(lesson_id)

        # Одна транзакция сохраняет один агрегат
        self._progress_repo.save(progress)

        # Для побочных эффектов (обновить статистику курса) - событие.
        # Упрощение: если процесс упадёт между save и publish, событие потеряется.
        # Надёжный вариант - outbox, он разобран в уроке Domain Events.
        self._event_bus.publish(
            LessonCompleted(
                user_id=user_id,
                course_id=course_id,
                lesson_id=lesson_id,
            )
        )

⚠️ Почему не два агрегата в одной транзакции?

Два агрегата в одной транзакции означают длинную блокировку, риск deadlock'ов и проблемы с масштабированием. Доменные события позволяют обновлять второй агрегат асинхронно, сохраняя eventual consistency.

Агрегат как граница транзакционной согласованности

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

КтоЗа что отвечает
Агрегаткакие данные обязаны быть согласованы вместе, и какие инварианты проверяются перед сохранением
БД и transaction managerACID: атомарность, изоляция, долговечность записи
Репозиторийчто весь агрегат сохраняется одной транзакцией, а не по частям

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

⚠️ Частая ошибка: «внутри агрегата гарантирован ACID»

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

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

Сериализация - это про пессимистичные блокировки (SELECT ... FOR UPDATE) или уровень изоляции SERIALIZABLE, где транзакция ждёт или откатывается по решению самой БД. Разница между «ждёт» и «получает отказ» практическая: в первом случае код не меняется, во втором нужен retry-цикл - см. уровни изоляции.

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

type CourseProgress struct {
    // ...
    version int // оптимистичная блокировка
}

func (cp *CourseProgress) Version() int { return cp.version }

// В репозитории при сохранении:
// UPDATE course_progress SET ..., version = version + 1
// WHERE id = ? AND version = ?
// Если 0 строк обновлено - ConflictError
<?php
declare(strict_types=1);

namespace App\Learning\Domain;

final class CourseProgress
{
    // ...
    private int $version = 0; // оптимистичная блокировка

    public function version(): int { return $this->version; }
}

// Doctrine поддерживает оптимистичную блокировку нативно:
// #[ORM\Version]
// #[ORM\Column(type: 'integer')]
// private int $version = 0;
// При flush() Doctrine добавит WHERE version = ? и бросит
// OptimisticLockException, если строка изменилась.
class CourseProgress:
    # ...
    _version: int = 0  # оптимистичная блокировка

    @property
    def version(self) -> int:
        return self._version


# В репозитории при сохранении:
# UPDATE course_progress SET ..., version = version + 1
# WHERE id = %s AND version = %s
# Если cursor.rowcount == 0 - ConflictError.
# В SQLAlchemy то же делает __mapper_args__ = {"version_id_col": version}:
# при flush() добавится WHERE version = ? и поднимется StaleDataError.

ℹ️ Оптимистичная vs пессимистичная блокировка

Оптимистичная (version field) - проверяем конфликт при записи. Подходит когда конфликты редки. Пессимистичная (SELECT FOR UPDATE) - блокируем строку при чтении. Подходит когда конфликты часты. Для большинства web-приложений оптимистичная блокировка - лучший выбор.

Мини-задание

  • Спроектируй агрегат QuizAttempt для BackendStart: пользователь отвечает на вопросы квиза, нельзя ответить дважды на один вопрос, результат пересчитывается автоматически
  • Определи 3 инварианта для этого агрегата и реализуй их в методах
  • Убедись, что все поля агрегата неэкспортируемые (lowercase)
  • Добавь поле version для оптимистичной блокировки
  • Проверь: не ссылается ли агрегат на другие агрегаты по значению (должен по ID)

Зарегистрируйтесь бесплатно, чтобы пройти квиз, решить задание с автопроверкой, вести прогресс.