docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/json-rpc-bundle/error_handling.md
+40
−16
16
16
17
17
Пакет `ufo-tech/rpc-exceptions` надає перелік стандартних кодів помилок та відповідних класів виключень:
18
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 | Користувацька помилка | ~~-~~ |
19
+
| Код | Клас | Опис |
20
+
| --- | --- | --- |
21
+
| -32700 | `RpcJsonParseException` | Сервер отримав недійсний JSON |
22
+
| -32600 | `RpcBadRequestException` | Недійсний об'єкт запиту (зокрема `jsonrpc` ≠ `"2.0"`, порожній batch, вимкнений batch) |
23
+
| -32601 | `RpcMethodNotFoundExceptionRpc` | Метод не існує або недоступний у цій групі / версії API |
24
+
| -32602 | `RpcBadParamException`, `ConstraintsImposedException` | Недійсні параметри методу |
25
+
| -32603 | `RpcInternalException` | Внутрішня помилка JSON-RPC |
26
+
| -32500 | `RpcRuntimeException` | Помилка виконання процедури |
27
+
| -32400 | `RpcLogicException` | Логічна помилка в застосунку (наприклад, метод заблоковано `#[RPC\Lock]`) |
28
+
| -32401 | `RpcTokenNotSentException` | Токен не передано (HTTP 401) |
29
+
| -32403 | `RpcInvalidTokenException` | Недійсний токен |
30
+
| -32404 | `RpcDataNotFoundException` | Дані не знайдено |
31
+
| -32300 | `RpcAsyncRequestException` | Помилка асинхронного запиту |
32
+
| -32301 | `RpcInvalidBatchRequestExceptions` | Помилка batch-запиту |
33
+
| -32000 | `RpcCustomServerException` | Серверна помилка, визначена реалізацією |
34
34
35
+
Коди поза діапазоном `-32768…-32000` перетворюються на `CustomApplicationException`, тож застосунок може використовувати власні коди помилок.
36
+
37
+
### Помилки параметрів
38
+
39
+
Відсутні обов'язкові параметри, неправильні типи, невдале створення DTO та порушення [`#[RPC\Assertions]`](/docs/api/json-rpc-bundle/add_rpc_service/assertions) повертаються однією помилкою `-32602` з повідомленнями по кожному параметру в `error.data`:
40
+
41
+
```json
42
+
{
43
+
"jsonrpc": "2.0",
44
+
"id": 1,
45
+
"error": {
46
+
"code": -32602,
47
+
"message": "Invalid Data for call method: user.create",
48
+
"data": {"email": "Required parameter \"email\" not passed"}
49
+
}
50
+
}
51
+
```
52
+
53
+
### Помилки в документації
54
+
55
+
Винятки, оголошені в докблоці методу тегом `@throws`, потрапляють у [документацію](/docs/api/json-rpc-bundle/documentation) з кодом і повідомленням — клієнт заздалегідь знає, яких помилок чекати.
56
+
35
57
### Використання виключень у вашому коді
36
58
37
59
#### Отримання об'єкта виключення з коду
53
75
'code' => -32600,
54
76
'message' => 'Some custom error message from rpc server',
55
77
];
56
−
$rpcException = RpcBadRequestException::fromArray($data);
78
+
$rpcException = AbstractRpcErrorException::fromArray($data);
57
79
// повертає екземпляр RpcBadRequestException::class
58
80
```
59
81
72
94
Якщо ви, як розробник, хочете повертати специфічну помилку, яка буде інтерпретована RPC сервером, вам слід використовувати один з інтерфейсів, наданих пакетом `ufo-tech/rpc-exceptions`, або наслідувати типове виключення та притримуватися нумерації помилок.
73
95
74
96
Однак, якщо специфічна обробка не потрібна, сервер здатний обробити будь-яку помилку або виключення, що відбуваються на рівні виконання методу API, забезпечуючи стабільність та надійність вашої системи.
97
+
98
+
Додаткові дані помилки можна передати клієнту через `error.data`: усі винятки пакета (`AbstractRpcErrorException` реалізує `Ufo\RpcError\IExceptionWithData`) мають методи `changeExtraData()` / `pushToExtraData()`. Підмінити або доповнити помилку глобально можна в лістенері події [`rpc.error`](/docs/api/json-rpc-bundle/functionality/events).