docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/sdk/bundle/usage.md
new file +70
−0
1
+
# Використання SDK Bundle
2
+
3
+
## Синхронні виклики
4
+
5
+
Згенеровані класи автоматично стають сервісами застосунку (з тегом `ufo.sdk_method_class`), тож їх достатньо запросити в конструкторі:
6
+
7
+
```php
8
+
use App\Sdk\Orders\UserSDK;
9
+
10
+
final class UserProfileService
11
+
{
12
+
public function __construct(private UserSDK $users) {}
13
+
14
+
public function profile(int $id): UserDto
15
+
{
16
+
return $this->users->withoutCache()->get($id);
17
+
}
18
+
}
19
+
```
20
+
21
+
Під час компіляції контейнера бандл (`SdkCompiler`) для кожного класу:
22
+
23
+
* знаходить постачальника за простором імен класу;
24
+
* передає заголовок `[token_key => token]`, якщо обидва параметри задано;
25
+
* передає обробники відповіді — сервіси з тегом `ufo.sdk_response_handler`, впорядковані за пріоритетом (так можна [додати власний](/docs/api/sdk/client/extending)).
26
+
27
+
Методи, fluent-параметри (`withoutCache()`, `rayId()`, `withHeaders()`), формат результату й обробка помилок — як у [Client SDK](/docs/api/sdk/client/usage).
28
+
29
+
## Асинхронні виклики
30
+
31
+
Класи `Async*SDK` отримують з конфігурації `token` і `async_secret`, а також сервіс `Ufo\Component\TransportContracts\AsyncTransportFactory`, який бандл реєструє сам. Йому потрібен хоча б один resolver транспорту — для RabbitMQ:
32
+
33
+
```bash
34
+
composer require ufo-tech/component-transport-amqp
35
+
```
36
+
37
+
```yaml
38
+
# config/services.yaml
39
+
services:
40
+
Symfony\Component\Messenger\Bridge\Amqp\Transport\AmqpTransportFactory: ~
41
+
42
+
Ufo\Component\AsyncAmqpTransport\AMQPTransportResolver:
43
+
autowire: true
44
+
autoconfigure: true # тег ufo.async_transport_resolver
45
+
```
46
+
47
+
```php
48
+
public function __construct(private AsyncReportSDK $reports) {}
49
+
50
+
$this->reports->callbackTo('https://my-app.example.com/rpc-callback')->build($month); // true
51
+
```
52
+
53
+
Пакет AMQP — бібліотека, а не бандл, тож resolver реєструється в сервісах застосунку вручну. Без жодного resolver-а виклик завершиться `TransportNotFoundException`. Особливості асинхронних викликів — [Client SDK: асинхронні виклики](/docs/api/sdk/client/async).
54
+
55
+
:::info subtitle="Версії 3.x"
56
+
У 3.x асинхронні класи працювали напряму з Symfony Messenger (`TransportFactoryInterface`) і окремого resolver-а не потребували. Під час оновлення до 4.0 додайте resolver і перегенеруйте SDK.
57
+
:::
58
+
59
+
## Помилки
60
+
61
+
* Помилки сервера й транспорту — `Ufo\RpcSdk\Exceptions\SdkException` з типізованим винятком у `getPrevious()` — див. [Client SDK](/docs/api/sdk/client/usage).
62
+
* Немає адреси постачальника в `sdk_config.yaml(.dist)` — `ConfigNotFoundException`.
63
+
64
+
:::warning
65
+
Якщо клас лежить поза простором імен налаштованого постачальника (наприклад, згенерований `ufo:sdk:make` для постачальника, якого немає в `vendors`), бандл мовчки не передасть йому ні токен, ні обробники. Симптом — помилка токена `-32401` від сервера. Див. [Актуальні помилки](/docs/api/sdk/bundle/known_issues/open).
66
+
:::
67
+
68
+
## Тестування
69
+
70
+
Згенеровані класи — звичайні сервіси, тож у тестовому оточенні їх можна перевизначити заглушками (`config/services_test.yaml`). У модульних тестах клас можна створити вручну з Symfony `MockHttpClient` в аргументі `$httpClient`.