HTTP адаптер: handler/controller как тонкий слой
HTTP адаптер: handler как тонкий слой
HTTP handler - это первичный адаптер. Он принимает внешний запрос и преобразует его в вызов use-case. Вся ответственность handler сводится к трём шагам:
- Распарсить входящий запрос (JSON body, URL-параметры, заголовки).
- Вызвать use-case с доменными типами.
- Сформировать 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-адаптера. Типичная цепочка обработки запроса:
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