Ports & Adapters: порты, адаптеры и что куда зависим

Ports & Adapters: порты, адаптеры и что куда зависим

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

Порт = интерфейс

Порт - это контракт. В Go порт - это interface, в PHP - interface. Он описывает, что нужно сделать, но не как.

// usecase/ports/user_repo.go
package ports

import (
    "context"

    "myapp/internal/domain"
)

type UserRepo interface {
    GetByID(ctx context.Context, id int64) (*domain.User, error)
    GetByEmail(ctx context.Context, email string) (*domain.User, error)
    Create(ctx context.Context, user *domain.User) error
}
<?php
// src/Application/Port/UserRepositoryPort.php
declare(strict_types=1);

namespace App\Application\Port;

use App\Domain\User;

interface UserRepositoryPort
{
    public function getById(int $id): ?User;

    public function getByEmail(string $email): ?User;

    public function create(User $user): void;
}
# usecase/ports/user_repo.py
from typing import Protocol

from myapp.domain import User


# Protocol - структурный интерфейс: адаптеру не нужно наследоваться от него,
# достаточно иметь те же методы (как с интерфейсами в Go).
class UserRepo(Protocol):
    def get_by_id(self, user_id: int) -> User: ...  # не найден - UserNotFoundError
    def get_by_email(self, email: str) -> User: ...
    def create(self, user: User) -> None: ...

Порт ничего не знает о PostgreSQL, MongoDB или файловой системе. Он знает только доменные типы: сущности (объекты со своим ID и историей, как User) и объекты-значения (значения без ID, которые равны, если равно содержимое, как Email). Для этого трека такого различия достаточно, подробный разбор - в уроке Entity и Value Object следующего трека.

Адаптер = реализация

Адаптер - это конкретная реализация порта. Он содержит всю инфраструктурную логику:

// adapters/postgres/user_repo.go
package postgres

import (
    "context"
    "database/sql"
    "errors"

    "myapp/internal/domain"
)

type UserRepo struct {
    db *sql.DB
}

func NewUserRepo(db *sql.DB) *UserRepo {
    return &UserRepo{db: db}
}

func (r *UserRepo) GetByID(ctx context.Context, id int64) (*domain.User, error) {
    return r.getOne(ctx, "SELECT id, email, name, password_hash, created_at FROM users WHERE id = $1", id)
}

func (r *UserRepo) GetByEmail(ctx context.Context, email string) (*domain.User, error) {
    return r.getOne(ctx, "SELECT id, email, name, password_hash, created_at FROM users WHERE email = $1", email)
}

// getOne - общий путь чтения одного пользователя: запросы разные,
// а сканирование и перевод sql.ErrNoRows в доменную ошибку одинаковые.
func (r *UserRepo) getOne(ctx context.Context, query string, arg any) (*domain.User, error) {
    var u domain.User
    err := r.db.QueryRowContext(ctx, query, arg).Scan(&u.ID, &u.Email, &u.Name, &u.PasswordHash, &u.CreatedAt)
    if errors.Is(err, sql.ErrNoRows) {
        return nil, domain.ErrUserNotFound
    }
    if err != nil {
        return nil, err
    }
    return &u, nil
}

func (r *UserRepo) Create(ctx context.Context, user *domain.User) error {
    // RETURNING id читается через QueryRow: ExecContext его просто выбросил бы,
    // и у созданного пользователя остался бы ID = 0.
    return r.db.QueryRowContext(ctx,
        "INSERT INTO users (email, name, password_hash) VALUES ($1, $2, $3) RETURNING id",
        user.Email, user.Name, user.PasswordHash,
    ).Scan(&user.ID)
}
<?php
// src/Infrastructure/Persistence/Doctrine/DoctrineUserRepository.php
declare(strict_types=1);

namespace App\Infrastructure\Persistence\Doctrine;

use App\Application\Port\UserRepositoryPort;
use App\Domain\User;
use Doctrine\DBAL\Connection;

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

    public function getById(int $id): ?User
    {
        $row = $this->connection->fetchAssociative(
            'SELECT id, email, name, password_hash, created_at FROM users WHERE id = :id',
            ['id' => $id],
        );
        return $row === false ? null : $this->hydrate($row);
    }

    public function getByEmail(string $email): ?User
    {
        $row = $this->connection->fetchAssociative(
            'SELECT id, email, name, password_hash, created_at FROM users WHERE email = :email',
            ['email' => $email],
        );
        return $row === false ? null : $this->hydrate($row);
    }

    public function create(User $user): void
    {
        $this->connection->insert('users', [
            'email' => $user->email(),
            'name' => $user->name(),
            'password_hash' => $user->passwordHash(),
        ]);
    }

    /** @param array<string,mixed> $row */
    private function hydrate(array $row): User
    {
        return User::fromStorage(
            id: (int) $row['id'],
            email: (string) $row['email'],
            name: (string) $row['name'],
            passwordHash: (string) $row['password_hash'],
        );
    }
}
# adapters/postgres/user_repo.py
import psycopg

from myapp.domain import User, UserNotFoundError


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

    def get_by_id(self, user_id: int) -> User:
        return self._get_one("SELECT id, email, name, password_hash, created_at FROM users WHERE id = %s", user_id)

    def get_by_email(self, email: str) -> User:
        return self._get_one("SELECT id, email, name, password_hash, created_at FROM users WHERE email = %s", email)

    # Общий путь чтения одного пользователя: запросы разные,
    # а разбор строки и «не найден» одинаковые.
    def _get_one(self, query: str, key: int | str) -> User:
        with self._conn.cursor() as cur:
            cur.execute(query, (key,))
            row = cur.fetchone()
        if row is None:
            raise UserNotFoundError(key)
        return User(id=row[0], email=row[1], name=row[2], password_hash=row[3], created_at=row[4])

    def create(self, user: User) -> None:
        with self._conn.cursor() as cur:
            cur.execute(
                "INSERT INTO users (email, name, password_hash) VALUES (%s, %s, %s) RETURNING id",
                (user.email, user.name, user.password_hash),
            )
            # RETURNING id нужно забрать, иначе у созданного пользователя не будет id
            user.id = cur.fetchone()[0]
        self._conn.commit()

ℹ️ Неявная реализация интерфейсов в Go

В Go не нужно писать implements UserRepo. Если структура имеет все методы из интерфейса - она его реализует. Компилятор проверит это автоматически. Это делает Go особенно удобным для Ports & Adapters: адаптеру не обязательно импортировать пакет с портом, достаточно доменных типов.

Driving vs Driven порты

Порты делятся на два типа:

Driving (первичные) порты - через них внешний мир вызывает приложение. Пример: HTTP handler вызывает use-case. Driving-порт - входной контракт приложения: интерфейс сценария или его публичный метод Execute. Use-case этот контракт реализует, а handler вызывает.

Driven (вторичные) порты - через них приложение обращается к инфраструктуре. Пример: use-case вызывает UserRepo.Create(). Репозиторий - driven-порт.

Driving и driven порты: handler слева как driving-адаптер, репозиторий справа как driven-адаптер

Handler - driving-адаптер. Он преобразует HTTP-запрос в вызов use-case. PostgresRepo - driven-адаптер. Он преобразует вызов интерфейса в SQL-запрос.

Как выглядит driving-адаптер целиком - парсинг тела, извлечение userID из контекста, маппинг доменных ошибок в коды ответа - показано в уроке HTTP адаптер.

Где живут интерфейсы

В Go принято размещать интерфейс рядом с тем, кто его использует, а не рядом с тем, кто его реализует. Это следствие принципа Interface Segregation и философии Go «accept interfaces, return structs».

Состав методов определяет потребитель

Правило про размещение файла запоминается легко, и на этом обычно останавливаются. Но переложить интерфейс в пакет usecase/ports/ мало: он всё ещё может быть определён не тем, кто его использует.

Вот порт, лежащий в правильном месте и составленный неправильно - по списку того, что умеет таблица:

// usecase/ports/user_repo.go - папка верная, состав методов нет
type UserRepo interface {
    GetByID(ctx context.Context, id int64) (*domain.User, error)
    GetByEmail(ctx context.Context, email string) (*domain.User, error)
    GetByPhone(ctx context.Context, phone string) (*domain.User, error)
    List(ctx context.Context, limit, offset int) ([]*domain.User, error)
    Search(ctx context.Context, query string) ([]*domain.User, error)
    Create(ctx context.Context, u *domain.User) error
    Update(ctx context.Context, u *domain.User) error
    Delete(ctx context.Context, id int64) error
}
<?php
// src/Port/UserRepository.php - та же ошибка
declare(strict_types=1);

namespace App\Port;

use App\Domain\User\User;

interface UserRepository
{
    public function getById(int $id): ?User;
    public function getByEmail(string $email): ?User;
    public function getByPhone(string $phone): ?User;
    public function list(int $limit, int $offset): array;
    public function search(string $query): array;
    public function create(User $u): void;
    public function update(User $u): void;
    public function delete(int $id): void;
}
# usecase/ports/user_repo.py - папка верная, состав методов нет
class UserRepo(Protocol):
    def get_by_id(self, user_id: int) -> User: ...
    def get_by_email(self, email: str) -> User: ...
    def get_by_phone(self, phone: str) -> User: ...
    def list_all(self, limit: int, offset: int) -> list[User]: ...
    def search(self, query: str) -> list[User]: ...
    def create(self, u: User) -> None: ...
    def update(self, u: User) -> None: ...
    def delete(self, user_id: int) -> None: ...

Это не порт, а перечень возможностей хранилища - тот же DAO, только через интерфейс. А вот контракт под конкретный сценарий:

// usecase/register_user.go - рядом со сценарием, ровно под его нужды.
// Интерфейс неэкспортируемый: он нужен только здесь.
type userStore interface {
    ByEmail(ctx context.Context, email domain.Email) (*domain.User, error)
    Add(ctx context.Context, u *domain.User) error
}
<?php
// src/Application/RegisterUser/UserStore.php - в namespace сценария
declare(strict_types=1);

namespace App\Application\RegisterUser;

use App\Domain\User\Email;
use App\Domain\User\User;

interface UserStore
{
    public function byEmail(Email $email): ?User;

    public function add(User $user): void;
}
# usecase/register_user.py - рядом со сценарием, ровно под его нужды.
# Protocol с подчёркиванием: он нужен только в этом модуле.
class _UserStore(Protocol):
    def by_email(self, email: Email) -> User | None: ...
    def add(self, u: User) -> None: ...

Два метода, имена на языке сценария. Одна реализация в адаптере может удовлетворять пяти таким мелким портам одновременно: в Go это бесплатно (явного implements нет), в PHP - список через запятую в implements UserStore, PasswordResetStore, ProfileStore.

⚠️ Признаки порта, определённого хранилищем

  • интерфейс растёт от новых запросов, а не от новых сценариев. Понадобился фильтр - добавили метод, и все реализации, включая тестовую, пришлось дописать;
  • сценарий использует два метода из восьми. Регистрация вызывает GetByEmail и Create, а мок для теста надо заполнять целиком;
  • имена методов пахнут хранилищем: List(limit, offset) - это про пагинацию SQL, а не про то, что делает бизнес-сценарий.

Когда общий крупный порт всё же уместен: если методов немного и их использует почти каждый сценарий - Get/Save/Delete для агрегата типичный случай, см. репозитории в DDD. Дробить два метода на два интерфейса ради принципа - другая крайность.

Ориентир: интерфейс переписывают, когда меняется сценарий, а не когда меняется база.

internal/
├── usecase/               # Use-cases - используют порты
│   ├── ports/             # Общие порты слоя приложения: небольшие интерфейсы,
│   │   ├── user_repo.go   # нужные многим сценариям; ни одного импорта адаптеров
│   │   └── progress_repo.go
│   └── register_user.go   # + узкий порт userStore только для этого сценария
└── adapters/
    └── postgres/          # Адаптеры - реализуют порты
        └── user_repo.go

usecase/ports/ здесь - часть слоя приложения, а не общий пакет «интерфейсы для всех»: в нём лежат только контракты, которые нужны use-case, и он не импортирует ни одного адаптера. Небольшой порт, которым пользуются почти все сценарии (как UserRepo из начала урока), удобно держать там. Узкий порт под один сценарий лучше объявить прямо в файле сценария, как userStore выше.

⚠️ Антипаттерн: интерфейс в пакете реализации

Если UserRepo interface лежит в пакете postgres/ - это неправильно. Получается, что use-case импортирует инфраструктурный пакет ради интерфейса. Зависимость идёт в неправильном направлении.

Несколько адаптеров для одного порта

Один порт UserRepo и три адаптера: Postgres для прода, in-memory для unit-тестов, mock для проверки взаимодействий

Главная сила портов - возможность подставить разные адаптеры под один интерфейс. Use-case даже не знает, какая реализация под ним стоит: postgres.UserRepo в продакшене, inmemory.UserRepo в юнит-тестах, mock.UserRepo - когда нужно проверить вызовы.

// adapters/inmemory/user_repo.go - для тестов
package inmemory

import (
    "context"
    "sync"

    "myapp/internal/domain"
)

// UserRepo хранит копии, а не указатели.
//
// Разница не косметическая. С map[int64]*domain.User репозиторий отдавал бы
// тот же объект, что лежит внутри: изменение через метод домена
// «сохранялось» бы само, без вызова Update. Тест на таком фейке зелёный,
// а в проде тот же код теряет изменения - фейк прятал бы ошибку вместо
// того, чтобы её показать.
type UserRepo struct {
    mu     sync.RWMutex
    users  map[int64]domain.User
    nextID int64
}

func NewUserRepo() *UserRepo {
    return &UserRepo{users: make(map[int64]domain.User), nextID: 1}
}

func (r *UserRepo) GetByID(_ context.Context, id int64) (*domain.User, error) {
    r.mu.RLock()
    defer r.mu.RUnlock()
    u, ok := r.users[id]
    if !ok {
        return nil, domain.ErrUserNotFound
    }
    // Возвращаем адрес копии: у вызывающего свой объект, наш остаётся нашим.
    return &u, nil
}

func (r *UserRepo) GetByEmail(_ context.Context, email string) (*domain.User, error) {
    r.mu.RLock()
    defer r.mu.RUnlock()
    for _, u := range r.users {
        if u.Email == email {
            return &u, nil // u - уже копия из map
        }
    }
    return nil, domain.ErrUserNotFound
}

func (r *UserRepo) Create(_ context.Context, user *domain.User) error {
    r.mu.Lock()
    defer r.mu.Unlock()
    user.ID = r.nextID
    r.nextID++
    r.users[user.ID] = *user
    return nil
}

func (r *UserRepo) Update(_ context.Context, user *domain.User) error {
    r.mu.Lock()
    defer r.mu.Unlock()
    if _, ok := r.users[user.ID]; !ok {
        return domain.ErrUserNotFound
    }
    r.users[user.ID] = *user
    return nil
}
<?php
// tests/Fakes/InMemoryUserRepository.php
declare(strict_types=1);

namespace App\Tests\Fakes;

use App\Application\Port\UserRepositoryPort;
use App\Domain\User;

final class InMemoryUserRepository implements UserRepositoryPort
{
    /** @var array<int, User> */
    private array $users = [];
    private int $nextId = 1;

    // Храним и отдаём копии (clone), как Go- и Python-версии: иначе изменение
    // через метод домена «сохранялось» бы само, без вызова update, и фейк
    // прятал бы ошибку, которую в проде покажет настоящая база.
    public function getById(int $id): ?User
    {
        return isset($this->users[$id]) ? clone $this->users[$id] : null;
    }

    public function getByEmail(string $email): ?User
    {
        foreach ($this->users as $user) {
            if ($user->email() === $email) {
                return clone $user;
            }
        }
        return null;
    }

    public function create(User $user): void
    {
        $user->assignId($this->nextId++);
        $this->users[$user->id()] = clone $user;
    }
}
# adapters/inmemory/user_repo.py - для тестов
import threading
from dataclasses import replace

from myapp.domain import User, UserNotFoundError


# UserRepo хранит копии, а не ссылки.
#
# Разница не косметическая. В Python объекты передаются по ссылке: положи
# в dict сам user - и репозиторий отдавал бы тот же объект, что лежит
# внутри: изменение через метод домена «сохранялось» бы само, без вызова
# update. Тест на таком фейке зелёный, а в проде тот же код теряет
# изменения - фейк прятал бы ошибку вместо того, чтобы её показать.
class UserRepo:
    def __init__(self) -> None:
        # Lock вместо RWMutex: для тестового фейка разницы нет
        self._lock = threading.Lock()
        self._users: dict[int, User] = {}
        self._next_id = 1

    def get_by_id(self, user_id: int) -> User:
        with self._lock:
            user = self._users.get(user_id)
            if user is None:
                raise UserNotFoundError(user_id)
            # Возвращаем копию: у вызывающего свой объект, наш остаётся нашим.
            return replace(user)

    def get_by_email(self, email: str) -> User:
        with self._lock:
            for user in self._users.values():
                if user.email == email:
                    return replace(user)
            raise UserNotFoundError(email)

    def create(self, user: User) -> None:
        with self._lock:
            user.id = self._next_id
            self._next_id += 1
            self._users[user.id] = replace(user)

    def update(self, user: User) -> None:
        with self._lock:
            if user.id not in self._users:
                raise UserNotFoundError(user.id)
            self._users[user.id] = replace(user)

PHP-FPM запускает request → выполняет → завершается. In-process mutex для in-memory адаптера в тестах не нужен - тесты выполняются последовательно в одном процессе. Если нужна shared state между процессами, используй Redis или APCu.

Теперь у одного порта UserRepo три адаптера:

  • postgres.UserRepo - для production
  • inmemory.UserRepo - для юнит-тестов
  • mock.UserRepo (testify/mock) - для проверки вызовов

Dependency Injection: собираем всё вместе

Адаптеры подставляются в use-case через конструктор. Здесь сценарий принимает небольшой общий порт UserRepo из начала урока: три метода, которыми пользуются почти все сценарии с пользователем, - это тот случай, когда общий порт уместен. Если бы порт разросся до восьми методов, регистрации стоило бы принимать узкий userStore, объявленный рядом с ней.

// usecase/register_user.go
package usecase

import "myapp/internal/usecase/ports"

type RegisterUser struct {
    users ports.UserRepo   // принимаем интерфейс, не конкретный тип
}

func NewRegisterUser(users ports.UserRepo) *RegisterUser {
    return &RegisterUser{users: users}
}
<?php
// src/Application/UseCase/RegisterUserUseCase.php
declare(strict_types=1);

namespace App\Application\UseCase;

use App\Application\Port\NotificationPort;
use App\Application\Port\UserRepositoryPort;

final class RegisterUserUseCase
{
    public function __construct(
        private readonly UserRepositoryPort $users,
        private readonly NotificationPort $notifier,
    ) {}
}
# usecase/register_user.py
from myapp.usecase.ports import UserRepo


class RegisterUser:
    def __init__(self, users: UserRepo) -> None:
        self._users = users  # принимаем Protocol, не конкретный класс

В main.go собираем зависимости руками:

func main() {
    db := connectDB()

    // Production: Postgres-адаптер
    userRepo := postgres.NewUserRepo(db)

    // Use-case получает адаптер через интерфейс
    registerUC := usecase.NewRegisterUser(userRepo)

    // Handler получает use-case. Пакет адаптера называется http, поэтому
    // импортируем его под псевдонимом, чтобы не столкнуться с net/http:
    // httpadapter "myapp/internal/adapters/http"
    handler := httpadapter.NewRegisterHandler(registerUC)

    router.Post("/users", handler.Handle)
}
# config/services.yaml - Symfony DI связывает интерфейс с реализацией
services:
    _defaults:
        autowire: true
        autoconfigure: true

    App\:
        resource: '../src/'

    # Production: связываем порт с Doctrine-адаптером
    App\Application\Port\UserRepositoryPort:
        alias: App\Infrastructure\Persistence\Doctrine\DoctrineUserRepository
# main.py - сборка руками; в FastAPI это Depends(), в Django - контейнер
# (например, dependency-injector) или фабрика в apps.py
def main() -> None:
    conn = connect_db()

    # Production: Postgres-адаптер
    user_repo = postgres.UserRepo(conn)

    # Use-case получает адаптер через Protocol
    register_uc = usecase.RegisterUser(user_repo)

    # Handler получает use-case
    handler = http.RegisterHandler(register_uc)

    router.post("/users", handler.handle)

В тестах - другой адаптер:

func TestRegisterUser(t *testing.T) {
    // Тест: in-memory адаптер, без базы данных
    userRepo := inmemory.NewUserRepo()
    uc := usecase.NewRegisterUser(userRepo)

    err := uc.Execute(context.Background(), usecase.RegisterInput{
        Email: "test@example.com",
        Name:  "Test",
    })
    assert.NoError(t, err)
}
<?php
// tests/Application/UseCase/RegisterUserUseCaseTest.php
declare(strict_types=1);

namespace App\Tests\Application\UseCase;

use App\Application\UseCase\RegisterUserUseCase;
use App\Tests\Fakes\InMemoryUserRepository;
use App\Tests\Fakes\NullNotifier;
use PHPUnit\Framework\TestCase;

final class RegisterUserUseCaseTest extends TestCase
{
    public function testRegistersUserWithInMemoryAdapter(): void
    {
        $users = new InMemoryUserRepository();
        $uc = new RegisterUserUseCase($users, new NullNotifier());

        $uc->execute('test@example.com', 'Test');

        self::assertNotNull($users->getByEmail('test@example.com'));
    }
}
# tests/test_register_user.py (pytest)
def test_register_user() -> None:
    # Тест: in-memory адаптер, без базы данных
    user_repo = inmemory.UserRepo()
    uc = usecase.RegisterUser(user_repo)

    # Явного assert нет: если сценарий бросит исключение, pytest уронит тест
    uc.execute(usecase.RegisterInput(email="test@example.com", name="Test"))

ℹ️ Сборка зависимостей в Go

В Go граф зависимостей обычно собирают руками в main.go, как выше: явно и без магии. Google Wire, который генерирует такой код на этапе компиляции, известен, но его репозиторий в архиве и не поддерживается. Если ручная сборка разрослась, альтернатива - uber-go/fx.

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

  • Определи в своём коде один driven-порт (например, репозиторий) и напиши для него Go interface
  • Перенеси SQL-логику из сервиса/handler в отдельный struct-адаптер, который реализует этот интерфейс
  • Напиши in-memory адаптер для того же интерфейса (map + mutex)
  • Убедись, что use-case принимает интерфейс в конструкторе, а не конкретный тип

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