docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/json-rpc-bundle/README.md
новий файл +93
−0
1
+
# JsonRpcBundle
2
+
3
+
:::block class="floatinginfobox"
4
+
<include>(docs/api/json-rpc-bundle/.info.md)
5
+
:::
6
+
7
+
JSON-RPC 2.0 сервер для Symfony 7.2+ / 8 (PHP 8.4+).
8
+
9
+
> Робити RPC сервіси для сервіс-орієнтованої архітектури на Symfony ще ніколи не було так просто.
10
+
11
+
Будь-який сервіс вашого застосунку стає API: реалізуйте інтерфейс `IRpcService` — і його публічні методи доступні як JSON-RPC методи. Валідація, перетворення типів, безпека, кеш і документація OpenRPC беруться з коду, який ви вже написали.
12
+
13
+
## Від класу до API
14
+
15
+
::::columns
16
+
:::col
17
+
**Ваш код**
18
+
19
+
```php
20
+
#[RPC\Info('User')]
21
+
final class UserApi implements IRpcService
22
+
{
23
+
public function __construct(private UserService $users) {}
24
+
25
+
/**
26
+
* Returns a user by id
27
+
* @throws UserNotFoundException
28
+
*/
29
+
#[RPC\Cache(lifetimeSecond: RPC\Cache::T_HOUR)]
30
+
public function get(int $id): UserDto
31
+
{
32
+
return $this->users->get($id);
33
+
}
34
+
}
35
+
```
36
+
:::
37
+
38
+
:::col
39
+
**Запит**
40
+
41
+
```json
42
+
{"jsonrpc": "2.0", "id": 1, "method": "User.get", "params": {"id": 5}}
43
+
```
44
+
45
+
**Відповідь**
46
+
47
+
```json
48
+
{
49
+
"jsonrpc": "2.0",
50
+
"id": 1,
51
+
"result": {"id": 5, "email": "user@example.com", "name": "John"}
52
+
}
53
+
```
54
+
:::
55
+
::::
56
+
57
+
Більше нічого писати не треба:
58
+
59
+
* `GET /rpc` уже повертає документацію OpenRPC з методом `User.get`, схемою `UserDto` і помилкою з `@throws`, а `GET /rpc/postman` — готову колекцію Postman;
60
+
* неправильний тип `id` поверне помилку `-32602` з поясненням по параметру;
61
+
* у prod-оточенні відповідь кешується на годину;
62
+
* той самий метод можна викликати з консолі, з черги Symfony Messenger, у batch разом з іншими методами — і, через розширення, як REST-ендпоінт чи інструмент для AI-агента.
63
+
64
+
## Чому JsonRpcBundle
65
+
66
+
* **Документація не відстає від коду.** OpenRPC і Postman будуються з типів PHP, PHPDoc, DTO, enum і обмежень валідації; назви методів перекладаються за `Accept-Language` ([Документація API](/docs/api/json-rpc-bundle/documentation)).
67
+
* **Один метод — багато транспортів.** HTTP, консоль, Symfony Messenger, а через розширення — REST, MCP, Mercure ([Асинхронність](/docs/api/json-rpc-bundle/functionality/async), [Виклик з консолі](/docs/api/json-rpc-bundle/functionality/cli)).
68
+
* **Еволюція без болю.** Кілька [версій API](/docs/api/json-rpc-bundle/functionality/versions) поруч (`/rpc`, `/rpc/v2`) і кілька [груп API](/docs/api/json-rpc-bundle/functionality/groups) в одному застосунку — публічна, внутрішня, BFF — зі своїми методами й токенами.
69
+
* **Менше запитів по мережі.** [Batch](/docs/api/json-rpc-bundle/functionality/batch) із залежностями `@FROM:<id>(<поле>)`, [notifications](/docs/api/json-rpc-bundle/functionality/notifications) «вистрілив і забув», результат на [webhook](/docs/api/json-rpc-bundle/functionality/callback).
70
+
* **Декларативність замість рутини.** [Валідація](/docs/api/json-rpc-bundle/add_rpc_service/assertions), [DTO й конвертація типів](/docs/api/json-rpc-bundle/add_rpc_service/params), [кеш](/docs/api/json-rpc-bundle/add_rpc_service/cache) і [блокування](/docs/api/json-rpc-bundle/add_rpc_service/lock) — атрибутами на методі.
71
+
* **Розширюваність.** [Події](/docs/api/json-rpc-bundle/functionality/events) навколо кожного виклику й точки розширення ядра ([Для розробників](/docs/api/json-rpc-bundle/developers)).
72
+
73
+
:::info
74
+
<include>(change_log/latest.md)
75
+
:::
76
+
77
+
## Екосистема
78
+
79
+
* **AI-агенти.** [MCP Bundle](/docs/api/mcp-bundle) відкриває ваші RPC-методи як інструменти для Claude Code, Cursor, Gemini CLI та OpenAI — без окремого коду.
80
+
* **REST.** [REST Bundle](/docs/api/rest-bundle) публікує вибрані методи як REST API з документацією OpenAPI.
81
+
* **Клієнти.** [JSON-RPC Client SDK](/docs/api/sdk/client) генерує PHP-клієнт з класами процедур і DTO, [RPC TS SDK](/docs/api/sdk/ts) — TypeScript-інтерфейси з документа OpenRPC.
82
+
* **Правила для ШІ-асистентів.** [Файли інструкцій](/docs/api/json-rpc-bundle/developers/ai), щоб Claude Code, Codex чи Cursor правильно працювали з бандлом.
83
+
84
+
Повний перелік — на сторінці [Розширення](/docs/api/json-rpc-bundle/developers/extensions).
85
+
86
+
## З чого почати
87
+
88
+
1. [Встановіть бандл](/docs/api/json-rpc-bundle/installation) — `composer require ufo-tech/json-rpc-bundle` і два конфігураційні файли.
89
+
2. [Додайте власні методи](/docs/api/json-rpc-bundle/add_rpc_service) і відкрийте `GET /rpc`, щоб побачити документацію.
90
+
3. Налаштуйте [безпеку й інші параметри](/docs/api/json-rpc-bundle/config).
91
+
4. Перегляньте [можливості](/docs/api/json-rpc-bundle/functionality/batch): batch, notifications, асинхронність, події.
92
+
93
+
Не впевнені, чи підходить вам JSON-RPC? Прочитайте статтю [RPC, REST та GraphQL](/articles/api/rpc_vs_rest_vs_graphql) — коротко й практично про те, коли який підхід доречний.
uk/docs/api/json-rpc-bundle/.info.md
+1
−1
49
49
50
50
51
51
52
−
52
+
53
53
:::
54
54
::::
55
55
uk/docs/api/json-rpc-bundle/change_log/latest.md
новий файл +1
−0
1
+
<include>(10.4.2.md)
uk/docs/api/json-rpc-bundle/change_log/10.4.2.md
новий файл +17
−0
1
+
## Версія 10.4
2
+
3
+
### Ключові зміни
4
+
5
+
* [Переклади для груп API](/docs/api/json-rpc-bundle/documentation): `translations/rpc/<group>.<locale>.yaml`; група важливіша за мову.
6
+
* Переклади з розширень (`translations.paths`), публічний сервіс `RpcLocaleNegotiator`.
7
+
* 10.4.1: `IApiRouteImport` — маршрути адаптера можна підключити окремо для кожної групи API.
8
+
* 10.4.2: `RpcExecutor` — єдина точка входу для адаптерів (REST, MCP); `rpc.post_response` запускається для будь-якого джерела запиту і для кожного виконаного елемента batch.
9
+
10
+
### Що врахувати
11
+
12
+
* Частковий базовий переклад: відсутній `description` береться з базового перекладу мовою `kernel.default_locale`, а не з атрибута / PHPDoc.
13
+
* REST-виклики тепер отримують `rpc.post_response`: для них запрацюють зв'язки кешу й async/notification-лістенери.
14
+
15
+
### Зміни оточення
16
+
17
+
* Без змін відносно 10.3.