Репозитории и интерфейсы: где им жить
Репозитории и интерфейсы: где им жить
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