init
uk/docs/api/json-rpc-bundle/error_handling.md
новий файл +74
−0
1
+
# Формат помилок в RPC
2
+
3
+
Відповідно до специфікації JSON-RPC, коли виклик RPC призводить до помилки, об'єкт відповіді повинен містити елемент "error", який є об'єктом з наступними членами:
4
+
5
+
- **code**: Число, яке вказує на тип помилки, що виникла. Це має бути ціле число.
6
+
- **message**: Рядок, що надає короткий опис помилки. Повідомлення має бути коротким і лаконічним.
7
+
- **data** (необов'язковий): Додаткова інформація про помилку, яка може бути корисною для налагодження.
8
+
9
+
Докладніше про формат помилок можна прочитати у специфікації JSON-RPC: [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification#error_object).
10
+
11
+
## Обробка помилок
12
+
13
+
У JsonRpcBundle реалізовано стандартний механізм обробки помилок для RPC запитів, який базується на окремому пакеті `ufo-tech/rpc-exceptions`. Цей пакет надає можливість детально обробляти помилки, що виникають під час виконання RPC запитів, і повертати стандартизовані коди та повідомлення про помилки.
14
+
15
+
### Коди помилок та їх інтерпретація
16
+
17
+
Пакет `ufo-tech/rpc-exceptions` надає перелік стандартних кодів помилок та відповідних класів виключень:
18
+
19
+
| Код | Тип помилки | Опис |
20
+
| --- | --- | --- |
21
+
| -32700 | Parse error | Сервер отримав недійсний JSON |
22
+
| -32600 | Invalid Request | Наданий JSON не є дійсним об'єктом запиту |
23
+
| -32601 | Method not found | Метод не існує або недоступний |
24
+
| -32602 | Invalid params | Недійсні параметри методу |
25
+
| -32603 | Internal error | Внутрішня помилка JSON-RPC |
26
+
| -32500 | Application error | Помилка виконання процедури |
27
+
| -32400 | System error | Логічна помилка в додатку |
28
+
| -32401 | Security error | Токен не знайдено |
29
+
| -32403 | Security error | Недійсний токен |
30
+
| -32300 | Async error | Помилка передачі асинхронних даних |
31
+
| -32301 | Batch error | Помилка batch-запиту |
32
+
| -32000 | Server error | Зарезервовано для серверних помилок, визначених реалізацією |
33
+
| від -32001 до -32099 | Користувацька помилка | ~~-~~ |
34
+
35
+
### Використання виключень у вашому коді
36
+
37
+
#### Отримання об'єкта виключення з коду
38
+
39
+
```php
40
+
use Ufo\RpcError\AbstractRpcErrorException;
41
+
42
+
$code = -32700;
43
+
$message = 'Some custom error message from rpc server'; // опціонально
44
+
$rpcException = AbstractRpcErrorException::fromCode($code);
45
+
// повертає екземпляр RpcJsonParseException::class
46
+
```
47
+
48
+
#### Отримання об'єкта виключення з масиву
49
+
```php
50
+
use Ufo\RpcError\AbstractRpcErrorException;
51
+
52
+
$data = [
53
+
'code' => -32600,
54
+
'message' => 'Some custom error message from rpc server',
55
+
];
56
+
$rpcException = RpcBadRequestException::fromArray($data);
57
+
// повертає екземпляр RpcBadRequestException::class
58
+
```
59
+
60
+
#### Отримання об'єкта виключення з JSON
61
+
62
+
```php
63
+
use Ufo\RpcError\AbstractRpcErrorException;
64
+
65
+
$data = "{\"code\":-32500,\"message\":\"Some custom error message from rpc server\"}";
66
+
$rpcException = AbstractRpcErrorException::fromJson($data);
67
+
// повертає екземпляр RpcRuntimeException::class
68
+
```
69
+
70
+
### Поради для розробників
71
+
72
+
Якщо ви, як розробник, хочете повертати специфічну помилку, яка буде інтерпретована RPC сервером, вам слід використовувати один з інтерфейсів, наданих пакетом `ufo-tech/rpc-exceptions`, або наслідувати типове виключення та притримуватися нумерації помилок.
73
+
74
+
Однак, якщо специфічна обробка не потрібна, сервер здатний обробити будь-яку помилку або виключення, що відбуваються на рівні виконання методу API, забезпечуючи стабільність та надійність вашої системи.