Repositories в DDD: что они должны делать

Repositories в DDD: что они должны делать

Репозиторий - не «слой над БД» и не свалка GetByWhatever. Разберём, что он должен делать, а что - точно нет.

Проблема: репозиторий превращается в свалку

Проект растёт, и в CourseRepository появляются методы: GetByID, GetBySlug, GetByAuthor, GetPublishedByCategory, GetWithLessonsAndQuizzes, SearchByTitleAndDifficulty, GetTopRated... Двадцать методов, каждый с уникальным SQL-запросом. Тесты - кошмар. Новый разработчик не знает, какой метод использовать.

Репозиторий в DDD - это не query builder и не DAO. Это коллекция агрегатов с минимальным интерфейсом.

⚠️ «Загружает агрегат целиком» - и что делать, когда целиком дорого

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

Соблазн решить это методом AddItem(orderID, item) в репозитории. Он работает и разрушает агрегат: инварианты, которые проверял агрегат (лимит суммы, максимум позиций), теперь не проверяются вовсе - никто не собрал состояние целиком.

Правильный порядок вопросов другой:

  1. Не велика ли граница агрегата? Дорогая загрузка - это обычно не проблема репозитория, а сигнал, что в один агрегат сложили то, что не обязано меняться одной транзакцией. «Заказ со всеми позициями» и «позиция как отдельный агрегат со ссылкой на заказ» - разные модели, и вторая часто честнее;
  2. не путаем ли мы чтение с изменением? Показать список из десяти тысяч позиций через агрегат не нужно вовсе: для этого есть отдельный путь чтения (CQRS-lite ниже в этом уроке) - он читает проекцию и никаких инвариантов не поддерживает, потому что ничего не меняет;
  3. и только если оба ответа «всё в порядке» - оптимизировать загрузку (ленивые коллекции, частичная материализация), помня, что каждая такая оптимизация ослабляет проверку инвариантов.

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

Repository как коллекция: use case вызывает интерфейс Get/Save/Delete, реализации - GORM в проде, in-memory map в тестах

Repository = коллекция агрегатов

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

// domain/repository.go - интерфейс в пакете domain
// Репозиторий знает только про агрегаты, ничего про БД.
type CourseProgressRepository interface {
    // Get загружает агрегат целиком (со всеми внутренними объектами)
    Get(ctx context.Context, userID, courseID string) (*CourseProgress, error)

    // Save сохраняет агрегат целиком (insert или update)
    Save(ctx context.Context, progress *CourseProgress) error

    // Delete удаляет агрегат
    Delete(ctx context.Context, userID, courseID string) error
}
<?php
declare(strict_types=1);

namespace App\Learning\Domain;

// Интерфейс в namespace Domain. Репозиторий знает только про агрегаты, ничего про БД.
// final НЕ ставится - это интерфейс.
interface CourseProgressRepository
{
    // get загружает агрегат целиком (со всеми внутренними объектами)
    public function get(string $userId, string $courseId): CourseProgress;

    // save сохраняет агрегат целиком (insert или update)
    public function save(CourseProgress $progress): void;

    // delete удаляет агрегат
    public function delete(string $userId, string $courseId): void;
}
# domain/repository.py - интерфейс в пакете domain.
# Репозиторий знает только про агрегаты, ничего про БД.
# Protocol - структурная типизация, как интерфейс в Go: реализация
# не наследуется от него, достаточно совпадения методов.
from typing import Protocol


class CourseProgressRepository(Protocol):
    def get(self, user_id: str, course_id: str) -> CourseProgress:
        """Загружает агрегат целиком (со всеми внутренними объектами);
        если агрегата нет - поднимает ProgressNotFoundError.
        """

    def save(self, progress: CourseProgress) -> None:
        """Сохраняет агрегат целиком (insert или update)."""

    def delete(self, user_id: str, course_id: str) -> None:
        """Удаляет агрегат."""

Три метода. Не тридцать. Репозиторий работает с агрегатом как с единым целым - загружает все его внутренние объекты (LessonProgress) и сохраняет всё вместе.

Отсюда и требование к Get: он обязан отдать собранный агрегат, а не строку таблицы. Значит, объекты-значения внутри придётся восстанавливать из колонок через их конструкторы, а не присваивать поля напрямую - иначе невалидное состояние попадёт в домен прямо из базы. Устройство таких типов - в уроке Entity и Value Object.

ℹ️ Репозиторий возвращает агрегаты, не строки из базы

Метод Get возвращает полностью собранный агрегат CourseProgress со всеми LessonProgress внутри. Не DTO, не строку из таблицы, не плоскую структуру. Агрегат готов к вызову бизнес-методов сразу после загрузки.

Интерфейс в домене, реализация в инфраструктуре

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

// domain/repository.go - порт (интерфейс)
type CourseProgressRepository interface {
    Get(ctx context.Context, userID, courseID string) (*CourseProgress, error)
    Save(ctx context.Context, progress *CourseProgress) error
    Delete(ctx context.Context, userID, courseID string) error
}
// Domain/CourseProgressRepository.php - порт (интерфейс)
namespace App\Learning\Domain;

interface CourseProgressRepository
{
    public function get(string $userId, string $courseId): CourseProgress;
    public function save(CourseProgress $progress): void;
    public function delete(string $userId, string $courseId): void;
}
# domain/repository.py - порт (интерфейс)
from typing import Protocol


class CourseProgressRepository(Protocol):
    def get(self, user_id: str, course_id: str) -> CourseProgress: ...
    def save(self, progress: CourseProgress) -> None: ...
    def delete(self, user_id: str, course_id: str) -> None: ...
// infrastructure/postgres/progress_repo.go - адаптер (реализация)
type ProgressRepo struct {
    db *gorm.DB
}

func NewProgressRepo(db *gorm.DB) *ProgressRepo {
    return &ProgressRepo{db: db}
}

func (r *ProgressRepo) Get(ctx context.Context, userID, courseID string) (*domain.CourseProgress, error) {
    var model progressModel
    err := r.db.WithContext(ctx).
        Where("user_id = ? AND course_id = ?", userID, courseID).
        First(&model).Error
    if err != nil {
        if errors.Is(err, gorm.ErrRecordNotFound) {
            return nil, domain.ErrProgressNotFound
        }
        return nil, fmt.Errorf("query progress: %w", err)
    }

    var lessonModels []lessonProgressModel
    err = r.db.WithContext(ctx).
        Where("progress_id = ?", model.ID).
        Find(&lessonModels).Error
    if err != nil {
        return nil, fmt.Errorf("query lessons: %w", err)
    }

    // Собираем агрегат из моделей БД
    return toDomainProgress(model, lessonModels), nil
}

func (r *ProgressRepo) Save(ctx context.Context, progress *domain.CourseProgress) error {
    return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
        model := toProgressModel(progress)
        if err := tx.Save(&model).Error; err != nil {
            return err
        }

        // Сохраняем внутренние объекты агрегата
        for _, lp := range toLessonModels(progress) {
            if err := tx.Save(&lp).Error; err != nil {
                return err
            }
        }
        return nil
    })
}
<?php
declare(strict_types=1);

// Infrastructure/Doctrine/DoctrineProgressRepository.php - адаптер (реализация)
namespace App\Learning\Infrastructure\Doctrine;

use App\Learning\Domain\CourseProgress;
use App\Learning\Domain\CourseProgressRepository;
use App\Learning\Domain\ProgressNotFoundException;
use Doctrine\ORM\EntityManagerInterface;

final class DoctrineProgressRepository implements CourseProgressRepository
{
    public function __construct(
        private readonly EntityManagerInterface $em,
    ) {}

    public function get(string $userId, string $courseId): CourseProgress
    {
        $model = $this->em->getRepository(ProgressModel::class)
 ->findOneBy(['userId' => $userId, 'courseId' => $courseId]);

        if ($model === null) {
            throw new ProgressNotFoundException();
        }

        // Doctrine подгрузит дочерние LessonProgressModel по association
        // Собираем агрегат из моделей БД
        return $this->toDomain($model);
    }

    public function save(CourseProgress $progress): void
    {
        // EntityManager управляет транзакцией; flush - атомарно
        $model = $this->toModel($progress);
        $this->em->persist($model);
        // Сохраняем внутренние объекты агрегата
        foreach ($this->toLessonModels($progress) as $lp) {
            $this->em->persist($lp);
        }
        $this->em->flush();
    }

    public function delete(string $userId, string $courseId): void
    {
        // DQL DELETE не каскадирует на дочерние сущности. Строки lesson_progress
        // удаляет сама база: FOREIGN KEY (progress_id) REFERENCES course_progress(id)
        // ON DELETE CASCADE. Без такого ключа удалился бы только корень агрегата.
        $this->em->createQuery(
            'DELETE FROM ' . ProgressModel::class . ' p
             WHERE p.userId = :u AND p.courseId = :c'
        )->setParameters(['u' => $userId, 'c' => $courseId])->execute();
    }
}
# infrastructure/postgres/progress_repo.py - адаптер (реализация).
# Вместо ORM - psycopg напрямую; в SQLAlchemy та же схема: модели таблиц
# отдельно, маппинг в доменный агрегат - руками.
import psycopg
from psycopg.rows import dict_row

from app.learning import domain


class ProgressRepo:
    def __init__(self, conn: psycopg.Connection) -> None:
        self._conn = conn

    def get(self, user_id: str, course_id: str) -> domain.CourseProgress:
        with self._conn.cursor(row_factory=dict_row) as cur:
            cur.execute(
                "SELECT * FROM course_progress WHERE user_id = %s AND course_id = %s",
                (user_id, course_id),
            )
            row = cur.fetchone()
            if row is None:
                raise domain.ProgressNotFoundError()

            cur.execute(
                "SELECT * FROM lesson_progress WHERE progress_id = %s",
                (row["id"],),
            )
            lesson_rows = cur.fetchall()

        # Собираем агрегат из строк БД
        return to_domain_progress(row, lesson_rows)

    def save(self, progress: domain.CourseProgress) -> None:
        # Одна транзакция на весь агрегат: контекстный менеджер делает
        # commit на выходе и rollback при исключении
        with self._conn.transaction():
            model = to_progress_model(progress)
            self._conn.execute(
                "INSERT INTO course_progress (id, user_id, course_id, percent) "
                "VALUES (%(id)s, %(user_id)s, %(course_id)s, %(percent)s) "
                "ON CONFLICT (id) DO UPDATE SET percent = EXCLUDED.percent",
                model,
            )

            # Сохраняем внутренние объекты агрегата
            for lp in to_lesson_models(progress):
                self._conn.execute(
                    "INSERT INTO lesson_progress (progress_id, lesson_id, completed) "
                    "VALUES (%(progress_id)s, %(lesson_id)s, %(completed)s) "
                    "ON CONFLICT (progress_id, lesson_id) "
                    "DO UPDATE SET completed = EXCLUDED.completed",
                    lp,
                )

    def delete(self, user_id: str, course_id: str) -> None:
        # Строки lesson_progress удаляются каскадом, это задано в схеме:
        # FOREIGN KEY (progress_id) REFERENCES course_progress(id) ON DELETE CASCADE
        self._conn.execute(
            "DELETE FROM course_progress WHERE user_id = %s AND course_id = %s",
            (user_id, course_id),
        )

Обрати внимание: реализация использует GORM-модели (progressModel, lessonProgressModel) и маппит их в доменные объекты. Домен не знает о GORM.

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

Repository vs DAO: в чём разница

АспектRepository (DDD)DAO
Работает сАгрегатамиТаблицами
Единица операцииАгрегат целикомОдна строка
Интерфейс3-5 методовДесятки методов
Запросы для чтенияОтдельный Read ModelВ том же классе
Знает о БДНет (интерфейс в домене)Да
МаппингМодель БД -> агрегатСтрока = объект

DAO (Data Access Object) привязан к таблице и предоставляет CRUD для строк. Repository привязан к агрегату и предоставляет операции для бизнес-объектов.

Что принадлежит репозиторию, а что нет

Принадлежит - операции с агрегатами:

  • Get(id) - загрузить агрегат
  • Save(aggregate) - сохранить (insert + update)
  • Delete(id) - удалить агрегат
  • NextID() - сгенерировать идентификатор (если нужно)

Не принадлежит - сложные выборки для UI:

  • Список курсов с пагинацией и фильтрами
  • Поиск по названию
  • Статистика и отчёты
  • JOIN'ы через несколько агрегатов

Для сложных запросов на чтение используй отдельный слой.

CQRS-lite: отдельные Read Models

CQRS (Command Query Responsibility Segregation) в лёгкой форме: команды (изменение) идут через агрегат и репозиторий, запросы (чтение для UI) идут через отдельный Read Model.

// domain/repository.go - для команд (write)
type CourseProgressRepository interface {
    Get(ctx context.Context, userID, courseID string) (*CourseProgress, error)
    Save(ctx context.Context, progress *CourseProgress) error
}

// application/query.go - для запросов (read)
type ProgressReadModel interface {
    // Список прогресса пользователя по всем курсам - для страницы "Мои курсы"
    ListByUser(ctx context.Context, userID string, page, size int) ([]ProgressSummary, error)

    // Прогресс конкретного курса для отображения - не агрегат, а DTO
    GetCourseDashboard(ctx context.Context, userID, courseID string) (*CourseDashboard, error)
}

// ProgressSummary - плоская структура для UI, не агрегат
type ProgressSummary struct {
    CourseID    string
    CourseTitle string
    Percent     int
    TotalLessons int
    CompletedLessons int
}
<?php
declare(strict_types=1);

// Domain/CourseProgressRepository.php - для команд (write)
namespace App\Learning\Domain;

interface CourseProgressRepository
{
    public function get(string $userId, string $courseId): CourseProgress;
    public function save(CourseProgress $progress): void;
}

// Application/Query/ProgressReadModel.php - для запросов (read)
namespace App\Learning\Application\Query;

interface ProgressReadModel
{
    // Список прогресса пользователя по всем курсам - для страницы «Мои курсы»
    /** @return ProgressSummary[] */
    public function listByUser(string $userId, int $page, int $size): array;

    // Прогресс конкретного курса для отображения - не агрегат, а DTO
    public function getCourseDashboard(string $userId, string $courseId): CourseDashboard;
}

// ProgressSummary - плоский DTO для UI, не агрегат
final readonly class ProgressSummary
{
    public function __construct(
        public string $courseId,
        public string $courseTitle,
        public int $percent,
        public int $totalLessons,
        public int $completedLessons,
    ) {}
}
from dataclasses import dataclass
from typing import Protocol


# domain/repository.py - для команд (write)
class CourseProgressRepository(Protocol):
    def get(self, user_id: str, course_id: str) -> CourseProgress: ...
    def save(self, progress: CourseProgress) -> None: ...


@dataclass(frozen=True)
class ProgressSummary:
    """Плоская структура для UI, не агрегат."""

    course_id: str
    course_title: str
    percent: int
    total_lessons: int
    completed_lessons: int


# application/query.py - для запросов (read)
class ProgressReadModel(Protocol):
    # Список прогресса пользователя по всем курсам - для страницы «Мои курсы»
    def list_by_user(self, user_id: str, page: int, size: int) -> list[ProgressSummary]: ...

    # Прогресс конкретного курса для отображения - не агрегат, а DTO
    def get_course_dashboard(self, user_id: str, course_id: str) -> CourseDashboard: ...

Read Model может использовать SQL напрямую, JOIN'ить таблицы, применять фильтры - ему не нужно собирать агрегат. Это просто данные для отображения.

⚠️ Read Model - не повод для хаоса

CQRS-lite не значит «делай что хочешь на стороне чтения». Read Model всё равно должен быть в отдельном интерфейсе, тестироваться и не содержать бизнес-логики. Он просто читает данные, не меняет их.

Объект фильтра: фильтры без взрыва методов

Если Read Model нуждается в комбинациях фильтров, вместо метода на каждую комбинацию передавай один объект критериев. Это упрощённая форма. Полноценный паттерн Specification - объект-предикат с методом IsSatisfiedBy и операциями And/Or; его используют, когда одно правило нужно и для проверки объекта, и для запроса.

// Объект критериев для фильтрации курсов
type CourseFilter struct {
    Difficulty *string
    TrackID    *string
    Search     *string
    Page       int
    Size       int
}

type CourseReadModel interface {
    List(ctx context.Context, filter CourseFilter) ([]CourseSummary, int, error)
}
<?php
declare(strict_types=1);

namespace App\Learning\Application\Query;

// Объект критериев для фильтрации курсов
final readonly class CourseFilter
{
    public function __construct(
        public ?string $difficulty = null,
        public ?string $trackId = null,
        public ?string $search = null,
        public int $page = 1,
        public int $size = 20,
    ) {}
}

interface CourseReadModel
{
    /** @return array{items: CourseSummary[], total: int} */
    public function list(CourseFilter $filter): array;
}
from dataclasses import dataclass
from typing import Protocol


# Объект критериев для фильтрации курсов
@dataclass(frozen=True)
class CourseFilter:
    difficulty: str | None = None
    track_id: str | None = None
    search: str | None = None
    page: int = 1
    size: int = 20


class CourseReadModel(Protocol):
    # Возвращает страницу результатов и общее число записей
    def list(self, course_filter: CourseFilter) -> tuple[list[CourseSummary], int]: ...

Один метод list с параметрами фильтрации вместо getByDifficulty, getByTrack, getByDifficultyAndTrack, searchByTitle...

In-memory реализация для тестов

Репозиторий - интерфейс, значит можно подставить реализацию для тестов без БД:

// domain/progress.go - глубокая копия агрегата: и корня, и уроков внутри.
// Обычное присваивание *cp тут не годится: копия структуры делит
// с оригиналом ту же карту lessons и те же *LessonProgress.
func (cp *CourseProgress) Clone() *CourseProgress {
    c := *cp
    c.lessons = make(map[string]*LessonProgress, len(cp.lessons))
    for k, lp := range cp.lessons {
        l := *lp
        c.lessons[k] = &l
    }
    return &c
}

// infrastructure/memory/progress_repo.go
type InMemoryProgressRepo struct {
    mu sync.RWMutex
    // Глубокие копии, а не общие объекты.
    //
    // Если хранить и отдавать тот же *domain.CourseProgress, репозиторий
    // отдавал бы объект, что лежит внутри: агрегат мутируется по указателю,
    // поэтому изменение «сохранялось» бы само, без вызова Save. Тест на таком
    // фейке зелёный, а в проде тот же код теряет изменения - фейк прятал
    // бы ошибку вместо того, чтобы её показать. Копировать структуру
    // присваиванием тоже мало: внутри агрегата map с указателями.
    data map[string]*domain.CourseProgress // ключ: "userID:courseID"
}

func NewInMemoryProgressRepo() *InMemoryProgressRepo {
    return &InMemoryProgressRepo{
        data: make(map[string]*domain.CourseProgress),
    }
}

func (r *InMemoryProgressRepo) Get(ctx context.Context, userID, courseID string) (*domain.CourseProgress, error) {
    r.mu.RLock()
    defer r.mu.RUnlock()

    key := userID + ":" + courseID
    p, ok := r.data[key]
    if !ok {
        return nil, domain.ErrProgressNotFound
    }
    // Отдаём глубокую копию: у вызывающего свой объект.
    return p.Clone(), nil
}

func (r *InMemoryProgressRepo) Save(ctx context.Context, progress *domain.CourseProgress) error {
    r.mu.Lock()
    defer r.mu.Unlock()

    key := progress.UserID() + ":" + progress.CourseID()
    r.data[key] = progress.Clone()
    return nil
}

func (r *InMemoryProgressRepo) Delete(ctx context.Context, userID, courseID string) error {
    r.mu.Lock()
    defer r.mu.Unlock()

    key := userID + ":" + courseID
    delete(r.data, key)
    return nil
}
<?php
declare(strict_types=1);

// Infrastructure/InMemory/InMemoryProgressRepository.php - для тестов
namespace App\Learning\Infrastructure\InMemory;

use App\Learning\Domain\CourseProgress;
use App\Learning\Domain\CourseProgressRepository;
use App\Learning\Domain\ProgressNotFoundException;

final class InMemoryProgressRepository implements CourseProgressRepository
{
    /**
     * Храним копии. Копия должна быть глубокой, поэтому в CourseProgress есть:
     *
     *     public function __clone()
     *     {
     *         foreach ($this->lessons as $k => $lp) {
     *             $this->lessons[$k] = clone $lp;
     *         }
     *     }
     *
     * @var array<string, CourseProgress>
     */
    private array $data = [];

    public function get(string $userId, string $courseId): CourseProgress
    {
        $key = $userId . ':' . $courseId;
        if (!isset($this->data[$key])) {
            throw new ProgressNotFoundException();
        }
        // Отдаём копию: у вызывающего свой объект.
        return clone $this->data[$key];
    }

    public function save(CourseProgress $progress): void
    {
        // Объекты в PHP передаются по дескриптору: без clone хранилище
        // и вызывающий делили бы один объект, и изменение «сохранялось»
        // бы само, без вызова save.
        $key = $progress->userId() . ':' . $progress->courseId();
        $this->data[$key] = clone $progress;
    }

    public function delete(string $userId, string $courseId): void
    {
        unset($this->data[$userId . ':' . $courseId]);
    }
}
# infrastructure/memory/progress_repo.py
import copy
import threading

from app.learning import domain


class InMemoryProgressRepo:
    def __init__(self) -> None:
        # Lock - аналог sync.RWMutex: use case могут гонять из нескольких потоков
        self._lock = threading.Lock()
        # Копии, а не ссылки.
        #
        # Все объекты здесь передаются по ссылке, поэтому если хранить
        # агрегат как есть, репозиторий отдавал бы тот же объект, что лежит
        # внутри: агрегат мутируется через методы, и изменение «сохранялось»
        # бы само, без вызова save. Тест на таком фейке зелёный, а в проде
        # тот же код теряет изменения - фейк прятал бы ошибку вместо того,
        # чтобы её показать. Поэтому deepcopy и на входе, и на выходе.
        self._data: dict[str, domain.CourseProgress] = {}  # ключ: "user_id:course_id"

    def get(self, user_id: str, course_id: str) -> domain.CourseProgress:
        with self._lock:
            key = f"{user_id}:{course_id}"
            p = self._data.get(key)
            if p is None:
                raise domain.ProgressNotFoundError()
            # Отдаём копию: у вызывающего свой объект.
            return copy.deepcopy(p)

    def save(self, progress: domain.CourseProgress) -> None:
        with self._lock:
            key = f"{progress.user_id}:{progress.course_id}"
            self._data[key] = copy.deepcopy(progress)

    def delete(self, user_id: str, course_id: str) -> None:
        with self._lock:
            self._data.pop(f"{user_id}:{course_id}", None)

Теперь use case тестируется без Docker, без миграций, без PostgreSQL:

// fakeEventBus записывает опубликованные события вместо отправки.
type fakeEventBus struct {
    events []domain.DomainEvent
}

func (b *fakeEventBus) Publish(_ context.Context, event domain.DomainEvent) error {
    b.events = append(b.events, event)
    return nil
}

func TestCompleteLessonUseCase(t *testing.T) {
    repo := memory.NewInMemoryProgressRepo()
    eventBus := &fakeEventBus{}

    // Подготовка: создать прогресс с уроками
    progress := domain.NewCourseProgress("p1", "u1", "c1", []string{"lesson-1", "lesson-2"})
    _ = repo.Save(context.Background(), progress)

    uc := NewCompleteLessonUseCase(repo, eventBus)
    err := uc.Execute(context.Background(), "u1", "c1", "lesson-1")

    require.NoError(t, err)

    // Проверяем, что агрегат обновился В ХРАНИЛИЩЕ.
    //
    // Это работает только потому, что репозиторий хранит копии: иначе тест
    // читал бы тот же объект, который мутировал use case, и прошёл бы даже
    // если убрать из use case вызов Save. См. врезку под тестом.
    updated, _ := repo.Get(context.Background(), "u1", "c1")
    assert.Equal(t, 50, updated.Percent())
    assert.Len(t, eventBus.events, 1)
}
<?php
declare(strict_types=1);

namespace App\Tests\Learning\Application;

use App\Learning\Application\CompleteLessonUseCase;
use App\Learning\Domain\CourseProgress;
use App\Learning\Infrastructure\InMemory\InMemoryProgressRepository;
use PHPUnit\Framework\TestCase;

final class CompleteLessonUseCaseTest extends TestCase
{
    public function testCompletesLessonAndUpdatesPercent(): void
    {
        $repo = new InMemoryProgressRepository();
        $eventBus = new InMemoryEventBus();

        // Подготовка: создать прогресс с уроками
        $progress = CourseProgress::start('p1', 'u1', 'c1', ['lesson-1', 'lesson-2']);
        $repo->save($progress);

        $useCase = new CompleteLessonUseCase($repo, $eventBus);
        $useCase->execute('u1', 'c1', 'lesson-1');

        // Проверяем, что агрегат обновился
        $updated = $repo->get('u1', 'c1');
        self::assertSame(50, $updated->percent());
        self::assertTrue($eventBus->wasPublished());
    }
}
# tests/test_complete_lesson.py - pytest, без БД
from app.learning import domain
from app.learning.application import CompleteLessonUseCase
from app.learning.infrastructure.memory import InMemoryProgressRepo


class FakeEventBus:
    """Записывает опубликованные события вместо отправки."""

    def __init__(self) -> None:
        self.events: list[domain.Event] = []

    def publish(self, *events: domain.Event) -> None:
        self.events.extend(events)


def test_complete_lesson_use_case() -> None:
    repo = InMemoryProgressRepo()
    event_bus = FakeEventBus()

    # Подготовка: создать прогресс с уроками
    progress = domain.CourseProgress("p1", "u1", "c1", ["lesson-1", "lesson-2"])
    repo.save(progress)

    uc = CompleteLessonUseCase(repo, event_bus)
    uc.execute("u1", "c1", "lesson-1")  # доменная ошибка уронила бы тест исключением

    # Проверяем, что агрегат обновился В ХРАНИЛИЩЕ.
    #
    # Это работает только потому, что репозиторий хранит копии: иначе тест
    # читал бы тот же объект, который мутировал use case, и прошёл бы даже
    # если убрать из use case вызов save. См. врезку под тестом.
    updated = repo.get("u1", "c1")
    assert updated.percent == 50
    assert len(event_bus.events) == 1

🚫 Не тестируй бизнес-логику через HTTP или БД

Если для проверки инварианта CompleteLesson нужно поднять PostgreSQL и отправить HTTP-запрос - тест хрупкий и медленный. In-memory репозиторий позволяет тестировать домен изолированно за миллисекунды.

⚠️ In-memory репозиторий обязан копировать данные

Тонкость, которая делает такой фейк либо полезным, либо вредным.

Если хранить map[string]*domain.CourseProgress и возвращать тот же указатель, то граница между «объектом в памяти» и «сохранённым состоянием» исчезает. Агрегат мутируется через методы по указателю, значит изменение попадает в хранилище само, без вызова Save.

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

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

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

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

  • Определи интерфейс QuizResultRepository в пакете domain (Get, Save, Delete)
  • Реализуй in-memory версию для тестов
  • Создай QuizReadModel с методом ListByUser для страницы «Мои результаты»
  • Проверь свои репозитории: не стали ли они DAO с десятком GetBy... методов
  • Напиши тест use case с in-memory репозиторием (без БД)

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