Формат помилок в RPC
Відповідно до специфікації JSON-RPC, коли виклик RPC призводить до помилки, об'єкт відповіді повинен містити елемент "error", який є об'єктом з наступними членами:
- code: Число, яке вказує на тип помилки, що виникла. Це має бути ціле число.
- message: Рядок, що надає короткий опис помилки. Повідомлення має бути коротким і лаконічним.
- data (необов'язковий): Додаткова інформація про помилку, яка може бути корисною для налагодження.
Докладніше про формат помилок можна прочитати у специфікації JSON-RPC: JSON-RPC 2.0 Specification.
Обробка помилок
У JsonRpcBundle реалізовано стандартний механізм обробки помилок для RPC запитів, який базується на окремому пакеті ufo-tech/rpc-exceptions. Цей пакет надає можливість детально обробляти помилки, що виникають під час виконання RPC запитів, і повертати стандартизовані коди та повідомлення про помилки.
Коди помилок та їх інтерпретація
Пакет ufo-tech/rpc-exceptions надає перелік стандартних кодів помилок та відповідних класів виключень:
| Код | Тип помилки | Опис |
|---|---|---|
| -32700 | Parse error | Сервер отримав недійсний JSON |
| -32600 | Invalid Request | Наданий JSON не є дійсним об'єктом запиту |
| -32601 | Method not found | Метод не існує або недоступний |
| -32602 | Invalid params | Недійсні параметри методу |
| -32603 | Internal error | Внутрішня помилка JSON-RPC |
| -32500 | Application error | Помилка виконання процедури |
| -32400 | System error | Логічна помилка в додатку |
| -32401 | Security error | Токен не знайдено |
| -32403 | Security error | Недійсний токен |
| -32300 | Async error | Помилка передачі асинхронних даних |
| -32301 | Batch error | Помилка batch-запиту |
| -32000 | Server error | Зарезервовано для серверних помилок, визначених реалізацією |
| від -32001 до -32099 | Користувацька помилка |
Використання виключень у вашому коді
Отримання об'єкта виключення з коду
use Ufo\RpcError\AbstractRpcErrorException;
$code = -32700;
$message = 'Some custom error message from rpc server'; // опціонально
$rpcException = AbstractRpcErrorException::fromCode($code);
// повертає екземпляр RpcJsonParseException::class
Отримання об'єкта виключення з масиву
use Ufo\RpcError\AbstractRpcErrorException;
$data = [
'code' => -32600,
'message' => 'Some custom error message from rpc server',
];
$rpcException = RpcBadRequestException::fromArray($data);
// повертає екземпляр RpcBadRequestException::class
Отримання об'єкта виключення з JSON
use Ufo\RpcError\AbstractRpcErrorException;
$data = "{\"code\":-32500,\"message\":\"Some custom error message from rpc server\"}";
$rpcException = AbstractRpcErrorException::fromJson($data);
// повертає екземпляр RpcRuntimeException::class
Поради для розробників
Якщо ви, як розробник, хочете повертати специфічну помилку, яка буде інтерпретована RPC сервером, вам слід використовувати один з інтерфейсів, наданих пакетом ufo-tech/rpc-exceptions, або наслідувати типове виключення та притримуватися нумерації помилок.
Однак, якщо специфічна обробка не потрібна, сервер здатний обробити будь-яку помилку або виключення, що відбуваються на рівні виконання методу API, забезпечуючи стабільність та надійність вашої системи.