Мини-проект: 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импортирует всех - здесь происходит сборка.
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 ./...и убедись, что нет ошибок