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-порт.
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 выше.
⚠️ Антипаттерн: интерфейс в пакете реализации
Если
UserRepointerface лежит в пакетеpostgres/- это неправильно. Получается, что use-case импортирует инфраструктурный пакет ради интерфейса. Зависимость идёт в неправильном направлении.
Несколько адаптеров для одного порта
Главная сила портов - возможность подставить разные адаптеры под один интерфейс. 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- для productioninmemory.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 принимает интерфейс в конструкторе, а не конкретный тип