5. Обробка помилок

Last modified by Ashterix on 2024/05/17 19:03
Зміст

Формат помилок в 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    Користувацька помилка -                                                

Використання виключень у вашому коді

Отримання об'єкта виключення з коду

1
2
3
4
5
6
7
<?php
use Ufo\RpcError\AbstractRpcErrorException;

$code = -32700;
$message = 'Some custom error message from rpc server'; // опціонально
$rpcException = AbstractRpcErrorException::fromCode($code);
// повертає екземпляр RpcJsonParseException::class

Отримання об'єкта виключення з масиву

1
2
3
4
5
6
7
8
9
<?php
use Ufo\RpcError\AbstractRpcErrorException;

$data = [
   'code' => -32600,
   'message' => 'Some custom error message from rpc server',
];
$rpcException = RpcBadRequestException::fromArray($data);
// повертає екземпляр RpcBadRequestException::class

Отримання об'єкта виключення з JSON

1
2
3
4
5
6
<?php
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, забезпечуючи стабільність та надійність вашої системи.