HTTP адаптер: handler/controller как тонкий слой

HTTP адаптер: handler как тонкий слой

HTTP handler - это первичный адаптер. Он принимает внешний запрос и преобразует его в вызов use-case. Вся ответственность handler сводится к трём шагам:

  1. Распарсить входящий запрос (JSON body, URL-параметры, заголовки).
  2. Вызвать use-case с доменными типами.
  3. Сформировать HTTP-ответ (статус код, JSON body).

Если в handler появляется бизнес-логика (проверка, что задача принадлежит пользователю, вычисление скидки, валидация бизнес-правил) - значит, handler раздулся и превратился в «серверный комбайн». Куда переносить такую логику, решается по одному признаку: оркестрация шагов уходит в сценарий (урок Use Case), а сами правила - в доменный объект, и граница между этими двумя ролями подробно разобрана в уроке Domain Service vs Application Service.

Структура handler

Handler получает use-case через конструктор - dependency injection без магии.

// internal/adapters/http/task_handler.go
package http

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

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

    "myapp/internal/usecase"
)

type TaskHandler struct {
    createTask *usecase.CreateTask
    listTasks  *usecase.ListTasks
}

func NewTaskHandler(ct *usecase.CreateTask, lt *usecase.ListTasks) *TaskHandler {
    return &TaskHandler{
        createTask: ct,
        listTasks:  lt,
    }
}

func (h *TaskHandler) Routes(r chi.Router) {
    r.Post("/tasks", h.Create)
    r.Get("/tasks", h.List)
}
<?php
// src/Infrastructure/Http/Controller/TaskController.php
declare(strict_types=1);

namespace App\Infrastructure\Http\Controller;

use App\Application\UseCase\CreateTaskUseCase;
use App\Application\UseCase\ListTasksUseCase;
use Symfony\Component\Routing\Attribute\Route;

final class TaskController
{
    public function __construct(
        private readonly CreateTaskUseCase $createTask,
        private readonly ListTasksUseCase $listTasks,
    ) {}

    // Маршруты задаются Symfony Routing через атрибуты #[Route(...)] на каждом методе
}
# myapp/adapters/http/task_handler.py
#
# Фреймворк-независимый адаптер: Request и Response - простые dataclass'ы,
# обработчики - функции «запрос на входе, ответ на выходе». В FastAPI их место
# занимают fastapi.Request / fastapi.Response и APIRouter, в Django -
# HttpRequest / JsonResponse и urls.py; сами обработчики при этом не меняются.
from dataclasses import dataclass, field
from typing import Any, Callable, Protocol

from myapp.usecase import CreateTask, ListTasks


@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)


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_task: CreateTask, list_tasks: ListTasks) -> None:
        self._create_task = create_task
        self._list_tasks = list_tasks

    def routes(self, router: Router) -> None:
        router.post("/tasks", self.create)
        router.get("/tasks", self.list)

ℹ️ Один handler - один use-case (или группа)

Можно сделать отдельный handler на каждый use-case (CreateTaskHandler, ListTasksHandler). Но на практике удобнее группировать по ресурсу: TaskHandler с методами Create, List, Get, Complete. Важно, чтобы каждый метод оставался тонким.

Полный пример: Create

type CreateTaskRequest struct {
    Title string `json:"title"`
}

type TaskResponse struct {
    ID        string `json:"id"`
    Title     string `json:"title"`
    Completed bool   `json:"completed"`
    CreatedAt string `json:"createdAt"`
}

func (h *TaskHandler) Create(w http.ResponseWriter, r *http.Request) {
    // 1. Парсим запрос.
    var req CreateTaskRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        writeError(w, http.StatusBadRequest, "invalid JSON")
        return
    }

    // 2. Достаём userID из контекста (установлен middleware).
    // Форма с ok: если middleware не подключили, без проверки была бы паника.
    userID, ok := r.Context().Value(userIDKey).(string)
    if !ok || userID == "" {
        writeError(w, http.StatusUnauthorized, "unauthenticated")
        return
    }

    // 3. Вызываем use-case.
    task, err := h.createTask.Execute(r.Context(), usecase.CreateTaskInput{
        UserID: userID,
        Title:  req.Title,
    })
    if err != nil {
        writeUseCaseError(w, err)
        return
    }

    // 4. Формируем ответ.
    // Время переводим в UTC и форматируем по RFC 3339: буква Z в шаблоне
    // "...05Z" была бы просто литералом, и локальное время ушло бы как UTC.
    writeJSON(w, http.StatusCreated, TaskResponse{
        ID:        task.ID(),
        Title:     task.Title(),
        Completed: task.Completed(),
        CreatedAt: task.CreatedAt().UTC().Format(time.RFC3339),
    })
}
<?php
// src/Infrastructure/Http/Controller/TaskController.php
declare(strict_types=1);

use App\Domain\TaskError;

#[Route('/tasks', methods: ['POST'])]
public function create(Request $request): JsonResponse
{
    // 1. Парсим запрос.
    $payload = json_decode($request->getContent(), true);
    if (!is_array($payload)) {
        return new JsonResponse(['error' => 'invalid JSON'], 400);
    }

    // 2. Достаём userId из request attributes (положил middleware).
    $userId = (string) $request->attributes->get('userId');

    // 3. Вызываем use-case.
    try {
        $task = $this->createTask->execute(new CreateTaskInput(
            userId: $userId,
            title: (string) ($payload['title'] ?? ''),
            description: '',
        ));
    } catch (TaskError $e) {
        return $this->writeUseCaseError($e);
    }

    // 4. Формируем ответ.
    return new JsonResponse([
        'id' => $task->id(),
        'title' => $task->title(),
        'completed' => $task->isCompleted(),
    ], 201);
}
import json
from dataclasses import dataclass
from datetime import timezone

from myapp.usecase import CreateTaskInput


@dataclass(frozen=True)
class CreateTaskRequest:
    title: str


@dataclass(frozen=True)
class TaskResponse:
    id: str
    title: str
    completed: bool
    created_at: str

    # camelCase ключей в JSON - забота этого слоя (в pydantic это alias).
    def to_dict(self) -> dict[str, object]:
        return {
            "id": self.id,
            "title": self.title,
            "completed": self.completed,
            "createdAt": self.created_at,
        }


class TaskHandler:  # продолжение task_handler.py
    def create(self, request: Request) -> Response:
        # 1. Парсим запрос.
        try:
            payload = json.loads(request.body)
        except ValueError:
            payload = None
        if not isinstance(payload, dict):
            return write_error(400, "invalid JSON")
        req = CreateTaskRequest(title=str(payload.get("title", "")))

        # 2. Достаём user_id из состояния запроса (положил middleware).
        user_id: str = request.state["user_id"]

        # 3. Вызываем use-case.
        try:
            task = self._create_task.execute(CreateTaskInput(
                user_id=user_id,
                title=req.title,
            ))
        except Exception as err:
            return write_use_case_error(err)

        # 4. Формируем ответ.
        return write_json(201, TaskResponse(
            id=task.id,
            title=task.title,
            completed=task.completed,
            # В UTC и с настоящей зоной: литерал Z у локального времени соврал бы.
            created_at=task.created_at.astimezone(timezone.utc).isoformat(),
        ).to_dict())

Обрати внимание: handler не знает, как генерируется ID, какие правила валидации применяются к Title, куда сохраняется задача. Он знает только про HTTP.

Структуры CreateTaskRequest и TaskResponse существуют только здесь, в адаптере, и в домен не попадают: в ответе нет ни внутренних флагов, ни хешей паролей, а формат даты - забота именно этого слоя. Почему таких структур в приложении оказывается сразу несколько и как между ними ходят данные - в уроке DTO и маппинг.

Маппинг доменных ошибок в HTTP-статусы

Use-case возвращает доменные ошибки (domain.ErrTaskNotFound, domain.ErrInvalidTitle). Handler превращает их в HTTP-коды.

func writeUseCaseError(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):
        writeError(w, http.StatusBadRequest, err.Error())
    case errors.Is(err, domain.ErrTaskAlreadyCompleted):
        writeError(w, http.StatusConflict, "task already completed")
    default:
        writeError(w, http.StatusInternalServerError, "internal error")
    }
}

func writeError(w http.ResponseWriter, status int, msg string) {
    writeJSON(w, status, map[string]string{"error": msg})
}

func writeJSON(w http.ResponseWriter, status int, data any) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    _ = json.NewEncoder(w).Encode(data)
}
<?php
// src/Infrastructure/Http/EventListener/DomainExceptionListener.php
declare(strict_types=1);

namespace App\Infrastructure\Http\EventListener;

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

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

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

        $response = match (true) {
            $e instanceof TaskNotFoundError =>
                new JsonResponse(['error' => 'task not found'], 404),
            $e instanceof InvalidTitleError =>
                new JsonResponse(['error' => $e->getMessage()], 400),
            $e instanceof TaskAlreadyCompletedError =>
                new JsonResponse(['error' => 'task already completed'], 409),
            default => null,
        };

        if ($response !== null) {
            $event->setResponse($response);
            return;
        }

        // Unknown exception - 500, детали в лог, не в ответ
        $this->logger->error('unhandled exception', ['exception' => $e]);
        $event->setResponse(new JsonResponse(['error' => 'internal error'], 500));
    }
}
# В FastAPI то же самое делает @app.exception_handler(TaskError) -
# один обработчик на все доменные исключения.
def write_use_case_error(err: Exception) -> Response:
    match err:
        case domain.TaskNotFoundError():
            return write_error(404, "task not found")
        case domain.InvalidTitleError():
            return write_error(400, str(err))
        case domain.TaskAlreadyCompletedError():
            return write_error(409, "task already completed")
        case _:
            return write_error(500, "internal error")


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


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

⚠️ Не отдавай err.Error() напрямую для 500

Внутренние ошибки (connection refused, sql: no rows) могут содержать детали инфраструктуры. Для 500 всегда отдавай generic-сообщение, а полную ошибку логируй серверно через slog.Error.

Валидация: handler vs domain

Есть два уровня валидации:

ГдеЧто проверяемПример
HandlerФормат запросаJSON корректен, обязательные поля присутствуют
Domain/Use-caseБизнес-правилаTitle не пустой, длина <= 200 символов, у пользователя < 100 задач
// В handler - только формат: поле title пришло и это строка.
// Указатель отличает «поля нет» от «пустая строка»; пустая строка -
// уже бизнес-правило, его проверит домен.
var req struct {
    Title *string `json:"title"`
}
if err := json.NewDecoder(r.Body).Decode(&req); err != nil || req.Title == nil {
    writeError(w, http.StatusBadRequest, "title is required")
    return
}

// В domain - бизнес-правило:
func (t *Task) SetTitle(title string) error {
    // Символы, а не байты: len() у строки в Go - это байты, и кириллица
    // упёрлась бы в лимит на сотой букве.
    if utf8.RuneCountInString(title) > 200 {
        return ErrInvalidTitle
    }
    t.title = title
    return nil
}
<?php
declare(strict_types=1);

// В controller - только формат запроса
if (!isset($payload['title']) || !is_string($payload['title'])) {
    return new JsonResponse(['error' => 'title is required'], 400);
}

// В domain - бизнес-правило
final class Task
{
    public function setTitle(string $title): void
    {
        if (mb_strlen($title) > 200) {
            throw InvalidTitleError::tooLong(200);
        }
        $this->title = $title;
    }
}
# В handler - только формат: поле title пришло и это строка.
# Пустая строка - уже бизнес-правило, его проверит домен.
def create(self, request: Request) -> Response:
    ...
    if not isinstance(payload.get("title"), str):
        return write_error(400, "title is required")
    ...


# В domain - бизнес-правило:
class Task:
    def set_title(self, title: str) -> None:
        if len(title) > 200:
            raise InvalidTitleError()
        self._title = title

Не дублируй бизнес-валидацию в handler. Если правило «максимум 200 символов» есть и в handler, и в domain - при изменении лимита придётся менять два места. Правило про длину заголовка - это инвариант доменного объекта, и держать его должен сам объект, не пуская внешний код к своим полям: как это устроено, в уроке Aggregates и инварианты.

Middleware и цепочка вызовов

Middleware - это тоже часть HTTP-адаптера. Типичная цепочка обработки запроса:

Цепочка обработки HTTP-запроса через middleware к use-case

func main() {
    r := chi.NewRouter()

    r.Use(middleware.Logger)
    r.Use(middleware.Recoverer)

    r.Route("/api", func(r chi.Router) {
        r.Use(AuthMiddleware(tokenService))

        // httpadapter - наш пакет adapters/http под псевдонимом,
        // чтобы не столкнуться с net/http
        taskHandler := httpadapter.NewTaskHandler(createTaskUC, listTasksUC)
        taskHandler.Routes(r)
    })
}
<?php
// src/Infrastructure/Http/EventListener/AuthListener.php
declare(strict_types=1);

namespace App\Infrastructure\Http\EventListener;

use App\Application\Port\TokenServicePort;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpKernel\Event\RequestEvent;

#[AsEventListener(priority: 10)]
final class AuthListener
{
    public function __construct(
        private readonly TokenServicePort $tokens,
    ) {}

    public function __invoke(RequestEvent $event): void
    {
        $request = $event->getRequest();
        if (!str_starts_with($request->getPathInfo(), '/api')) {
            return;
        }

        $token = $request->headers->get('Authorization');
        $userId = $this->tokens->verify((string) $token);

        // Кладём userId в attributes - controller достанет через $request->attributes->get('userId')
        $request->attributes->set('userId', $userId);
    }
}
# myapp/adapters/http/middleware.py
Middleware = Callable[[Handler], Handler]


def auth_middleware(tokens: TokenService) -> Middleware:
    def wrap(next_handler: Handler) -> Handler:
        def handle(request: Request) -> Response:
            token = request.headers.get("Authorization", "")
            user_id = tokens.verify(token)

            # Кладём user_id в state - handler достанет через request.state["user_id"].
            request.state["user_id"] = user_id
            return next_handler(request)
        return handle
    return wrap


# cmd/server/main.py
def main() -> None:
    router = Router()

    router.use(logging_middleware)
    router.use(recover_middleware)

    api = router.group("/api")
    api.use(auth_middleware(token_service))

    task_handler = TaskHandler(create_task_uc, list_tasks_uc)
    task_handler.routes(api)

    # В FastAPI та же цепочка: app.add_middleware(...) для логов и recover,
    # APIRouter(prefix="/api") вместо group, Depends(current_user) вместо
    # auth_middleware. Обработчики TaskHandler не меняются.

Auth middleware/listener извлекает токен, валидирует его и кладёт userID в context / request attributes. Handler/controller достаёт userID оттуда. Use-case получает userID как обычный параметр. Ни middleware, ни use-case не знают друг о друге.

Антипаттерн: бизнес-логика в handler

// Плохо: handler решает, можно ли завершить задачу.
func (h *TaskHandler) Complete(w http.ResponseWriter, r *http.Request) {
    task, _ := h.repo.GetByID(r.Context(), chi.URLParam(r, "id"))

    if task.Completed() {
        writeError(w, http.StatusConflict, "already done")
        return
    }
    if task.UserID() != currentUserID(r) {
        writeError(w, http.StatusForbidden, "not your task")
        return
    }

    // прямой вызов repo + мутация - бизнес-логика в HTTP-слое
    _ = task.Complete()
    _ = h.repo.Update(r.Context(), task)
    writeJSON(w, http.StatusOK, task)
}
<?php
// Плохо: controller знает про репозиторий, проверяет владельца и статус
#[Route('/tasks/{id}/complete', methods: ['POST'])]
public function completeBad(string $id, Request $request): JsonResponse
{
    $task = $this->tasks->getById($id);

    if ($task->isCompleted()) {
        return new JsonResponse(['error' => 'already done'], 409);
    }
    if ($task->userId() !== (string) $request->attributes->get('userId')) {
        return new JsonResponse(['error' => 'not your task'], 403);
    }

    // прямой вызов repo + мутация - бизнес-логика в HTTP-слое
    $task->complete();
    $this->tasks->update($task);

    return new JsonResponse(['ok' => true]);
}
# Плохо: handler решает, можно ли завершить задачу.
class TaskHandler:
    def complete(self, request: Request) -> Response:
        task = self._repo.get_by_id(request.path_params["id"])

        if task.completed:
            return write_error(409, "already done")
        if task.user_id != request.state["user_id"]:
            return write_error(403, "not your task")

        # прямой вызов repo + мутация - бизнес-логика в HTTP-слое
        task.complete()
        self._repo.update(task)
        return write_json(200, {"ok": True})

Здесь handler напрямую работает с репозиторием и содержит бизнес-логику (проверка владельца, проверка статуса). При добавлении нового правила (например, «нельзя завершить задачу без описания») придётся менять handler. Правильный вариант:

// Хорошо: handler тонкий, логика в use-case.
func (h *TaskHandler) Complete(w http.ResponseWriter, r *http.Request) {
    taskID := chi.URLParam(r, "id")
    userID := currentUserID(r)

    err := h.completeTask.Execute(r.Context(), taskID, userID)
    if err != nil {
        writeUseCaseError(w, err)
        return
    }

    w.WriteHeader(http.StatusNoContent)
}
<?php
// Хорошо: controller тонкий, логика в use-case
use App\Domain\TaskError;

#[Route('/tasks/{id}/complete', methods: ['POST'])]
public function complete(string $id, Request $request): Response
{
    try {
        $this->completeTask->execute(
            taskId: $id,
            userId: (string) $request->attributes->get('userId'),
        );
    } catch (TaskError $e) {
        return $this->writeUseCaseError($e);
    }

    return new Response(status: 204);
}
# Хорошо: handler тонкий, логика в use-case.
class TaskHandler:
    def complete(self, request: Request) -> Response:
        task_id = request.path_params["id"]
        user_id: str = request.state["user_id"]

        try:
            self._complete_task.execute(task_id, user_id)
        except Exception as err:
            return write_use_case_error(err)

        return Response(status=204)

🚫 Handler не должен импортировать репозиторий

Если handler зависит от ports.TaskRepository напрямую - это нарушение архитектуры. Handler зависит от use-case, use-case зависит от порта, порт реализуется адаптером. Три слоя, направление зависимостей всегда внутрь.

Посмотреть эти три слоя разом, вместе с доменом, портами и сборкой зависимостей в одной точке входа, можно в мини-проекте Tasks API - там тот же handler стоит на своём месте в готовом приложении.

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

  • Напиши handler GetTask, который принимает ID из URL, вызывает use-case и возвращает JSON
  • Реализуй функцию writeUseCaseError для своего проекта - маппинг минимум 3 доменных ошибок в HTTP-статусы
  • Проверь свои handler-ы: есть ли в них if-ы, которые относятся к бизнес-логике? Вынеси их в use-case
  • Убедись, что handler не импортирует пакет adapters/postgres или database/sql

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