Exceptions -> OperationOutcome
В мире php-ходящих есть мнение, что первое, что сказал Иисус Христос, придя в этот мир: "исключения - зло".
Причина, по которой появилась эта статья статья, проста и банальна: автору надоело отлавливать тонну кастомных исключений между слоями приложения.
Исключения в php — мощный и гибкий способ отлавливать непредвиденные события, произошедшие при выполнении операции. И самое главное здесь то, что исключения предусмотрены на уровне самого языка.
Конструкция по типу try { .. } catch (Exception $e) { ..$e->getMessage() } знакома каждому 5 человеку в мире и воспринимается как неотъемлемая часть любой логики на php.
Взгляните на исходники mature-фреймворков вроде Symfony, Laravel и десятков других. Вы без труда обнаружите отдельную директорию Exceptions с тонной кастомных исключений, предусмотренных самими фреймворками.
Любопытный читатель задаст вопрос и что в этом такого?
Ничего, кроме того, что из чёткой цепочки обработки запросов ваш код быстро превращается в коллекцию try catch на каждой 3 строке.
Это не кажется проблемой до того момента, как дело не дойдёт до разделения приложения на отдельные слои во благо SOLID. Представьте, что в вашей команде >1 человека и все они работают над разными слоями, которые должны между собой взаимодействовать. В подобных ситуациях все участники должны документировать все созданные методы, а так же возвращаемые исключения. И да, это хорошо, но зачастую документация исключений становится невыносимой. Таким образом ваша работа обрастает ненужным слоем прокидывания исключений, которые к слову нужно ещё и создать.
OperationOutcome
OperationOutcome объект, он же DTO, он же "контракт", он же спаситель моей жопы - ключевой компонент ядра минифреймворка Rift для апи шлюзов с уклоном в мультитенантность.
На его основе реализован весь минифреймворк, который представляет из себя весьма занятный эксперимент, являющийся следствием работы над несколькими разными по сути, но очень схожими в реализации проектами, объединяющий в себе то лучшее, что я вынес из попыток сделать легаси шлак не легаси шлаком.
OperationOutcome не что иное как объект, создаваемый каждый раз когда какое-то звено вашего приложения пытается сообщить окружающему миру о результате своей работы. Использование стандартизированного объекта ответа в сотню раз облегчает восприятие логической цепочки выполнения запросов и позволяет не "ломать" единый поток её выполнения.
Аналогичная концепция передачи объекта в качестве результата выполнения операции реализована azjezz/psl . Знающий читатель увидит в OperationOutcome влияние промисов из фп с их методами .then и .map
Итак, как это работает.
Rift предлагает организовывать приложения, придерживаясь единого контракта, убивающего путаницу при работе с сырыми исключениям. Rift\Core\Contracts - здесь описывается объект OperationOutcome, вспомогательный класс-обёртка Operation, позволяющий создавать новый объект с помощью методов success и error, а так же OperationOutcomeTrait, содержащий HTTP статус-коды (которые вы легко можете заменить на свои кастомные).
Объект OperationOutcome содержит 4 основных переменных, полностью описывающих возможные исходы выполнения операции:
code (int) - статус-код операции, по умолчанию используются http коды;
result (mixed) - результат выполнения операции, любая полезная нагрузка. Если операция занимается генерацией целочисленного числа - кладите его сюда, инициализацией объекта - сюда же, формированием массива - добро пожаловать;
error (string) - описание ошибки при наличии;
meta (array) - мета-данные операции. Метрики, дебаг информация лежит тут.
Приведём пример возвращения методом результата операции:
use Rift\Core\Contracts\Operation;
use Rift\Core\Contracts\OperationOutcome;
class SomeService extends Operation {
public static function execute(): OperationOutcome {
// логика получения $result
return self::success($result);
}
}
Использование вспомогательного класса Operation и его метода success / error через наследование может осуждаться, поэтому альтернативный вариант будет выглядеть так:
use Rift\Core\Contracts\Operation;
use Rift\Core\Contracts\OperationOutcome;
class SomeService {
public static function execute(): OperationOutcome {
// логика получения $result
return Operation::success($result);
}
}
В любом случае результатом вызова статического метода execute будет объект OperationOutcome:
object(Rift\Core\Contracts\OperationOutcome)#29 (4) {
["code"]=>
int(200)
["result"]=>
string(18) "operation's result"
["error"]=>
NULL
["meta"]=>
array(2) {
["metrics"]=>
array(0) {
}
["debug"]=>
array(0) {
}
}
}
Более сложные вариации инициализации объекта OperationOutcome
Существует слишком много вариантов инициализации объекта ответа, включающих в себя как простые сценарии, по типу success($result), так и более сложные, с использованием кастомных метрик, отладочной информации и подобных необязательных полей.
Здесь вы найдёте несколько простых (сложные цепочки вынесены отдельно) примеров инициализации OperationOutcome.
Во всех этих случаях вызванная операция возвращает стандартизированный объект ответа, готовый к обработке, и неважно имеет он такой вид:
object(Rift\Core\Contracts\OperationOutcome)#49 (4) {
["code"]=>
int(404)
["result"]=>
NULL
["error"]=>
string(14) "User not found"
["meta"]=>
array(1) {
["debug"]=>
array(3) {
["searched_id"]=>
int(999)
["available_ids"]=>
array(3) {
[0]=>
int(1)
[1]=>
int(2)
[2]=>
int(3)
}
["trace"]=>
array(1) {
[0]=>
array(5) {
["file"]=>
string(21) "/app/public/index.php"
["line"]=>
int(74)
["function"]=>
string(14) "errorWithDebug"
["class"]=>
string(24) "App\Examples\SomeService"
["type"]=>
string(2) "::"
}
}
}
}
}
или такой:
object(Rift\Core\Contracts\OperationOutcome)#23 (4) {
["code"]=>
int(200)
["result"]=>
array(2) {
["user_id"]=>
int(123)
["name"]=>
string(8) "Huila"
}
["error"]=>
NULL
["meta"]=>
array(2) {
["metrics"]=>
array(3) {
["execution_time_ms"]=>
float(45.2)
["memory_usage_mb"]=>
float(12.7)
["database_queries"]=>
int(3)
}
["debug"]=>
array(0) {
}
}
}
Согласитесь, это напоминает исключения, но с одной большой разницей...
Обработка OperationOutcome
Представим, что в вашем приложении есть слой типа UseCase / Controller, который должен обратиться к ряду репозиториев, обработать их ответы и выдать результат в случае успеха. Если бы мы были педофилами Symfony-like разработчиками, мы бы использовали конструкцию try-catch, проверяя каждый раз корректность запроса к репозиторию и выбрасывая исключение в случае неудачи.
Но мы не доверяем исключениям, а полагаемся на OperationOutcome, который будет возвращать каждый метод наших репозиториев.
OperationOutcome из коробки содержит несколько методов, облегчающих составление логической цепочки запросов:
->isSuccess(): bool - проверка объекта на успех / провал. Работает с использованием поля code. По умолчанию успешные коды ответа: 200 Operation::HTTP_OK, 201 Operation::HTTP_CREATED. Если проверяемый объект ответа имеет один из этих статусов, метод isSuccess() вернёт true;
->then(callable $callback) - выполняет коллбэк, если результат успешный (аналог then/flatMap);
->map(callable $callback) - трансформирует результат, если успех (аналог map);
->catch(callable $errorHandler) - обрабатывает ошибку, если она есть (аналог catch);
->tap(callable $callback) - выполняет сайд-эффект без изменения результата (аналог tap);
->ensure(callable $predicate, string $errorMessage, int $errorCode = 400) - проверяет условие, иначе возвращает ошибку (аналог filter/assert);
->merge(OperationOutcome $other, callable $merger) - комбинирует два OperationOutcome (аналог zip);
так же из коробки предоставляются готовые методы для работы с метриками и дебаг информацией:
->withMetric(string $key, mixed $value) - пушит метрику в meta['metrics'] объекта;
->addDebugData(string $key, mixed $value) - пушит дебаг информацию в meta['debug'] объекта.
Здесь собраны демонстрационные примеры использования всех вышеуказанных методов.
Вот как может выглядеть цепочка запросов в вашем UseCase:
class SomeUseCase {
public static function demoChain(): OperationOutcome
{
return Operation::success(['id' => 1, 'name' => ' alice '])
->withMetric('start_time', microtime(true))
->map(function($user) {
$user['name'] = trim($user['name']);
return $user;
})
->ensure(
fn($user) => !empty($user['name']),
'Name cannot be empty',
400
)
->map(function($user) {
$user['name'] = ucfirst($user['name']);
return $user;
})
->then(function($user) {
return self::fetchUserStats($user['id'])
->map(function($stats) use ($user) {
return array_merge($user, ['stats' => $stats]);
});
})
->addDebugData('ahuenno', 'yes')
->withMetric('end_time', microtime(true));
}
private static function fetchUserStats(int $userId): OperationOutcome
{
// Имитация получения статистики
if ($userId === 1) {
return Operation::success([
'logins' => 42,
'last_login' => '2023-01-01'
]);
}
return Operation::error(404, 'Stats not found');
}
}
результатом вызова метода demoChain будет элегантный OperationOutcome:
object(Rift\Core\Contracts\OperationOutcome)#41 (4) {
["code"]=>
int(200)
["result"]=>
array(3) {
["id"]=>
int(1)
["name"]=>
string(5) "Alice"
["stats"]=>
array(2) {
["logins"]=>
int(42)
["last_login"]=>
string(10) "2023-01-01"
}
}
["error"]=>
NULL
["meta"]=>
array(2) {
["metrics"]=>
array(1) {
["end_time"]=>
float(1749400258.696166)
}
["debug"]=>
array(1) {
["ahuenno"]=>
string(3) "yes"
}
}
}
Представление OperationOutcome: ->toJson()
OperationOutcome настолько универсален, что может использоваться для API ответов (особенно хорошо, если ваше приложение разделено на несколько серверов и общается по одному стандарту).
->toJson(?callable $transformer = null, int $flags) - метод для сериализации OperationOutcome. Вы можете задать кастомную схему ответа и установить необходимые флаги для преобразования во всеми любимый json.
Приведём пример:
$resultQueryJson = $resultQuery->toJson(fn($outcome) => [
'ok' => $outcome->isSuccess(),
'code' => $outcome->code,
'payload' => $outcome->result ?? $outcome->error,
'_meta' => $outcome->meta
]);
в результате мы получим трансформированный OperationOutcome:
string(134) "{
"ok": false,
"code": 404,
"payload": "Path not found",
"_meta": {
"metrics": [],
"debug": []
}
}"
Послесловие
Как бы ни хотелось отказаться от исключений в пользу единого контракта, есть ситуации, когда без них не обойтись. Фатальные ошибки при работе с базой данных никуда не делись, и их всё так же нужно отлавливать и передавать на уровень выше. OperationOutcome — это лишь ещё один слой абстракции, который нужен для интуитивно понятного восприятия цепочки запросов и стандартизации ответов каждого звена. Он не подвержен статическому анализу (в отличие от @throws в PHPStan/Psalm). Он может быть избыточным для многих проектов.
Но он совмещает в себе природу функциональщины и единый стандарт ответа и может выступать отличным связующим звеном между слоями сложных проектов, где важна контрактность и последовательность выполнения цепочки запросов.
Rift
Rift - минифреймворк, строящийся вокруг идеи OperationOutcome в контексте мультитенантных приложений.