Глава 5. HTTP, маршруты и ответы без скрытой магии

HTTP — не транспорт для функций

URL обозначает ресурс или устойчивую точку сценария, метод выражает намерение, а статус сообщает класс результата. GET читает и должен оставаться безопасным; POST создаёт или запускает операцию; PUT обычно заменяет представление; PATCH меняет часть; DELETE запрашивает удаление. Это не абсолютная религия, а общий словарь между клиентом, кешем и сервером.

Не передавайте изменение состояния через ссылку GET. Поисковый робот, prefetch или повтор браузера не должны случайно выполнить команду.

Front controller

<?php
declare(strict_types=1);

require dirname(__DIR__) . '/vendor/autoload.php';

$request = Request::fromGlobals();
$response = $router->dispatch($request);
$response->send();

Маршрут как пара

Ключ маршрута состоит минимум из метода и нормализованного пути. /tasks для GET и POST — два разных контракта. Динамический параметр /tasks/{id} сначала проверяется как форма идентификатора, затем сценарий проверяет существование и право доступа.

Разделяйте 404 и 403 осознанно. Для закрытых объектов нейтральный 404 иногда уменьшает утечку существования, но внутри журнала причина должна сохраняться.

Статусы, которые помогают

• 200 — представление получено или команда вернула тело.
• 201 — ресурс создан; полезен заголовок Location.
• 303 — после POST перевести браузер на GET и избежать повторной отправки.
• 400 — запрос синтаксически непригоден; 422 — форма разобрана, но значения нарушают контракт.
• 401 — требуется аутентификация; 403 — личность известна, действие запрещено.
• 409 — текущее состояние конфликтует с командой.

HTML и JSON — разные представления

Один use case способен вернуть предметный Result, но HTML-контроллер превращает его в шаблон и редирект, а API-контроллер — в JSON и HTTP-статус. Не заставляйте предметный слой знать о тегах, заголовках или fetch().

Content-Type устанавливается явно. Для JSON используйте application/json; charset для JSON подразумевает UTF-8. Не отражайте входной Accept без allowlist поддерживаемых форматов.

Диагностика маршрута

Практика главы

Опишите маршруты списка задач, создания, завершения и удаления. Для каждого укажите метод, путь, успешный статус, минимум два отказа и правило повторного запроса.

Перелинковка со справочником