Мини-проект: Tasks API в hex-стиле (Go, PHP, Python)

Мини-проект: Tasks API в hex-стиле

Соберём полноценный API для управления задачами с нуля. Каждый слой - отдельный пакет. Зависимости направлены внутрь. Всё, что изучали в предыдущих уроках, здесь складывается в рабочий проект. Если по ходу станет непонятно, почему пакеты расставлены именно так, вернись к уроку Ports & Adapters: направление зависимостей задаёт именно он.

Структура проекта

tasks-api/
├── cmd/
│   └── server/
│       └── main.go              # точка входа, DI, запуск сервера
├── 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     # use-case: завершить задачу
│   │   └── list_tasks.go        # use-case: список задач
│   └── adapters/
│       ├── postgres/
│       │   └── task_repo.go     # PostgresTaskRepo
│       ├── inmemory/
│       │   └── task_repo.go     # InMemoryTaskRepo (тесты)
│       └── http/
│           ├── handler.go       # TaskHandler
│           └── response.go      # JSON helpers
├── go.mod
└── go.sum

ℹ️ Правило зависимостей

domain не импортирует ничего из проекта. usecase импортирует domain и usecase/ports. Driven-адаптеры (postgres, inmemory) импортируют domain (и при желании usecase/ports), driving-адаптер http импортирует domain и usecase. cmd импортирует всех - здесь происходит сборка.

Слои проекта Tasks API: cmd собирает всё, adapters реализуют порты, use-case в центре, domain ниже всех

Domain: entity Task

// internal/domain/task.go
package domain

import (
    "time"
    "unicode/utf8"

    "github.com/google/uuid"
)

// maxTitleLen - лимит в символах, а не в байтах: len(string) в Go считает
// байты, и русский заголовок из 101 буквы (202 байта) не прошёл бы.
const maxTitleLen = 200

func validTitle(title string) bool {
    n := utf8.RuneCountInString(title)
    return n > 0 && n <= maxTitleLen
}

// Task - доменная сущность с закрытыми полями.
//
// Поля неэкспортированы не для красоты: с экспортированными полями любой
// пакет пишет `domain.Task{}` литералом или `t.Title = ""` напрямую,
// и тогда утверждение «невалидный Task создать нельзя» становится
// неправдой - валидация в NewTask просто обходится.
type Task struct {
    id          string
    userID      string
    title       string
    description string
    completed   bool
    createdAt   time.Time
    completedAt *time.Time
}

// Геттеры: наружу отдаём значения, менять состояние можно только методами ниже.
func (t Task) ID() string             { return t.id }
func (t Task) UserID() string         { return t.userID }
func (t Task) Title() string          { return t.title }
func (t Task) Description() string    { return t.description }
func (t Task) Completed() bool        { return t.completed }
func (t Task) CreatedAt() time.Time   { return t.createdAt }
func (t Task) CompletedAt() *time.Time { return t.completedAt }

// NewTask создаёт задачу с валидацией.
func NewTask(userID, title, description string) (Task, error) {
    if userID == "" {
        return Task{}, ErrInvalidUserID
    }
    if !validTitle(title) {
        return Task{}, ErrInvalidTitle
    }

    return Task{
        id:          uuid.NewString(),
        userID:      userID,
        title:       title,
        description: description,
        completed:   false,
        createdAt:   time.Now(),
    }, nil
}

// TaskFromStorage восстанавливает задачу из строки БД.
//
// Отдельная функция нужна потому, что закрытые поля иначе не заполнить
// из пакета-адаптера. Но «отдельная функция» не значит «дыра в инвариантах»:
// если сюда можно передать что угодно, проблема просто переехала из литерала
// структуры в вызов этой функции.
//
// Политика такая:
//
//   - структурные инварианты проверяем всегда (пустой id, пустой userID,
//     пустой или слишком длинный title). Их нарушение означает, что в базе
//     лежит мусор, и тащить его в домен нельзя - лучше явная ошибка
//     на чтении, чем непонятное поведение через три слоя;
//   - остальное считаем доверенным состоянием: время создания, флаг
//     выполнения и завершения пришли из нашей же записи, повторно
//     их «бизнес-проверять» бессмысленно. Например, задача может быть
//     completed - через NewTask такую не создать, и это нормально:
//     это результат вызова Complete() когда-то раньше.
//
// Что делать с уже испорченными строками, если они есть: чинить их
// миграцией, а не ослаблять проверку. Ошибка на чтении покажет, сколько
// таких строк и где.
func TaskFromStorage(
    id, userID, title, description string,
    completed bool,
    createdAt time.Time,
    completedAt *time.Time,
) (Task, error) {
    if id == "" || userID == "" {
        return Task{}, ErrCorruptedTask
    }
    if !validTitle(title) {
        return Task{}, ErrCorruptedTask
    }

    return Task{
        id:          id,
        userID:      userID,
        title:       title,
        description: description,
        completed:   completed,
        createdAt:   createdAt,
        completedAt: completedAt,
    }, nil
}

// Complete отмечает задачу выполненной.
func (t *Task) Complete() error {
    if t.completed {
        return ErrTaskAlreadyCompleted
    }
    t.completed = true
    now := time.Now()
    t.completedAt = &now
    return nil
}

// CompleteBy завершает задачу от имени пользователя.
// «Чужую задачу завершить нельзя» - доменное правило, поэтому оно здесь,
// а не сравнением полей в use-case. Проверка «кто ты» (токен, заголовок)
// остаётся в middleware: она техническая и до домена не доходит.
func (t *Task) CompleteBy(userID string) error {
    if t.userID != userID {
        return ErrAccessDenied
    }
    return t.Complete()
}

// SetTitle обновляет заголовок с валидацией.
func (t *Task) SetTitle(title string) error {
    if !validTitle(title) {
        return ErrInvalidTitle
    }
    t.title = title
    return nil
}
// internal/domain/errors.go
package domain

import "errors"

var (
    ErrTaskNotFound         = errors.New("task not found")
    ErrTaskAlreadyCompleted = errors.New("task already completed")
    ErrInvalidTitle         = errors.New("invalid title: must be 1-200 characters")
    ErrInvalidUserID        = errors.New("invalid user ID")
    // ErrCorruptedTask - строка в базе не проходит структурные инварианты.
    // Отдельная ошибка, потому что причина другая: не пользователь ошибся,
    // а данные повреждены. Наружу это 500, а не 400.
    ErrCorruptedTask        = errors.New("corrupted task in storage")
    ErrAccessDenied         = errors.New("access denied")
)
<?php
// src/Domain/Task.php
declare(strict_types=1);

namespace App\Domain;

use DateTimeImmutable;
use Symfony\Component\Uid\Uuid;

final class Task
{
    private bool $completed = false;
    private ?DateTimeImmutable $completedAt = null;

    private function __construct(
        private readonly string $id,
        private readonly string $userId,
        private string $title,
        private string $description,
        private readonly DateTimeImmutable $createdAt,
    ) {}

    public static function create(string $userId, string $title, string $description): self
    {
        if ($userId === '') {
            throw TaskError::invalidUserId();
        }
        if ($title === '' || mb_strlen($title) > 200) {
            throw TaskError::invalidTitle();
        }

        return new self(
            id: Uuid::v4()->toRfc4122(),
            userId: $userId,
            title: $title,
            description: $description,
            createdAt: new DateTimeImmutable(),
        );
    }

    public function complete(): void
    {
        if ($this->completed) {
            throw TaskError::alreadyCompleted();
        }
        $this->completed = true;
        $this->completedAt = new DateTimeImmutable();
    }

    /** «Чужую задачу завершить нельзя» - доменное правило, поэтому оно здесь. */
    public function completeBy(string $userId): void
    {
        if ($this->userId !== $userId) {
            throw TaskError::accessDenied();
        }
        $this->complete();
    }

    public function setTitle(string $title): void
    {
        if ($title === '' || mb_strlen($title) > 200) {
            throw TaskError::invalidTitle();
        }
        $this->title = $title;
    }

    /**
     * Восстановление из строки БД.
     *
     * Конструктор приватный, поэтому адаптеру нужна отдельная точка входа.
     * Структурные инварианты проверяются и здесь: если в базе пустой id
     * или пустой title, это повреждённые данные, и пускать их в домен
     * нельзя. Доверенным считается только то, что через бизнес-правила
     * пройти не может по определению - например, уже выставленный
     * $completed: он результат вызова complete() когда-то раньше.
     */
    public static function fromStorage(
        string $id,
        string $userId,
        string $title,
        bool $completed,
        string $description = '',
        ?DateTimeImmutable $createdAt = null,
        ?DateTimeImmutable $completedAt = null,
    ): self {
        if ($id === '' || $userId === '' || $title === '' || mb_strlen($title) > 200) {
            throw TaskError::corrupted($id);
        }

        $task = new self(
            id: $id,
            userId: $userId,
            title: $title,
            description: $description,
            createdAt: $createdAt ?? new DateTimeImmutable(),
        );
        $task->completed = $completed;
        $task->completedAt = $completedAt;

        return $task;
    }

    public function id(): string { return $this->id; }
    public function userId(): string { return $this->userId; }
    public function title(): string { return $this->title; }
    public function isCompleted(): bool { return $this->completed; }
    public function createdAt(): DateTimeImmutable { return $this->createdAt; }
}
<?php
// src/Domain/TaskError.php
declare(strict_types=1);

namespace App\Domain;

use DomainException;

final class TaskError extends DomainException
{
    // Вид ошибки - для маппинга в HTTP-статус. Сравнивать по тексту
    // сообщения нельзя: любая правка формулировки молча сломает маппинг.
    public const NOT_FOUND = 'not_found';
    public const ALREADY_COMPLETED = 'already_completed';
    public const INVALID_TITLE = 'invalid_title';
    public const INVALID_USER_ID = 'invalid_user_id';
    public const ACCESS_DENIED = 'access_denied';
    public const CORRUPTED = 'corrupted';

    private function __construct(string $message, public readonly string $kind)
    {
        parent::__construct($message);
    }

    public static function notFound(): self { return new self('task not found', self::NOT_FOUND); }
    public static function alreadyCompleted(): self { return new self('task already completed', self::ALREADY_COMPLETED); }
    public static function invalidTitle(): self { return new self('invalid title: must be 1-200 characters', self::INVALID_TITLE); }
    public static function invalidUserId(): self { return new self('invalid user id', self::INVALID_USER_ID); }
    public static function accessDenied(): self { return new self('access denied', self::ACCESS_DENIED); }

    /** Строка в БД не проходит структурные инварианты: наружу это 500, а не 400. */
    public static function corrupted(string $id): self
    {
        return new self(sprintf('corrupted task in storage: id=%s', $id), self::CORRUPTED);
    }
}
# tasks_api/domain/task.py
from __future__ import annotations

import uuid
from datetime import datetime, timezone

from tasks_api.domain.errors import (
    AccessDeniedError,
    CorruptedTaskError,
    InvalidTitleError,
    InvalidUserIdError,
    TaskAlreadyCompletedError,
)


class Task:
    """Доменная сущность с закрытыми полями.

    Подчёркивание в именах не для красоты: с открытыми полями любой модуль
    пишет Task(...) напрямую или task.title = "", и тогда утверждение
    «невалидный Task создать нельзя» становится неправдой - валидация
    в create просто обходится. В языке это соглашение, а не замок,
    но ревью и линтер такие обращения ловят.
    """

    __slots__ = (
        "_id", "_user_id", "_title", "_description",
        "_completed", "_created_at", "_completed_at",
    )

    # Конструктор напрямую не вызывают: единственные точки входа - create и from_storage.
    def __init__(
        self,
        task_id: str,
        user_id: str,
        title: str,
        description: str,
        completed: bool,
        created_at: datetime,
        completed_at: datetime | None,
    ) -> None:
        self._id = task_id
        self._user_id = user_id
        self._title = title
        self._description = description
        self._completed = completed
        self._created_at = created_at
        self._completed_at = completed_at

    # Геттеры: наружу отдаём значения, менять состояние можно только методами ниже.
    @property
    def id(self) -> str:
        return self._id

    @property
    def user_id(self) -> str:
        return self._user_id

    @property
    def title(self) -> str:
        return self._title

    @property
    def description(self) -> str:
        return self._description

    @property
    def completed(self) -> bool:
        return self._completed

    @property
    def created_at(self) -> datetime:
        return self._created_at

    @property
    def completed_at(self) -> datetime | None:
        return self._completed_at

    @classmethod
    def create(cls, user_id: str, title: str, description: str) -> Task:
        """Создаёт задачу с валидацией."""
        if not user_id:
            raise InvalidUserIdError()
        if not title or len(title) > 200:
            raise InvalidTitleError()

        return cls(
            task_id=str(uuid.uuid4()),
            user_id=user_id,
            title=title,
            description=description,
            completed=False,
            created_at=datetime.now(timezone.utc),
            completed_at=None,
        )

    @classmethod
    def from_storage(
        cls,
        task_id: str,
        user_id: str,
        title: str,
        description: str,
        completed: bool,
        created_at: datetime,
        completed_at: datetime | None,
    ) -> Task:
        """Восстанавливает задачу из строки БД.

        Отдельная точка входа нужна потому, что адаптер не должен собирать
        сущность в обход create. Но «отдельная точка входа» не значит
        «дыра в инвариантах»: если сюда можно передать что угодно, проблема
        просто переехала из конструктора в вызов этого метода.

        Политика такая:

          - структурные инварианты проверяем всегда (пустой task_id, пустой
            user_id, пустой или слишком длинный title). Их нарушение означает,
            что в базе лежит мусор, и тащить его в домен нельзя - лучше явная
            ошибка на чтении, чем непонятное поведение через три слоя;
          - остальное считаем доверенным состоянием: время создания, флаг
            выполнения и завершения пришли из нашей же записи, повторно
            их «бизнес-проверять» бессмысленно. Например, задача может быть
            completed - через create такую не создать, и это нормально:
            это результат вызова complete() когда-то раньше.

        Что делать с уже испорченными строками, если они есть: чинить их
        миграцией, а не ослаблять проверку. Ошибка на чтении покажет, сколько
        таких строк и где.
        """
        if not task_id or not user_id:
            raise CorruptedTaskError(task_id)
        if not title or len(title) > 200:
            raise CorruptedTaskError(task_id)

        return cls(
            task_id=task_id,
            user_id=user_id,
            title=title,
            description=description,
            completed=completed,
            created_at=created_at,
            completed_at=completed_at,
        )

    def complete(self) -> None:
        """Отмечает задачу выполненной."""
        if self._completed:
            raise TaskAlreadyCompletedError()
        self._completed = True
        self._completed_at = datetime.now(timezone.utc)

    def complete_by(self, user_id: str) -> None:
        """«Чужую задачу завершить нельзя» - доменное правило, поэтому оно здесь."""
        if self._user_id != user_id:
            raise AccessDeniedError()
        self.complete()

    def set_title(self, title: str) -> None:
        """Обновляет заголовок с валидацией."""
        if not title or len(title) > 200:
            raise InvalidTitleError()
        self._title = title
# tasks_api/domain/errors.py


class TaskError(Exception):
    """Корень доменных ошибок: адаптеры ловят его одним except."""


class TaskNotFoundError(TaskError):
    def __init__(self) -> None:
        super().__init__("task not found")


class TaskAlreadyCompletedError(TaskError):
    def __init__(self) -> None:
        super().__init__("task already completed")


class InvalidTitleError(TaskError):
    def __init__(self) -> None:
        super().__init__("invalid title: must be 1-200 characters")


class InvalidUserIdError(TaskError):
    def __init__(self) -> None:
        super().__init__("invalid user ID")


class CorruptedTaskError(TaskError):
    """Строка в базе не проходит структурные инварианты.

    Отдельная ошибка, потому что причина другая: не пользователь ошибся,
    а данные повреждены. Наружу это 500, а не 400.
    """

    def __init__(self, task_id: str) -> None:
        super().__init__(f"corrupted task in storage: id={task_id}")


class AccessDeniedError(TaskError):
    def __init__(self) -> None:
        super().__init__("access denied")

Вся бизнес-логика - внутри методов entity. NewTask гарантирует, что невалидный Task не может быть создан. Complete() защищает инвариант «нельзя завершить дважды».

⚠️ Почему поля закрыты - и куда переехала бы проблема, если закрыть их наивно

Если бы поля Task были экспортированы, утверждение выше было бы неправдой: domain.Task{Title: ""} собирается, а t.Completed = true обходит Complete() вместе с проверкой «нельзя завершить дважды». Валидация в конструкторе защищает ровно до тех пор, пока конструктор - единственный путь. Поэтому поля закрыты, как и приватный конструктор в PHP-версии.

Но закрыть поля - это только половина. Адаптеру БД надо как-то собрать объект из строки, и если сделать для этого функцию, принимающую что угодно, проблема просто переедет: вместо литерала структуры инварианты будут обходить через TaskFromStorage(...).

Поэтому у восстановления есть явная политика, и она написана рядом с функцией:

ЧтоКак обрабатываетсяПочему
пустой id, userID, title; слишком длинный titleошибка ErrCorruptedTaskэто не бизнес-случай, а повреждённые данные; тащить их в домен хуже, чем упасть на чтении
completed, completedAt, createdAtпринимаются как естьдоверенное состояние: результат вызовов, которые уже прошли валидацию раньше

Обратите внимание на вторую строку: через NewTask завершённую задачу создать нельзя, а TaskFromStorage её принимает - и это правильно. Восстановление воспроизводит прошлое состояние, а не создаёт новое. Требовать от него бизнес-правил создания значит запретить читать из базы всё, что было изменено после создания.

Что делать с уже испорченными строками в существующей базе: чинить миграцией, а не ослаблять проверку. Ошибка на чтении хотя бы покажет, сколько их и где.

Task здесь - сущность: у неё есть идентификатор и жизненный цикл, а два разных Task с одинаковым заголовком остаются разными задачами. Если захочется усилить модель и вынести, скажем, заголовок в самовалидирующийся тип вместо string, начни с урока Entity и Value Object. А само слово «инвариант» и приёмы его защиты (приватные поля, единственная точка входа для изменений) разобраны в уроке Aggregates и инварианты.

Порты: интерфейсы

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

import (
    "context"

    "tasks-api/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
}
// internal/usecase/ports/notifier.go
package ports

import "context"

type TaskNotifier interface {
    TaskCompleted(ctx context.Context, userID, taskTitle 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;
}
<?php
// src/Application/Port/TaskNotifierPort.php
declare(strict_types=1);

namespace App\Application\Port;

interface TaskNotifierPort
{
    public function taskCompleted(string $userId, string $taskTitle): void;
}
# tasks_api/usecase/ports/task_repo.py
from typing import Protocol

from tasks_api 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: ...
# tasks_api/usecase/ports/notifier.py
from typing import Protocol


class TaskNotifier(Protocol):
    def task_completed(self, user_id: str, task_title: str) -> None: ...

Два порта - два контракта. Репозиторий для persistence, notifier для side-effect (email, push, webhook). Use-case зависит от обоих через интерфейсы. Обрати внимание, что оба интерфейса лежат в usecase/ports/, а не рядом с реализациями: почему размещение интерфейса определяет направление зависимостей, разобрано в уроке Репозитории и интерфейсы.

Use-cases

CreateTask

// internal/usecase/create_task.go
package usecase

import (
    "context"

    "tasks-api/internal/domain"
    "tasks-api/internal/usecase/ports"
)

type CreateTaskInput struct {
    UserID      string
    Title       string
    Description string
}

type CreateTask struct {
    repo ports.TaskRepository
}

func NewCreateTask(repo ports.TaskRepository) *CreateTask {
    return &CreateTask{repo: repo}
}

func (uc *CreateTask) Execute(ctx context.Context, in CreateTaskInput) (domain.Task, error) {
    task, err := domain.NewTask(in.UserID, in.Title, in.Description)
    if err != nil {
        return domain.Task{}, err
    }

    if err := uc.repo.Create(ctx, task); err != nil {
        return domain.Task{}, err
    }
    return task, nil
}
<?php
// src/Application/UseCase/CreateTaskUseCase.php
declare(strict_types=1);

namespace App\Application\UseCase;

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

final readonly class CreateTaskInput
{
    public function __construct(
        public string $userId,
        public string $title,
        public string $description,
    ) {}
}

final class CreateTaskUseCase
{
    public function __construct(
        private readonly TaskRepositoryPort $tasks,
    ) {}

    public function execute(CreateTaskInput $in): Task
    {
        $task = Task::create($in->userId, $in->title, $in->description);
        $this->tasks->create($task);
        return $task;
    }
}
# tasks_api/usecase/create_task.py
from dataclasses import dataclass

from tasks_api import domain
from tasks_api.usecase.ports import TaskRepository


@dataclass(frozen=True, slots=True)
class CreateTaskInput:
    user_id: str
    title: str
    description: str = ""


class CreateTask:
    def __init__(self, repo: TaskRepository) -> None:
        self._repo = repo

    def execute(self, inp: CreateTaskInput) -> domain.Task:
        task = domain.Task.create(inp.user_id, inp.title, inp.description)
        self._repo.create(task)
        return task

CompleteTask

// internal/usecase/complete_task.go
package usecase

import (
    "context"
    "log/slog"

    "tasks-api/internal/usecase/ports"
)

type CompleteTask struct {
    repo     ports.TaskRepository
    notifier ports.TaskNotifier
}

func NewCompleteTask(repo ports.TaskRepository, notifier ports.TaskNotifier) *CompleteTask {
    return &CompleteTask{repo: repo, notifier: notifier}
}

func (uc *CompleteTask) Execute(ctx context.Context, taskID, userID string) error {
    task, err := uc.repo.GetByID(ctx, taskID)
    if err != nil {
        return err
    }

    // Проверка владельца - доменное правило, его держит сущность.
    if err := task.CompleteBy(userID); err != nil {
        return err
    }

    if err := uc.repo.Update(ctx, task); err != nil {
        return err
    }

    // Side-effect не блокирует операцию, но и не исчезает бесследно:
    // молча проглоченная ошибка - это отключённое уведомление, о котором
    // никто не узнает.
    if err := uc.notifier.TaskCompleted(ctx, userID, task.Title()); err != nil {
        slog.ErrorContext(ctx, "task completion notification failed",
            slog.String("task_id", taskID),
            slog.String("user_id", userID),
            slog.String("err", err.Error()),
        )
    }

    return nil
}
<?php
// src/Application/UseCase/CompleteTaskUseCase.php
declare(strict_types=1);

namespace App\Application\UseCase;

use App\Application\Port\TaskNotifierPort;
use App\Application\Port\TaskRepositoryPort;
use Throwable;

final class CompleteTaskUseCase
{
    public function __construct(
        private readonly TaskRepositoryPort $tasks,
        private readonly TaskNotifierPort $notifier,
    ) {}

    public function execute(string $taskId, string $userId): void
    {
        $task = $this->tasks->getById($taskId);

        // Проверка владельца - доменное правило, его держит сущность.
        $task->completeBy($userId);
        $this->tasks->update($task);

        try {
            $this->notifier->taskCompleted($userId, $task->title());
        } catch (Throwable) {
            // Side-effect не блокирует операцию. Молча глотать ошибку плохо:
            // в настоящем проекте её пишет в лог декоратор LoggingNotifier (см. ниже)
        }
    }
}
# tasks_api/usecase/complete_task.py
import logging

from tasks_api import domain
from tasks_api.usecase.ports import TaskNotifier, TaskRepository

log = logging.getLogger(__name__)


class CompleteTask:
    def __init__(self, repo: TaskRepository, notifier: TaskNotifier) -> None:
        self._repo = repo
        self._notifier = notifier

    def execute(self, task_id: str, user_id: str) -> None:
        task = self._repo.get_by_id(task_id)

        # Проверка владельца - доменное правило, его держит сущность.
        task.complete_by(user_id)
        self._repo.update(task)

        # Side-effect не блокирует операцию, но и не исчезает бесследно:
        # молча проглоченное исключение - это отключённое уведомление,
        # о котором никто не узнает. extra уходит в поля записи лога.
        try:
            self._notifier.task_completed(user_id, task.title)
        except Exception as err:
            log.error(
                "task completion notification failed",
                extra={"task_id": task_id, "user_id": user_id, "err": str(err)},
            )

ℹ️ Почему здесь use-case пишет в лог

Это сознательное исключение из правила «Не логируй в use-case» из урока Use cases. Ошибку уведомления сценарий не возвращает: задача уже завершена и сохранена, и откатывать бизнес-операцию из-за письма нельзя. Значит, handler о ней не узнает, и залогировать её больше негде. Если хочется держать use-case совсем чистым, логирование выносят в адаптер: декоратор LoggingNotifier оборачивает настоящий нотификатор и пишет в лог его ошибку, а сценарий просто игнорирует ошибку side-effect.

ListTasks

// internal/usecase/list_tasks.go
package usecase

import (
    "context"

    "tasks-api/internal/domain"
    "tasks-api/internal/usecase/ports"
)

type ListTasks struct {
    repo ports.TaskRepository
}

func NewListTasks(repo ports.TaskRepository) *ListTasks {
    return &ListTasks{repo: repo}
}

func (uc *ListTasks) Execute(ctx context.Context, userID string) ([]domain.Task, error) {
    return uc.repo.ListByUser(ctx, userID)
}
<?php
// src/Application/UseCase/ListTasksUseCase.php
declare(strict_types=1);

namespace App\Application\UseCase;

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

final class ListTasksUseCase
{
    public function __construct(
        private readonly TaskRepositoryPort $tasks,
    ) {}

    /** @return list<Task> */
    public function execute(string $userId): array
    {
        return $this->tasks->listByUser($userId);
    }
}
# tasks_api/usecase/list_tasks.py
from tasks_api import domain
from tasks_api.usecase.ports import TaskRepository


class ListTasks:
    def __init__(self, repo: TaskRepository) -> None:
        self._repo = repo

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

ListTasks получился в одну строку, и это нормально: сценарию нечего решать, он просто делегирует репозиторию. Толстеть use-case начинает, когда в Execute заводятся расчёты вместо вызовов - признаки такого перерождения и порог «40-50 строк» описаны в уроке Use Case: сценарии вместо «толстых сервисов».

Адаптеры

InMemoryTaskRepo

Хранилище в памяти - map под sync.RWMutex: чтения (GetByID, ListByUser) берут RLock и идут параллельно, записи берут Lock и выполняются по одной. Без замка одновременные запросы к серверу писали бы в map из разных горутин, и программа упала бы; зачем это и как ловить гонки флагом -race, разобрано во врезке урока Репозитории и интерфейсы.

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

import (
    "context"
    "sync"

    "tasks-api/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)
        }
    }
    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
}
<?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 на входе и выходе обязателен (см. урок про тестирование):
    // без него мутация задачи «сохранялась» бы без вызова update(),
    // и тест, забывший update(), прошёл бы, а в проде задача не сохранилась бы.
    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;
            }
        }
        return $result;
    }

    public function update(Task $task): void
    {
        if (!isset($this->store[$task->id()])) {
            throw TaskError::notFound();
        }
        $this->store[$task->id()] = clone $task;
    }
}
# tasks_api/adapters/inmemory/task_repo.py
import copy
import threading

from tasks_api import domain


class InMemoryTaskRepo:
    def __init__(self) -> None:
        # RWMutex в stdlib нет; под GIL достаточно обычного Lock.
        self._lock = threading.Lock()
        self._store: dict[str, domain.Task] = {}

    # Копируем на входе и на выходе: Go-версия хранит значения, здесь
    # объекты живут по ссылке, и без copy мутация домена «сохранялась» бы
    # без вызова update.
    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:
            return [copy.copy(t) for t in self._store.values() if t.user_id == user_id]

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

HTTP Handler

// internal/adapters/http/handler.go
package http

import (
    "context"
    "encoding/json"
    "net/http"
    "time"

    "github.com/go-chi/chi/v5"

    "tasks-api/internal/domain"
    "tasks-api/internal/usecase"
)

type TaskHandler struct {
    create   *usecase.CreateTask
    complete *usecase.CompleteTask
    list     *usecase.ListTasks
}

func NewTaskHandler(c *usecase.CreateTask, comp *usecase.CompleteTask, l *usecase.ListTasks) *TaskHandler {
    return &TaskHandler{create: c, complete: comp, list: l}
}

func (h *TaskHandler) Routes(r chi.Router) {
    r.Group(func(r chi.Router) {
        r.Use(WithUserID)
        r.Post("/tasks", h.CreateTask)
        r.Post("/tasks/{id}/complete", h.CompleteTask)
        r.Get("/tasks", h.ListTasks)
    })
}

// userIDKey - ключ контекста собственного типа. Строковый ключ "userID"
// может совпасть с ключом из любого другого пакета; staticcheck (правило SA1029) на такой ключ ругается.
type userIDKey struct{}

// WithUserID - учебная аутентификация: ID пользователя берётся из заголовка
// X-User-ID. В настоящем сервисе на этом месте JWT-middleware; handler-ам всё
// равно, откуда ID взялся, - они читают его из контекста.
func WithUserID(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        id := r.Header.Get("X-User-ID")
        if id == "" {
            writeError(w, http.StatusUnauthorized, "X-User-ID header is required")
            return
        }
        next.ServeHTTP(w, r.WithContext(context.WithValue(r.Context(), userIDKey{}, id)))
    })
}

// userIDFrom - чтение с comma-ok: если middleware не подключили, handler
// ответит 401, а не упадёт с паникой на утверждении типа.
func userIDFrom(r *http.Request) (string, bool) {
    id, ok := r.Context().Value(userIDKey{}).(string)
    return id, ok && id != ""
}

// taskResponse - то, что уходит клиенту. domain.Task отдавать нельзя: поля
// у него закрытые, и encoding/json вернул бы {}. Да и правило из урока про
// DTO то же самое: наружу - только Response DTO.
type taskResponse struct {
    ID          string     `json:"id"`
    Title       string     `json:"title"`
    Description string     `json:"description"`
    Completed   bool       `json:"completed"`
    CreatedAt   time.Time  `json:"created_at"`
    CompletedAt *time.Time `json:"completed_at,omitempty"`
}

func toTaskResponse(t domain.Task) taskResponse {
    return taskResponse{
        ID:          t.ID(),
        Title:       t.Title(),
        Description: t.Description(),
        Completed:   t.Completed(),
        CreatedAt:   t.CreatedAt(),
        CompletedAt: t.CompletedAt(),
    }
}

func (h *TaskHandler) CreateTask(w http.ResponseWriter, r *http.Request) {
    var req struct {
        Title       string `json:"title"`
        Description string `json:"description"`
    }
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        writeError(w, http.StatusBadRequest, "invalid JSON")
        return
    }

    userID, ok := userIDFrom(r)
    if !ok {
        writeError(w, http.StatusUnauthorized, "unauthenticated")
        return
    }

    task, err := h.create.Execute(r.Context(), usecase.CreateTaskInput{
        UserID:      userID,
        Title:       req.Title,
        Description: req.Description,
    })
    if err != nil {
        mapError(w, err)
        return
    }

    writeJSON(w, http.StatusCreated, toTaskResponse(task))
}

func (h *TaskHandler) CompleteTask(w http.ResponseWriter, r *http.Request) {
    taskID := chi.URLParam(r, "id")
    userID, ok := userIDFrom(r)
    if !ok {
        writeError(w, http.StatusUnauthorized, "unauthenticated")
        return
    }

    if err := h.complete.Execute(r.Context(), taskID, userID); err != nil {
        mapError(w, err)
        return
    }
    w.WriteHeader(http.StatusNoContent)
}

func (h *TaskHandler) ListTasks(w http.ResponseWriter, r *http.Request) {
    userID, ok := userIDFrom(r)
    if !ok {
        writeError(w, http.StatusUnauthorized, "unauthenticated")
        return
    }
    tasks, err := h.list.Execute(r.Context(), userID)
    if err != nil {
        mapError(w, err)
        return
    }
    resp := make([]taskResponse, 0, len(tasks)) // пустой список - [], а не null
    for _, t := range tasks {
        resp = append(resp, toTaskResponse(t))
    }
    writeJSON(w, http.StatusOK, resp)
}
<?php
// src/Infrastructure/Http/Controller/TaskController.php
declare(strict_types=1);

namespace App\Infrastructure\Http\Controller;

use App\Application\UseCase\CompleteTaskUseCase;
use App\Application\UseCase\CreateTaskInput;
use App\Application\UseCase\CreateTaskUseCase;
use App\Application\UseCase\ListTasksUseCase;
use App\Domain\TaskError;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class TaskController
{
    public function __construct(
        private readonly CreateTaskUseCase $create,
        private readonly CompleteTaskUseCase $complete,
        private readonly ListTasksUseCase $list,
    ) {}

    #[Route('/tasks', methods: ['POST'])]
    public function createTask(Request $request): JsonResponse
    {
        $payload = json_decode($request->getContent(), true);
        if (!is_array($payload)) {
            return new JsonResponse(['error' => 'invalid JSON'], 400);
        }

        $userId = (string) $request->attributes->get('userId');

        try {
            $task = $this->create->execute(new CreateTaskInput(
                userId: $userId,
                title: (string) ($payload['title'] ?? ''),
                description: (string) ($payload['description'] ?? ''),
            ));
        } catch (TaskError $e) {
            return $this->mapError($e);
        }

        return new JsonResponse([
            'id' => $task->id(),
            'title' => $task->title(),
            'completed' => $task->isCompleted(),
        ], 201);
    }

    #[Route('/tasks/{id}/complete', methods: ['POST'])]
    public function completeTask(string $id, Request $request): Response
    {
        $userId = (string) $request->attributes->get('userId');

        try {
            $this->complete->execute($id, $userId);
        } catch (TaskError $e) {
            return $this->mapError($e);
        }

        return new Response(status: 204);
    }

    #[Route('/tasks', methods: ['GET'])]
    public function listTasks(Request $request): JsonResponse
    {
        $userId = (string) $request->attributes->get('userId');
        $tasks = $this->list->execute($userId);

        return new JsonResponse(array_map(
            static fn ($task) => [
                'id' => $task->id(),
                'title' => $task->title(),
                'completed' => $task->isCompleted(),
            ],
            $tasks,
        ));
    }

    private function mapError(TaskError $e): JsonResponse
    {
        // Маппинг по виду ошибки, а не по тексту сообщения
        $status = match ($e->kind) {
            TaskError::NOT_FOUND => 404,
            TaskError::ACCESS_DENIED => 403,
            TaskError::ALREADY_COMPLETED => 409,
            TaskError::INVALID_TITLE, TaskError::INVALID_USER_ID => 400,
            default => 500, // corrupted: данные повреждены, клиент не виноват
        };
        $message = $status === 500 ? 'internal error' : $e->getMessage();
        return new JsonResponse(['error' => $message], $status);
    }
}
# tasks_api/adapters/http/handler.py
#
# Фреймворк-независимый адаптер: Request и Response - простые dataclass'ы
# (лежат в response.py ниже), обработчики - функции «запрос на входе,
# ответ на выходе». В FastAPI их место занимают fastapi.Request / Response
# и APIRouter, в Django - HttpRequest / JsonResponse и urls.py; сами
# обработчики при этом не меняются.
import json
from typing import Any, Callable, Protocol

from tasks_api import domain
from tasks_api.adapters.http.response import Request, Response, map_error, write_error, write_json
from tasks_api.usecase import CompleteTask, CreateTask, CreateTaskInput, ListTasks

Handler = Callable[[Request], Response]


class Router(Protocol):
    # Регистрация маршрутов; реализация - любая. В FastAPI это
    # APIRouter.add_api_route(path, handler, methods=[...]).
    def post(self, path: str, handler: Handler) -> None: ...

    def get(self, path: str, handler: Handler) -> None: ...


class TaskHandler:
    def __init__(self, create: CreateTask, complete: CompleteTask, list_tasks: ListTasks) -> None:
        self._create = create
        self._complete = complete
        self._list = list_tasks

    def routes(self, router: Router) -> None:
        router.post("/tasks", self.create_task)
        router.post("/tasks/{id}/complete", self.complete_task)
        router.get("/tasks", self.list_tasks)

    def create_task(self, request: Request) -> Response:
        try:
            payload = json.loads(request.body)
        except ValueError:
            payload = None
        if not isinstance(payload, dict):
            return write_error(400, "invalid JSON")

        user_id: str = request.state["user_id"]

        # Любая ошибка уходит в map_error, как в Go-версии: доменные - в 4xx,
        # остальные - в 500.
        try:
            task = self._create.execute(CreateTaskInput(
                user_id=user_id,
                title=str(payload.get("title", "")),
                description=str(payload.get("description", "")),
            ))
        except Exception as err:
            return map_error(err)

        return write_json(201, task_to_dict(task))

    def complete_task(self, request: Request) -> Response:
        task_id = request.path_params["id"]
        user_id: str = request.state["user_id"]

        try:
            self._complete.execute(task_id, user_id)
        except Exception as err:
            return map_error(err)
        return Response(status=204)

    def list_tasks(self, request: Request) -> Response:
        user_id: str = request.state["user_id"]
        try:
            tasks = self._list.execute(user_id)
        except Exception as err:
            return map_error(err)
        return write_json(200, [task_to_dict(t) for t in tasks])


def task_to_dict(task: domain.Task) -> dict[str, Any]:
    return {"id": task.id, "title": task.title, "completed": task.completed}

Откуда handler знает пользователя: middleware WithUserID кладёт ID в контекст, handler читает его через userIDFrom с проверкой ok. Здесь ID берётся из заголовка X-User-ID - это учебная заглушка, в настоящем сервисе на этом месте проверка токена (как она устроена, в уроке Основы аутентификации и авторизации). Handler от этой замены не меняется; в PHP-версии ту же роль играет DemoAuthListener, в Python - auth_middleware (оба - в разделе «Сборка» ниже). И наружу уходит taskResponse, а не domain.Task: у сущности закрытые поля, encoding/json их не видит и вернул бы {}.

⚠️ mapError - единственное место маппинга

Все доменные ошибки маппятся в HTTP-статусы в одной функции. Не разбрасывай switch err по handler-ам - потеряешь контроль.

// internal/adapters/http/response.go
package http

import (
    "encoding/json"
    "errors"
    "net/http"

    "tasks-api/internal/domain"
)

func mapError(w http.ResponseWriter, err error) {
    switch {
    case errors.Is(err, domain.ErrTaskNotFound):
        writeError(w, http.StatusNotFound, "task not found")
    case errors.Is(err, domain.ErrInvalidTitle),
        errors.Is(err, domain.ErrInvalidUserID):
        writeError(w, http.StatusBadRequest, err.Error())
    case errors.Is(err, domain.ErrTaskAlreadyCompleted):
        writeError(w, http.StatusConflict, err.Error())
    case errors.Is(err, domain.ErrAccessDenied):
        writeError(w, http.StatusForbidden, "access denied")
    default:
        writeError(w, http.StatusInternalServerError, "internal error")
    }
}

func writeJSON(w http.ResponseWriter, status int, data any) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    _ = json.NewEncoder(w).Encode(data)
}

func writeError(w http.ResponseWriter, status int, msg string) {
    writeJSON(w, status, map[string]string{"error": msg})
}
<?php
// src/Infrastructure/Http/EventListener/TaskExceptionListener.php
// Глобальный маппинг доменных исключений → HTTP-статусы в одном месте
declare(strict_types=1);

namespace App\Infrastructure\Http\EventListener;

use App\Domain\TaskError;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpKernel\Event\ExceptionEvent;
use Psr\Log\LoggerInterface;

#[AsEventListener]
final class TaskExceptionListener
{
    public function __construct(
        private readonly LoggerInterface $logger,
    ) {}

    public function __invoke(ExceptionEvent $event): void
    {
        $e = $event->getThrowable();

        // Маппинг по виду ошибки, а не по тексту сообщения. corrupted
        // проваливается ниже, в 500: данные повреждены, клиент не виноват.
        $status = $e instanceof TaskError ? match ($e->kind) {
            TaskError::NOT_FOUND => 404,
            TaskError::ACCESS_DENIED => 403,
            TaskError::ALREADY_COMPLETED => 409,
            TaskError::INVALID_TITLE, TaskError::INVALID_USER_ID => 400,
            default => null,
        } : null;
        if ($status !== null) {
            $event->setResponse(new JsonResponse(['error' => $e->getMessage()], $status));
            return;
        }

        // Неизвестное исключение - 500, детали в лог
        $this->logger->error('unhandled exception', ['exception' => $e]);
        $event->setResponse(new JsonResponse(['error' => 'internal error'], 500));
    }
}
# tasks_api/adapters/http/response.py
#
# Транспортные структуры и JSON-хелперы. В FastAPI map_error превращается
# в @app.exception_handler(TaskError) - один обработчик на все доменные ошибки.
import json
import logging
from dataclasses import dataclass, field
from typing import Any

from tasks_api import domain

log = logging.getLogger(__name__)


@dataclass
class Request:
    body: bytes = b""
    path_params: dict[str, str] = field(default_factory=dict)
    headers: dict[str, str] = field(default_factory=dict)
    # Сюда middleware кладёт user_id - аналог context.Value в Go.
    state: dict[str, Any] = field(default_factory=dict)


@dataclass
class Response:
    status: int
    body: bytes = b""
    headers: dict[str, str] = field(default_factory=dict)


def map_error(err: Exception) -> Response:
    match err:
        case domain.TaskNotFoundError():
            return write_error(404, "task not found")
        case domain.InvalidTitleError() | domain.InvalidUserIdError():
            return write_error(400, str(err))
        case domain.TaskAlreadyCompletedError():
            return write_error(409, str(err))
        case domain.AccessDeniedError():
            return write_error(403, "access denied")
        case _:
            # Неизвестная ошибка - 500, детали в лог, не в ответ.
            log.error("unhandled error", extra={"err": str(err)})
            return write_error(500, "internal error")


def write_json(status: int, data: Any) -> Response:
    return Response(
        status=status,
        body=json.dumps(data, ensure_ascii=False).encode(),
        headers={"Content-Type": "application/json"},
    )


def write_error(status: int, msg: str) -> Response:
    return write_json(status, {"error": msg})

Сборка: main.go

// cmd/server/main.go
package main

import (
    "context"
    "log/slog"
    "net/http"
    "os"

    "github.com/go-chi/chi/v5"
    "github.com/go-chi/chi/v5/middleware"
    adapter "tasks-api/internal/adapters/http"
    "tasks-api/internal/adapters/inmemory"
    "tasks-api/internal/usecase"
)

func main() {
    logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
    slog.SetDefault(logger)

    // Adapters
    taskRepo := inmemory.NewTaskRepo()
    notifier := &LogNotifier{} // заглушка

    // Use-cases
    createTask := usecase.NewCreateTask(taskRepo)
    completeTask := usecase.NewCompleteTask(taskRepo, notifier)
    listTasks := usecase.NewListTasks(taskRepo)

    // HTTP
    handler := adapter.NewTaskHandler(createTask, completeTask, listTasks)

    r := chi.NewRouter()
    r.Use(middleware.Logger)
    r.Use(middleware.Recoverer)
    r.Route("/api", func(r chi.Router) {
        handler.Routes(r)
    })

    slog.Info("server starting", slog.String("addr", ":8080"))
    if err := http.ListenAndServe(":8080", r); err != nil {
        slog.Error("server failed", slog.String("err", err.Error()))
        os.Exit(1)
    }
}

// LogNotifier - заглушка для TaskNotifier.
type LogNotifier struct{}

func (n *LogNotifier) TaskCompleted(_ context.Context, userID, title string) error {
    slog.Info("task completed",
        slog.String("userID", userID),
        slog.String("title", title),
    )
    return nil
}
<?php
// src/Infrastructure/Notifier/LogNotifier.php - заглушка для TaskNotifierPort
declare(strict_types=1);

namespace App\Infrastructure\Notifier;

use App\Application\Port\TaskNotifierPort;
use Psr\Log\LoggerInterface;

final class LogNotifier implements TaskNotifierPort
{
    public function __construct(
        private readonly LoggerInterface $logger,
    ) {}

    public function taskCompleted(string $userId, string $taskTitle): void
    {
        $this->logger->info('task completed', [
            'userId' => $userId,
            'title' => $taskTitle,
        ]);
    }
}
<?php
// src/Infrastructure/Http/DemoAuthListener.php
declare(strict_types=1);

namespace App\Infrastructure\Http;

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpKernel\Event\RequestEvent;

// Учебная аутентификация: userId из заголовка X-User-ID кладётся в атрибуты
// запроса, откуда его читает TaskController. В настоящем сервисе на этом месте
// Symfony Security с JWT - контроллеру всё равно, откуда userId взялся.
#[AsEventListener(event: 'kernel.request')]
final class DemoAuthListener
{
    public function __invoke(RequestEvent $event): void
    {
        $request = $event->getRequest();
        if (!str_starts_with($request->getPathInfo(), '/api/')) {
            return;
        }
        $userId = (string) $request->headers->get('X-User-ID', '');
        if ($userId === '') {
            $event->setResponse(new JsonResponse(['error' => 'X-User-ID header is required'], 401));
            return;
        }
        $request->attributes->set('userId', $userId);
    }
}
# tasks_api/__main__.py - точка входа: python -m tasks_api
import logging
import sys

from tasks_api.adapters.http import TaskHandler
from tasks_api.adapters.http.handler import Handler
from tasks_api.adapters.http.response import Request, Response, write_error
from tasks_api.adapters.http.router import Router, logging_middleware, recover_middleware, serve
from tasks_api.adapters.inmemory import InMemoryTaskRepo
from tasks_api.usecase import CompleteTask, CreateTask, ListTasks

log = logging.getLogger("tasks_api")


def main() -> None:
    # JSON-строки средствами stdlib logging; вложенные поля из extra
    # даст свой Formatter или structlog.
    logging.basicConfig(
        level=logging.INFO,
        stream=sys.stdout,
        format='{"time": "%(asctime)s", "level": "%(levelname)s", "msg": "%(message)s"}',
    )

    # Adapters
    task_repo = InMemoryTaskRepo()
    notifier = LogNotifier()  # заглушка

    # Use-cases
    create_task = CreateTask(task_repo)
    complete_task = CompleteTask(task_repo, notifier)
    list_tasks = ListTasks(task_repo)

    # HTTP
    handler = TaskHandler(create_task, complete_task, list_tasks)

    # Router и serve - тонкая обвязка над wsgiref в adapters/http/router.py:
    # диспетчеризация по методу и пути, цепочка middleware, перевод WSGI
    # environ в Request и Response обратно. В FastAPI её заменяют
    # APIRouter(prefix="/api") и uvicorn.run(app).
    router = Router(prefix="/api", middlewares=[logging_middleware, recover_middleware, auth_middleware])
    handler.routes(router)

    log.info("server starting", extra={"addr": ":8080"})
    serve(router, port=8080)


def auth_middleware(next_handler: Handler) -> Handler:
    """Учебная аутентификация: user_id из заголовка X-User-ID кладётся в
    request.state, откуда его читает TaskHandler. В настоящем сервисе на этом
    месте проверка JWT - обработчикам всё равно, откуда user_id взялся."""

    def handle(request: Request) -> Response:
        user_id = next((v for k, v in request.headers.items() if k.lower() == "x-user-id"), "")
        if not user_id:
            return write_error(401, "X-User-ID header is required")
        request.state["user_id"] = user_id
        return next_handler(request)

    return handle


class LogNotifier:
    """Заглушка для TaskNotifier."""

    def task_completed(self, user_id: str, title: str) -> None:
        log.info("task completed", extra={"user_id": user_id, "title": title})


if __name__ == "__main__":
    main()

В Symfony сборка зависимостей описывается декларативно в config/services.yaml - autowiring находит конструкторы и подставляет реализации по типу:

# config/services.yaml
services:
    _defaults:
        autowire: true
        autoconfigure: true

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

    # Связываем порты с реализациями (Domain/Application видит только интерфейсы)
    App\Application\Port\TaskRepositoryPort:
        alias: App\Infrastructure\Persistence\InMemory\InMemoryTaskRepository

    App\Application\Port\TaskNotifierPort:
        alias: App\Infrastructure\Notifier\LogNotifier

Вся сборка - в main.go / config/services.yaml. Такое место называют composition root (корень сборки): только здесь создаются конкретные реализации и передаются в конструкторы. Ни один внутренний пакет не знает о других адаптерах. Чтобы переключиться с in-memory на Doctrine - меняется одна строка в services.yaml, use-case и тесты остаются как есть.

Как запустить

# Инициализация модуля
go mod init tasks-api
go mod tidy

# Запуск
go run ./cmd/server/

# Проверка: X-User-ID - учебная замена токена (см. WithUserID в handler.go)
curl -X POST http://localhost:8080/api/tasks \
 -H "Content-Type: application/json" \
 -H "X-User-ID: user-1" \
 -d '{"title": "Изучить hex-arch", "description": "Разобраться с портами и адаптерами"}'

curl http://localhost:8080/api/tasks -H "X-User-ID: user-1"

# Без заголовка - 401, а не паника
curl -i http://localhost:8080/api/tasks

Чек-лист перед «отправкой»

Пройдись по проекту и проверь каждый пункт:

  • domain/ не импортирует инфраструктуру (драйверы БД, net/http, chi); допустимы stdlib и небольшие чистые библиотеки вроде github.com/google/uuid
  • usecase/ импортирует только domain и usecase/ports - никаких database/sql, net/http, chi
  • adapters/postgres/ импортирует domain и usecase/ports, но не adapters/http
  • adapters/http/ импортирует domain и usecase, но не adapters/postgres
  • Все доменные ошибки определены в domain/errors.go
  • Handler не содержит бизнес-логики (нет if task.Completed(), нет прямого вызова repo)
  • InMemoryRepo проходит те же тесты, что и PostgresRepo (одинаковый интерфейс)
  • Тесты use-case запускаются без Docker, без БД, за миллисекунды

ℹ️ Следующий шаг

Замени создание репозитория в main.go: вместо inmemory.NewTaskRepo() создай пул pgxpool и передай его в postgres.NewTaskRepo(pool) (код адаптера - в уроке Репозитории и интерфейсы) - и проект работает с реальной базой. Ни один use-case и ни один тест не изменится. Это и есть гексагональная архитектура в действии.

Тесты к этим сценариям пишутся на InMemoryTaskRepo, без Docker и миграций; table-driven шаблон и правило «фейк для репозитория, мок для side-effect» - в уроке Тестирование use-case без базы данных. Дальше домен можно усилить: вместо плоской структуры Task завести объекты-значения, агрегат с дочерними объектами и доменные события. Тот же путь пройден на более богатой модели в мини-проекте трека ddd-lite.

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

  • Создай структуру папок по шаблону выше, скопируй код из урока
  • Добавь use-case DeleteTask с проверкой владельца
  • Напиши 3 теста на CompleteTask: успех, задача не найдена, чужая задача
  • Замени LogNotifier на SlackNotifier, который шлёт webhook (адаптер для внешнего сервиса)
  • Запусти go vet ./... и убедись, что нет ошибок

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