docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/sdk/client/usage.md
новий файл +99
−0
1
+
# Використання SDK
2
+
3
+
Згенерований клас процедури — звичайний PHP-клас. У Symfony з [SDK Bundle](/docs/api/sdk/bundle/usage) його достатньо отримати через автовайринг; без бандла — створити вручну.
4
+
5
+
## Синхронний виклик
6
+
7
+
```php
8
+
use App\Sdk\Orders\UserSDK;
9
+
10
+
$users = new UserSDK(headers: ['Ufo-RPC-Token' => $token]);
11
+
12
+
$user = $users->get(5); // App\Sdk\Orders\DTO\UserDto
13
+
$list = $users->list(page: 2); // UserDto[]
14
+
```
15
+
16
+
Конструктор:
17
+
18
+
```php
19
+
new UserSDK(
20
+
array $headers = [], // HTTP-заголовки, зокрема токен
21
+
string|int|null $requestId = null, // id запиту; за замовчуванням uniqid()
22
+
string $rpcVersion = '2.0',
23
+
?HttpClientInterface $httpClient = null, // власний Symfony HttpClient
24
+
array $httpRequestOptions = [], // опції HttpClient (timeout, proxy, ...)
25
+
?IRpcSpecialParamHandler $rpcSpecialParams = null,
26
+
iterable $handlers = [], // обробники відповіді; порожньо — стандартні
27
+
string $transportName = 'sync', // ключ адреси в sdk_config.yaml
28
+
)
29
+
```
30
+
31
+
Назва заголовка з токеном не фіксована — вона така, як на сервері (`security.token_name`, за замовчуванням `Ufo-RPC-Token`).
32
+
33
+
### Адреса сервера
34
+
35
+
Адреса береться з `sdk_config.yaml` (якщо є) або `sdk_config.yaml.dist` поруч із класами — за назвою постачальника (останній сегмент простору імен класу) і `transportName`. Немає запису — `ConfigNotFoundException`.
36
+
37
+
## Fluent-методи
38
+
39
+
| Метод | Що робить |
40
+
| --- | --- |
41
+
| `withHeaders(array $headers)` | Додати заголовки до наступних запитів (лише синхронні класи) |
42
+
| `withoutCache()` / `withCache()` | Передати серверу `$rpc.ignoreCache: true` / `false` — обійти або використати [кеш відповіді](/docs/api/json-rpc-bundle/add_rpc_service/cache) |
43
+
| `rayId(string $id)` | Передати `$rpc.rayId` для трасування ланцюжка запитів |
44
+
| `setId(string\|int $id)` / `setRequestId()` | Задати id запиту |
45
+
| `resetConfig()` | Скинути спеціальні параметри |
46
+
47
+
```php
48
+
$user = $users->withoutCache()->rayId($traceId)->get(5);
49
+
```
50
+
51
+
Синхронні класи скидають спеціальні параметри й генерують новий id після кожного успішного запиту. Кожен запит містить `$rpc` (`timeout`, `ignoreCache` і, якщо задано, `rayId`, `callback`); сервери на JsonRpcBundle його розуміють, інші сервери отримують додатковий параметр.
52
+
53
+
## Результат
54
+
55
+
Тип результату визначається з `@return` згенерованого методу, і відповідь сервера перетворюється на нього ланцюжком обробників:
56
+
57
+
| Обробник | Пріоритет | Що перетворює |
58
+
| --- | --- | --- |
59
+
| `EnumResponseHandler` | 100 | значення → case enum |
60
+
| `UnionResponseHandler` | 80 | union-типи |
61
+
| `CollectionResponseHandler` | 60 | масиви елементів |
62
+
| `DtoResponseHandler` | 20 | об'єкти → DTO |
63
+
64
+
Власні обробники — див. [Розширення](/docs/api/sdk/client/extending).
65
+
66
+
## Помилки
67
+
68
+
* **Валідація параметрів** виконується до запиту за обмеженнями з документації сервера. Порушення — `Ufo\RpcError\ConstraintsImposedException` (або інший `AbstractRpcErrorException` за кодом) **без** обгортки.
69
+
* **Помилки сервера й транспорту** загортаються в `Ufo\RpcSdk\Exceptions\SdkException`: його `getCode()` — код помилки JSON-RPC, а типізований виняток `rpc-exceptions` (наприклад, `RpcDataNotFoundException` для `-32404`) — у `getPrevious()`.
70
+
71
+
```php
72
+
use Ufo\RpcError\RpcDataNotFoundException;
73
+
use Ufo\RpcSdk\Exceptions\SdkException;
74
+
75
+
try {
76
+
$user = $users->get($id);
77
+
} catch (SdkException $e) {
78
+
if ($e->getPrevious() instanceof RpcDataNotFoundException) {
79
+
// користувача немає
80
+
}
81
+
throw $e;
82
+
}
83
+
```
84
+
85
+
:::warning
86
+
Не ловіть `RpcDataNotFoundException` та інші винятки `rpc-exceptions` напряму — з синхронного виклику вони не вилітають, лише всередині `SdkException`.
87
+
:::
88
+
89
+
## Batch і notifications
90
+
91
+
SDK надсилає лише одиночні запити з `id`. [Batch](/docs/api/json-rpc-bundle/functionality/batch) і [notifications](/docs/api/json-rpc-bundle/functionality/notifications) через згенеровані класи не підтримуються.
92
+
93
+
## Налагодження
94
+
95
+
`Ufo\RpcSdk\Procedures\RequestResponseStack::getAll()` повертає всі запити, заголовки й відповіді поточного процесу.
96
+
97
+
:::warning
98
+
`getLastStack()`, `getLastRequest()` і `getLastResponse()` у 5.0.2 працюють неправильно — див. [Актуальні помилки](/docs/api/sdk/client/known_issues/open). Використовуйте `getAll()`.
99
+
:::