Репозитории и интерфейсы: где им жить

Репозитории и интерфейсы: где им жить

Repository - это порт для сохранения и получения данных. В терминах гексагональной архитектуры репозиторий является вторичным портом: бизнес-логика говорит «мне нужно сохранить задачу», а конкретная реализация (PostgreSQL, MongoDB, in-memory map) - это адаптер, который этот порт реализует. См. также Repository в DDD.

Главный вопрос: где объявить интерфейс, а где положить реализацию?

Правило: интерфейс рядом с потребителем

Где жить интерфейсу: рядом с реализацией плохо, рядом с потребителем хорошо

В Go принято объявлять интерфейс там, где он используется, а не там, где реализуется. В этом треке интерфейс репозитория - порт слоя приложения, он живёт в usecase/ports/ (та же раскладка, что с первого урока), а реализация - в adapters/.

ℹ️ А в DDD интерфейс лежит в domain

В треке DDD Lite интерфейс репозитория объявлен в пакете domain. Это не противоречие, а другая точка зрения на ту же границу: в DDD репозиторий описывают как часть языка домена («коллекция агрегатов»), в гексагоне - как порт, который нужен сценарию. Важно одно правило, общее для обоих вариантов: интерфейс лежит внутри (в domain или в usecase/ports), реализация - снаружи, в адаптере. Выбери одно место на проект и держись его.

internal/
  domain/
    task.go              # entity Task
    errors.go            # доменные ошибки
  usecase/
    ports/
      task_repo.go       # интерфейс TaskRepository
      notifier.go        # интерфейс TaskNotifier
    create_task.go       # use-case
    complete_task.go
  adapters/
    postgres/
      task_repo.go       # PostgresTaskRepository
    inmemory/
      task_repo.go       # InMemoryTaskRepository (для тестов)
    http/
      task_handler.go    # HTTP handler

ℹ️ Почему не в adapters/

Если интерфейс лежит рядом с реализацией (в adapters/postgres/), то use-case вынужден импортировать пакет адаптера. Это разрушает всю идею: домен начинает зависеть от инфраструктуры. Интерфейс в usecase/ports/ - и зависимость направлена внутрь.

Интерфейс TaskRepository

Сигнатуры принимают и возвращают доменные типы. Никаких *sql.Row, pgx.Rows или bson.M в контракте порта. Если внутри домена вместо голых строк живут объекты-значения (Email, Slug, Money), то восстанавливать их из колонок при чтении - тоже работа адаптера: как такие типы устроены и почему их нельзя собрать в обход конструктора, в уроке Entity и Value Object.

// internal/usecase/ports/task_repo.go
package ports

import (
    "context"

    "myapp/internal/domain"
)

type TaskRepository interface {
    Create(ctx context.Context, task domain.Task) error
    GetByID(ctx context.Context, id string) (domain.Task, error)
    ListByUser(ctx context.Context, userID string) ([]domain.Task, error)
    Update(ctx context.Context, task domain.Task) error
    Delete(ctx context.Context, id string) error
}
<?php
// src/Application/Port/TaskRepositoryPort.php
declare(strict_types=1);

namespace App\Application\Port;

use App\Domain\Task;

interface TaskRepositoryPort
{
    public function create(Task $task): void;

    public function getById(string $id): Task;

    /** @return list<Task> */
    public function listByUser(string $userId): array;

    public function update(Task $task): void;

    public function delete(string $id): void;
}
# myapp/usecase/ports/task_repo.py
from typing import Protocol

from myapp import domain


class TaskRepository(Protocol):
    # Контекст с отменой и дедлайном, который в Go идёт первым аргументом,
    # здесь не передаём: в синхронном стеке его нет, в asyncio это async def
    # и таймаут снаружи. Контракт от этого не меняется.
    def create(self, task: domain.Task) -> None: ...

    def get_by_id(self, task_id: str) -> domain.Task: ...

    def list_by_user(self, user_id: str) -> list[domain.Task]: ...

    def update(self, task: domain.Task) -> None: ...

    def delete(self, task_id: str) -> None: ...

Обрати внимание:

  • Каждый метод принимает context.Context первым аргументом - это стандарт Go: через контекст приходят отмена и дедлайн запроса (и служебные значения вроде trace ID), и драйвер базы прервёт SQL-запрос, если клиент уже ушёл.
  • Возвращаются domain.Task, а не *TaskRow или map[string]interface{}.
  • Ошибки - обычный error. Доменные ошибки (например, domain.ErrTaskNotFound) определяются в пакете domain.

Реализация: PostgresTaskRepository / DoctrineTaskRepository

Адаптер реализует интерфейс и работает с конкретной базой. Внутри - SQL, pgx, Doctrine, что угодно. Наружу - только доменные типы. Когда имена колонок расходятся с именами полей домена или в таблице появляется updated_at, которого в домене нет, внутри адаптера заводят отдельную структуру строки и функции перевода - как это выглядит, в уроке DTO и маппинг.

// internal/adapters/postgres/task_repo.go
package postgres

import (
    "context"
    "errors"
    "fmt"
    "time"

    "github.com/jackc/pgx/v5"
    "github.com/jackc/pgx/v5/pgxpool"

    "myapp/internal/domain"
)

type TaskRepo struct {
    pool *pgxpool.Pool
}

func NewTaskRepo(pool *pgxpool.Pool) *TaskRepo {
    return &TaskRepo{pool: pool}
}

func (r *TaskRepo) Create(ctx context.Context, task domain.Task) error {
    _, err := r.pool.Exec(ctx,
        `INSERT INTO tasks (id, user_id, title, completed)
         VALUES ($1, $2, $3, $4)`,
        task.ID(), task.UserID(), task.Title(), task.Completed(),
    )
    return err
}

// GetByID читает строку в локальные переменные и собирает сущность
// через domain.TaskFromStorage.
//
// Сканировать сразу в поля сущности нельзя: они закрыты - и это не помеха,
// а смысл. Сборка через функцию домена - единственное место, где строка
// БД превращается в объект, и там же проверяются структурные инварианты.
func (r *TaskRepo) GetByID(ctx context.Context, id string) (domain.Task, error) {
    var (
        taskID, userID, title string
        completed             bool
        createdAt             time.Time
    )
    err := r.pool.QueryRow(ctx,
        `SELECT id, user_id, title, completed, created_at
         FROM tasks WHERE id = $1`, id,
    ).Scan(&taskID, &userID, &title, &completed, &createdAt)

    if errors.Is(err, pgx.ErrNoRows) {
        return domain.Task{}, domain.ErrTaskNotFound
    }
    if err != nil {
        return domain.Task{}, err
    }

    return domain.TaskFromStorage(taskID, userID, title, "", completed, createdAt, nil)
}

func (r *TaskRepo) ListByUser(ctx context.Context, userID string) ([]domain.Task, error) {
    rows, err := r.pool.Query(ctx,
        `SELECT id, user_id, title, completed, created_at
         FROM tasks WHERE user_id = $1 ORDER BY created_at DESC`, userID,
    )
    if err != nil {
        return nil, err
    }
    defer rows.Close()

    var tasks []domain.Task
    for rows.Next() {
        var (
            taskID, uID, title string
            completed          bool
            createdAt          time.Time
        )
        if err := rows.Scan(&taskID, &uID, &title, &completed, &createdAt); err != nil {
            return nil, err
        }
        t, err := domain.TaskFromStorage(taskID, uID, title, "", completed, createdAt, nil)
        if err != nil {
            // Одна повреждённая строка не должна выглядеть как пустой список:
            // это ошибка данных, и она обязана быть видна.
            return nil, fmt.Errorf("task %s: %w", taskID, err)
        }
        tasks = append(tasks, t)
    }
    return tasks, rows.Err()
}

func (r *TaskRepo) Update(ctx context.Context, task domain.Task) error {
    tag, err := r.pool.Exec(ctx,
        `UPDATE tasks SET title = $2, completed = $3 WHERE id = $1`,
        task.ID(), task.Title(), task.Completed(),
    )
    if err != nil {
        return err
    }
    if tag.RowsAffected() == 0 {
        return domain.ErrTaskNotFound
    }
    return nil
}

func (r *TaskRepo) Delete(ctx context.Context, id string) error {
    _, err := r.pool.Exec(ctx, `DELETE FROM tasks WHERE id = $1`, id)
    return err
}
<?php
// src/Infrastructure/Persistence/Doctrine/DoctrineTaskRepository.php
declare(strict_types=1);

namespace App\Infrastructure\Persistence\Doctrine;

use App\Application\Port\TaskRepositoryPort;
use App\Domain\Task;
use App\Domain\TaskError;
use DateTimeImmutable;
use Doctrine\DBAL\Connection;

final class DoctrineTaskRepository implements TaskRepositoryPort
{
    public function __construct(
        private readonly Connection $connection,
    ) {}

    public function create(Task $task): void
    {
        $this->connection->insert('tasks', [
            'id' => $task->id(),
            'user_id' => $task->userId(),
            'title' => $task->title(),
            'completed' => $task->isCompleted() ? 1 : 0,
        ]);
    }

    public function getById(string $id): Task
    {
        $row = $this->connection->fetchAssociative(
            'SELECT id, user_id, title, completed, created_at FROM tasks WHERE id = :id',
            ['id' => $id],
        );
        if ($row === false) {
            throw TaskError::notFound();
        }
        return $this->hydrate($row);
    }

    /** @return list<Task> */
    public function listByUser(string $userId): array
    {
        $rows = $this->connection->fetchAllAssociative(
            'SELECT id, user_id, title, completed, created_at FROM tasks WHERE user_id = :uid ORDER BY created_at DESC',
            ['uid' => $userId],
        );
        return array_map(fn (array $row) => $this->hydrate($row), $rows);
    }

    public function update(Task $task): void
    {
        $this->connection->update(
            'tasks',
            ['title' => $task->title(), 'completed' => $task->isCompleted() ? 1 : 0],
            ['id' => $task->id()],
        );
    }

    public function delete(string $id): void
    {
        $this->connection->delete('tasks', ['id' => $id]);
    }

    /** @param array<string,mixed> $row */
    private function hydrate(array $row): Task
    {
        // Task::fromStorage проверяет структурные инварианты и не проверяет
        // бизнес-правила создания: см. урок с мини-проектом трека.
        return Task::fromStorage(
            id: (string) $row['id'],
            userId: (string) $row['user_id'],
            title: (string) $row['title'],
            completed: (bool) $row['completed'],
            createdAt: new DateTimeImmutable((string) $row['created_at']),
        );
    }
}
# myapp/adapters/postgres/task_repo.py
import psycopg  # psycopg 3

from myapp import domain


# Репозиторий получает соединение, а не пул. Тогда один и тот же класс
# работает и сам по себе (соединение из `with pool.connection() as conn`
# на запрос), и внутри Unit of Work - на соединении транзакции.
class TaskRepo:
    def __init__(self, conn: psycopg.Connection) -> None:
        self._conn = conn

    def create(self, task: domain.Task) -> None:
        self._conn.execute(
            "INSERT INTO tasks (id, user_id, title, completed) VALUES (%s, %s, %s, %s)",
            (task.id, task.user_id, task.title, task.completed),
        )

    # get_by_id читает строку в локальные переменные и собирает сущность
    # через domain.Task.from_storage.
    #
    # Писать сразу в поля сущности нельзя: они закрыты - и это не помеха,
    # а смысл. Сборка через метод домена - единственное место, где строка
    # БД превращается в объект, и там же проверяются структурные инварианты.
    def get_by_id(self, task_id: str) -> domain.Task:
        row = self._conn.execute(
            "SELECT id, user_id, title, completed, created_at FROM tasks WHERE id = %s",
            (task_id,),
        ).fetchone()

        if row is None:
            raise domain.TaskNotFoundError()

        found_id, user_id, title, completed, created_at = row
        return domain.Task.from_storage(found_id, user_id, title, "", completed, created_at, None)

    def list_by_user(self, user_id: str) -> list[domain.Task]:
        rows = self._conn.execute(
            "SELECT id, user_id, title, completed, created_at"
            " FROM tasks WHERE user_id = %s ORDER BY created_at DESC",
            (user_id,),
        ).fetchall()

        tasks: list[domain.Task] = []
        for task_id, uid, title, completed, created_at in rows:
            # Одна повреждённая строка не должна выглядеть как пустой список:
            # CorruptedTaskError из from_storage не ловим - это ошибка данных,
            # и она обязана быть видна (id задачи уже в её сообщении).
            tasks.append(domain.Task.from_storage(task_id, uid, title, "", completed, created_at, None))
        return tasks

Ключевой момент в GetByID: ошибку «нет строки» мы превращаем в доменную (domain.ErrTaskNotFound / TaskError::notFound()). Потребитель (use-case) не знает ничего про pgx или Doctrine.

Реализация: InMemoryTaskRepository

Для unit-тестов не нужна база данных. Достаточно map.

// internal/adapters/inmemory/task_repo.go
package inmemory

import (
    "context"
    "sort"
    "sync"

    "myapp/internal/domain"
)

type TaskRepo struct {
    mu    sync.RWMutex
    store map[string]domain.Task
}

func NewTaskRepo() *TaskRepo {
    return &TaskRepo{store: make(map[string]domain.Task)}
}

func (r *TaskRepo) Create(_ context.Context, task domain.Task) error {
    r.mu.Lock()
    defer r.mu.Unlock()
    r.store[task.ID()] = task
    return nil
}

func (r *TaskRepo) GetByID(_ context.Context, id string) (domain.Task, error) {
    r.mu.RLock()
    defer r.mu.RUnlock()
    t, ok := r.store[id]
    if !ok {
        return domain.Task{}, domain.ErrTaskNotFound
    }
    return t, nil
}

func (r *TaskRepo) ListByUser(_ context.Context, userID string) ([]domain.Task, error) {
    r.mu.RLock()
    defer r.mu.RUnlock()
    var result []domain.Task
    for _, t := range r.store {
        if t.UserID() == userID {
            result = append(result, t)
        }
    }
    // Порядок обхода map случаен, а контракт задан Postgres-адаптером:
    // ORDER BY created_at DESC. Фейк обязан его повторить, иначе тесты,
    // которые смотрят на порядок, будут то зелёными, то красными.
    sort.Slice(result, func(i, j int) bool {
        return result[i].CreatedAt().After(result[j].CreatedAt())
    })
    return result, nil
}

func (r *TaskRepo) Update(_ context.Context, task domain.Task) error {
    r.mu.Lock()
    defer r.mu.Unlock()
    if _, ok := r.store[task.ID()]; !ok {
        return domain.ErrTaskNotFound
    }
    r.store[task.ID()] = task
    return nil
}

func (r *TaskRepo) Delete(_ context.Context, id string) error {
    r.mu.Lock()
    defer r.mu.Unlock()
    delete(r.store, id)
    return nil
}
<?php
// src/Infrastructure/Persistence/InMemory/InMemoryTaskRepository.php
declare(strict_types=1);

namespace App\Infrastructure\Persistence\InMemory;

use App\Application\Port\TaskRepositoryPort;
use App\Domain\Task;
use App\Domain\TaskError;

final class InMemoryTaskRepository implements TaskRepositoryPort
{
    /** @var array<string, Task> */
    private array $store = [];

    // Клонируем на входе и на выходе.
    //
    // Без clone in-memory-репозиторий хранил бы ссылку на тот же объект,
    // что у вызывающего: любая мутация домена сразу «сохранялась» бы
    // без вызова update. Тест на таком фейке проходит, а в проде тот же
    // код теряет изменения - фейк прятал бы ошибку, вместо того чтобы
    // её показать. Go-версия рядом хранит значения и получает это
    // поведение бесплатно.
    public function create(Task $task): void
    {
        $this->store[$task->id()] = clone $task;
    }

    public function getById(string $id): Task
    {
        if (!isset($this->store[$id])) {
            throw TaskError::notFound();
        }
        return clone $this->store[$id];
    }

    /** @return list<Task> */
    public function listByUser(string $userId): array
    {
        $result = [];
        foreach ($this->store as $task) {
            if ($task->userId() === $userId) {
                $result[] = clone $task;
            }
        }
        // Тот же порядок, что ORDER BY created_at DESC в Doctrine-адаптере
        usort($result, fn (Task $a, Task $b): int => $b->createdAt() <=> $a->createdAt());
        return $result;
    }

    public function update(Task $task): void
    {
        $this->store[$task->id()] = clone $task;
    }

    public function delete(string $id): void
    {
        unset($this->store[$id]);
    }
}
# myapp/adapters/inmemory/task_repo.py
import copy
import threading

from myapp import domain


class TaskRepo:
    def __init__(self) -> None:
        # RWMutex в stdlib нет; для тестового фейка достаточно обычного Lock
        # (он нужен и с GIL, и в free-threaded сборках CPython).
        self._lock = threading.Lock()
        self._store: dict[str, domain.Task] = {}

    # Копируем на входе и на выходе.
    #
    # Без copy in-memory-репозиторий хранил бы ссылку на тот же объект,
    # что у вызывающего: любая мутация домена сразу «сохранялась» бы
    # без вызова update. Тест на таком фейке проходит, а в проде тот же
    # код теряет изменения - фейк прятал бы ошибку, вместо того чтобы
    # её показать. Go-версия рядом хранит значения и получает это
    # поведение бесплатно.
    def create(self, task: domain.Task) -> None:
        with self._lock:
            self._store[task.id] = copy.copy(task)

    def get_by_id(self, task_id: str) -> domain.Task:
        with self._lock:
            task = self._store.get(task_id)
        if task is None:
            raise domain.TaskNotFoundError()
        return copy.copy(task)

    def list_by_user(self, user_id: str) -> list[domain.Task]:
        with self._lock:
            found = [copy.copy(t) for t in self._store.values() if t.user_id == user_id]
        # Тот же порядок, что ORDER BY created_at DESC в Postgres-адаптере
        return sorted(found, key=lambda t: t.created_at, reverse=True)

    def update(self, task: domain.Task) -> None:
        with self._lock:
            self._store[task.id] = copy.copy(task)

    def delete(self, task_id: str) -> None:
        with self._lock:
            self._store.pop(task_id, None)

PHP-FPM однопоточный per request. Мьютекс на in-memory store для тестов не нужен - PHPUnit запускает тесты последовательно в одном процессе. Если используешь ParaTest (параллельный запуск), у каждого процесса своя память - изоляция тестов сохраняется.

⚠️ sync.RWMutex в InMemory

Даже в тестовом репозитории ставь мьютекс. Пока достаточно знать три вещи:

  • Data race (гонка данных) - когда две горутины одновременно обращаются к одной переменной и хотя бы одна пишет, без синхронизации. Результат непредсказуем, а одновременная запись в map вообще роняет программу.
  • go test -race запускает тесты со встроенным детектором гонок: он следит за обращениями к памяти и печатает отчёт DATA RACE, если поймал гонку. Тесты с t.Parallel() и use-case, запускающие горутины, легко её создают.
  • sync.RWMutex - замок: RLock пускает много читателей сразу, Lock даёт писателю эксклюзивный доступ. Поэтому GetByID и ListByUser берут RLock, а Create и Update - Lock.

Подробно - в уроках Пакет sync и Race conditions и тестирование конкурентного кода. Привычка писать потокобезопасный код даже в фейке - бесплатная страховка.

Транзакции в репозиториях

Когда use-case требует, чтобы задача и событие о ней появились вместе, есть два подхода. Сразу уточним, о какой атомарности речь: об одной локальной транзакции одной базы - записать в брокер атомарно с базой нельзя (три смысла слова «атомарно»).

Подход 1: Unit of Work через интерфейс.

type UnitOfWork interface {
    Do(ctx context.Context, fn func(repos Repositories) error) error
}

type Repositories struct {
    Tasks  TaskRepository
    Events EventRepository
}
<?php
// src/Application/Port/UnitOfWorkPort.php
declare(strict_types=1);

namespace App\Application\Port;

interface UnitOfWorkPort
{
    /**
     * @template T
     * @param callable(Repositories): T $fn
     * @return T
     */
    public function transactional(callable $fn): mixed;
}

final readonly class Repositories
{
    public function __construct(
        public TaskRepositoryPort $tasks,
        public EventRepositoryPort $events,
    ) {}
}

<?php
// src/Infrastructure/Persistence/Doctrine/DoctrineUnitOfWork.php
declare(strict_types=1);

namespace App\Infrastructure\Persistence\Doctrine;

use App\Application\Port\Repositories;
use App\Application\Port\UnitOfWorkPort;
use Doctrine\DBAL\Connection;

final class DoctrineUnitOfWork implements UnitOfWorkPort
{
    public function __construct(
        private readonly Connection $connection,
        private readonly Repositories $repos,
    ) {}

    public function transactional(callable $fn): mixed
    {
        return $this->connection->transactional(fn () => $fn($this->repos));
    }
}
# myapp/usecase/ports/unit_of_work.py
from dataclasses import dataclass
from typing import Callable, Protocol, TypeVar

T = TypeVar("T")


@dataclass(frozen=True)
class Repositories:
    tasks: TaskRepository
    events: EventRepository


class UnitOfWork(Protocol):
    def do(self, fn: Callable[[Repositories], T]) -> T: ...


# myapp/adapters/postgres/unit_of_work.py
class PostgresUnitOfWork:
    def __init__(self, pool: ConnectionPool) -> None:
        self._pool = pool

    def do(self, fn: Callable[[Repositories], T]) -> T:
        # conn.transaction(): BEGIN на входе, COMMIT на выходе,
        # ROLLBACK при исключении. Репозитории собираются на этом же
        # соединении - иначе BEGIN и INSERT окажутся в разных сессиях пула.
        with self._pool.connection() as conn, conn.transaction():
            return fn(Repositories(tasks=TaskRepo(conn), events=EventRepo(conn)))

Use-case вызывает uow.Do(ctx, func(repos) { ... }) / $uow->transactional(fn ($repos) => ...), а адаптер оборачивает вызов в BEGIN / COMMIT.

Подход 2: передать транзакцию через context. Этот способ проще, но связывает слои через скрытое состояние в контексте. Первый подход предпочтительнее в большинстве случаев.

🚫 Не возвращай *sql.Rows из репозитория

Если интерфейс возвращает *sql.Rows, потребитель обязан вызвать rows.Close(). Это утечка абстракции: use-case знает, что работает с SQL. Репозиторий должен вернуть []domain.Task или ошибку - ничего между.

Порт, два его адаптера, use-case и сборка зависимостей в одном месте собраны в мини-проекте Tasks API - там же видно, что переключение с in-memory на PostgreSQL меняет ровно одну строку.

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

  • Объяви интерфейс UserRepository в пакете usecase/ports/ с методами Create, GetByID, GetByEmail
  • Напиши InMemoryUserRepo, который реализует этот интерфейс через map[string]domain.User
  • Убедись, что InMemoryUserRepo возвращает доменную ошибку domain.ErrUserNotFound, а не generic «not found»
  • Проверь, что use-case импортирует только пакеты domain и usecase/ports - никаких database/sql или pgx

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