← Актуальні помилки Client SDK
docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/sdk/client/known_issues/open.md
новий файл +49
−0
1
+
# Актуальні помилки Client SDK
2
+
3
+
Відомі помилки й нестиковки поточної версії `ufo-tech/json-rpc-client-sdk` (5.0.2). Виправлені — на сторінці [Виправлені помилки](/docs/api/sdk/client/known_issues/fixed).
4
+
5
+
<include>(.issues/errors-wrapped-in-sdk-exception.md)
6
+
7
+
---
8
+
9
+
<include>(.issues/async-params-not-reset.md)
10
+
11
+
---
12
+
13
+
<include>(.issues/sync-reset-skipped-on-error.md)
14
+
15
+
---
16
+
17
+
<include>(.issues/async-ping-fatal.md)
18
+
19
+
---
20
+
21
+
<include>(.issues/async-no-api-group.md)
22
+
23
+
---
24
+
25
+
<include>(.issues/response-schema-cached-by-method.md)
26
+
27
+
---
28
+
29
+
<include>(.issues/request-response-stack.md)
30
+
31
+
---
32
+
33
+
<include>(.issues/enum-try-from-value.md)
34
+
35
+
---
36
+
37
+
<include>(.issues/url-in-attr-ignored.md)
38
+
39
+
---
40
+
41
+
<include>(.issues/make-script-limits.md)
42
+
43
+
---
44
+
45
+
<include>(.issues/return-docblock-default.md)
46
+
47
+
---
48
+
49
+
<include>(.issues/readme-outdated.md)
uk/docs/api/sdk/client/known_issues/.issues/errors-wrapped-in-sdk-exception.md
новий файл +11
−0
1
+
### Типізовані помилки сервера приходять лише всередині `SdkException`
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 5.0.2 (поточна). Нестиковка з очікуваннями й README; перевірено за кодом тегу 5.0.2.
5
+
:::
6
+
7
+
**Симптом.** `catch (RpcDataNotFoundException $e)` навколо синхронного виклику ніколи не спрацьовує.
8
+
9
+
**Причина.** `AbstractProcedure::requestApi()` загортає будь-який виняток у `Ufo\RpcSdk\Exceptions\SdkException`; виняток `rpc-exceptions` доступний через `getPrevious()`, код JSON-RPC — через `getCode()`. Помилки валідації параметрів, навпаки, вилітають без обгортки.
10
+
11
+
**Обхідний шлях.** Ловіть `SdkException` і перевіряйте `getPrevious()` — див. [Використання](/docs/api/sdk/client/usage).
uk/docs/api/sdk/client/known_issues/.issues/async-params-not-reset.md
новий файл +9
−0
1
+
### Асинхронні виклики не скидають спеціальні параметри і не змінюють id
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 4.2.0 — 5.0.2 (поточна). Перевірено за кодом тегу 5.0.2; у 4.2.x скидання додано лише для синхронних класів.
5
+
:::
6
+
7
+
**Симптом.** Після `callbackTo()`, `asyncTimeout()`, `rayId()` чи `withoutCache()` на асинхронному об'єкті параметр діє на **всі** наступні виклики цього об'єкта; усі виклики мають однаковий id.
8
+
9
+
**Обхідний шлях.** Викликайте `resetConfig()` і `setId()` перед кожним викликом або створюйте новий об'єкт для кожного запиту з особливими параметрами.
uk/docs/api/sdk/client/known_issues/.issues/sync-reset-skipped-on-error.md
новий файл +11
−0
1
+
### Після помилки синхронного виклику параметри й id не скидаються
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 5.0.2 (поточна). Перевірено за кодом тегу 5.0.2.
5
+
:::
6
+
7
+
**Симптом.** Якщо виклик завершився помилкою, спеціальні параметри (`withoutCache()`, `rayId()` тощо) і id переходять на наступний виклик того самого об'єкта.
8
+
9
+
**Причина.** Скидання параметрів і новий id виконуються лише на шляху успіху (`AbstractProcedure::requestApi()`).
10
+
11
+
**Обхідний шлях.** Після перехопленої помилки викликайте `resetConfig()` і `setId()`.
uk/docs/api/sdk/client/known_issues/.issues/async-ping-fatal.md
новий файл +11
−0
1
+
### `ping()` на асинхронному класі завершується фатальною помилкою
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 5.0.2 (поточна). Перевірено за кодом тегу 5.0.2.
5
+
:::
6
+
7
+
**Симптом.** `$asyncSdk->ping()` — `Error: Call to a member function getResult() on true`.
8
+
9
+
**Причина.** `ping()` оголошено в спільному `AbstractBaseProcedure` як `$this->requestApi()->getResult()`, а в асинхронних класах `requestApi()` повертає `true`.
10
+
11
+
**Обхідний шлях.** Перевіряйте доступність сервера синхронним класом.
uk/docs/api/sdk/client/known_issues/.issues/async-no-api-group.md
новий файл +11
−0
1
+
### Асинхронні виклики не передають групу API
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 5.0.2 (поточна). Перевірено за кодом тегу 5.0.2.
5
+
:::
6
+
7
+
**Симптом.** Асинхронний виклик методу, що належить не до групи `general`, сервер відхиляє як `Method not found`.
8
+
9
+
**Причина.** `AbstractAsyncProcedure` створює `RpcAsyncRequest` без `apiGroup`; сервер у такому разі використовує `general`.
10
+
11
+
**Обхідний шлях.** Для асинхронних викликів використовуйте методи групи `general`.
uk/docs/api/sdk/client/known_issues/.issues/response-schema-cached-by-method.md
новий файл +11
−0
1
+
### Схема результату кешується лише за назвою методу
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 5.0.2 (поточна). Перевірено за кодом тегу 5.0.2.
5
+
:::
6
+
7
+
**Симптом.** Якщо в одному процесі є два SDK-класи (різні постачальники чи версії API) з однаковою назвою RPC-методу, наприклад `User.get`, відповідь другого перетворюється за схемою, простором імен і обробниками першого — результат отримує DTO не того класу або падає.
8
+
9
+
**Причина.** `SdkResponseCreator::$instances` ключується лише назвою методу.
10
+
11
+
**Обхідний шлях.** Не використовуйте в одному процесі кількох постачальників з однаковими назвами методів або давайте методам різні назви на сервері.
uk/docs/api/sdk/client/known_issues/.issues/request-response-stack.md
новий файл +11
−0
1
+
### `RequestResponseStack::getLast*()` не працюють
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 5.0.2 (поточна). Перевірено за кодом тегу 5.0.2.
5
+
:::
6
+
7
+
**Симптом.** `getLastStack()`, `getLastRequest()`, `getLastResponse()` після виклику дають помилку невизначеного індексу й `TypeError`. Асинхронні виклики перезаписують один і той самий запис стека.
8
+
9
+
**Причина.** `addResponse()` збільшує лічильник, а `getLast*()` читають запис за новим, ще порожнім індексом. Асинхронні класи не викликають `addResponse()`.
10
+
11
+
**Обхідний шлях.** Використовуйте `RequestResponseStack::getAll()` і беріть останній елемент.
uk/docs/api/sdk/client/known_issues/.issues/enum-try-from-value.md
новий файл +11
−0
1
+
### `tryFromValue()` згенерованих enum кидає `TypeError`
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 5.0.2 (поточна). Перевірено за шаблоном `templates/enum.php.twig` тегу 5.0.2.
5
+
:::
6
+
7
+
**Симптом.** `OrderStatus::tryFromValue('unknown')` замість `null` — `TypeError`.
8
+
9
+
**Причина.** Метод оголошено як `: self`, а він повертає `self::tryFrom()`, тобто `?self`.
10
+
11
+
**Обхідний шлях.** Використовуйте вбудований `OrderStatus::tryFrom()`.
uk/docs/api/sdk/client/known_issues/.issues/url-in-attr-ignored.md
новий файл +11
−0
1
+
### `urlInAttr` / `generate_url_in_attr` не впливає на генерацію
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 5.0.2 (поточна). Перевірено за кодом тегу 5.0.2.
5
+
:::
6
+
7
+
**Симптом.** Атрибут `#[ApiUrl]` з адресою сервера ніколи не з'являється в згенерованих класах; адреса завжди береться з `sdk_config.yaml(.dist)`.
8
+
9
+
**Причина.** `SdkProcedureMaker` передає в шаблон `apiUrlInAttr`, але шаблони його не використовують.
10
+
11
+
**Обхідний шлях.** Задавайте адреси через `sdk_config.yaml`.
uk/docs/api/sdk/client/known_issues/.issues/make-script-limits.md
новий файл +14
−0
1
+
### `bin/make.php` не дозволяє задати простір імен і заголовки
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 5.0.2 (поточна). Перевірено за кодом тегу 5.0.2.
5
+
:::
6
+
7
+
**Симптом.**
8
+
9
+
* Простір імен жорстко заданий як `Ufo\RpcSdk\Client`, а його ж пакет зіставляє у своєму `composer.json` з власним каталогом `sdk/`, тож у встановленому як залежність пакеті згенеровані файли можуть потрапити у `vendor/`.
10
+
* Документацію запитує без заголовків — захищену `protected_doc` документацію не отримати.
11
+
* Без аргументу читає `bin/schema.json`, якого немає в пакеті.
12
+
* `Maker::make()` без callback завершується помилкою (callback викликається без перевірки на `null`).
13
+
14
+
**Обхідний шлях.** Генеруйте через [SDK Bundle](/docs/api/sdk/bundle/commands) або з коду з власним `ConfigsHolder` і `HttpReader` із заголовками — див. [Генерація](/docs/api/sdk/client/generation).
uk/docs/api/sdk/client/known_issues/.issues/return-docblock-default.md
новий файл +11
−0
1
+
### Метод без `@return` дає попередження
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 5.0.2 (поточна). Перевірено за кодом тегу 5.0.2.
5
+
:::
6
+
7
+
**Симптом.** Для методу згенерованого класу без тегу `@return` (наприклад, після ручного редагування) — PHP warning про невизначений індекс.
8
+
9
+
**Причина.** `(string)$tags[0] ?? 'mixed'` у `SdkResponseCreator`: приведення типу виконується до `??`, тож значення за замовчуванням не застосовується.
10
+
11
+
**Обхідний шлях.** Не прибирайте `@return` із згенерованих класів.
uk/docs/api/sdk/client/known_issues/.issues/readme-outdated.md
новий файл +11
−0
1
+
### README пакета застарів
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 5.0.2 (поточна). Нестиковка документації, на роботу не впливає.
5
+
:::
6
+
7
+
* Методи `->timeout()` і `->callback()` насправді називаються `asyncTimeout()` і `callbackTo()`.
8
+
* Маска «лише синхронні» в таблиці — `#Command.run`; правильно `&Command.run`.
9
+
* Приклад використання з `UserProcedure` / `PingProcedure` — з версій 2.x–3.x; зараз класи називаються `<Назва>SDK`, результати — DTO.
10
+
* Вказано `ufo-tech/rpc-objects` ^3.7, у `composer.json` — ^3.8; Symfony 8 і `rpc-exceptions` ^2 не згадано.
11
+
* Посилання на документацію веде на стару вікі `docs.ufo-tech.space`.