docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/json-rpc-bundle/developers/README.md
новий файл +122
−0
1
+
# Для розробників
2
+
3
+
JsonRpcBundle — не закритий продукт «все в одному», а ядро, на якому можна будувати власні рішення. Він закриває основу будь-якого RPC API: прийом запитів, карту методів, валідацію, конвертацію даних, безпеку, кеш і документацію. Усе, що виходить за ці межі, — нові транспорти, протоколи, інтеграції, інструменти — задумано як розширення.
4
+
5
+
Цей розділ для тих, хто хоче зрозуміти, як бандл працює всередині, і розширювати його: у власному проєкті чи окремим пакетом для спільноти.
6
+
7
+
## Принципи, на яких побудовано бандл
8
+
9
+
**Код — єдине джерело правди.** Методи API — це звичайні PHP-методи. Назви, типи, PHPDoc, атрибути й обмеження валідації одночасно визначають поведінку і документацію, тож вони не розходяться.
10
+
11
+
**Мінімум налаштувань.** Достатньо реалізувати `IRpcService` — решту бандл виводить сам: карту методів, схеми параметрів і результатів, конвертацію типів. Конфігурація потрібна лише там, де є реальний вибір.
12
+
13
+
**Незалежність від транспорту.** Процедура не знає, звідки прийшов запит: HTTP, консоль, черга повідомлень, REST чи MCP через розширення. Валідація, безпека, кеш і події однакові для всіх.
14
+
15
+
**Відкритість до розширення.** Ключові етапи обробки — події, а основні механізми — інтерфейси з автоконфігурацією: конвертери параметрів, генератори схем, джерела методів, стратегії batch, валідатори токенів, завантажувачі маршрутів. Нову поведінку додають, не змінюючи ядра.
16
+
17
+
**Рідні механізми Symfony.** DI-контейнер, EventDispatcher, Messenger, Lock, Validator, Cache, Translation — бандл не винаходить власних аналогів, тож розширення пишуться звичними для Symfony способами.
18
+
19
+
**Відповідність стандарту.** Протокол — [JSON-RPC 2.0](https://www.jsonrpc.org/specification), документація — [OpenRPC](https://spec.open-rpc.org/). Клієнти й інструменти, що підтримують стандарти, працюють з API без адаптації.
20
+
21
+
**Продуктивність без жертв.** Карта методів і метадані будуються під час компіляції контейнера, документація кешується, а дорога робота переноситься на після відправлення відповіді.
22
+
23
+
## Що є в розділі
24
+
25
+
* [Життєвий цикл](/docs/api/json-rpc-bundle/developers/lifecycle) — як запит проходить через бандл для кожної точки входу і в який момент генерується кожна подія.
26
+
* [Розширення](/docs/api/json-rpc-bundle/developers/extensions) — перелік наявних розширень.
27
+
* [Події життєвого циклу](/docs/api/json-rpc-bundle/functionality/events) — детально про кожну подію і приклади лістенерів.
28
+
* [Правила для ШІ-асистентів](/docs/api/json-rpc-bundle/developers/ai) — файли інструкцій для Claude Code, Codex, Cursor, Copilot, що підключаються до ваших наявних правил.
29
+
* [Відомі помилки](/docs/api/json-rpc-bundle/developers/known_issues/open) — що працює не так, як очікується, і як це обійти.
30
+
31
+
## Загальні положення для розширень
32
+
33
+
1. **Не дублюйте ядро.** Розширення не повинне мати власної карти методів, валідації чи формату помилок. Методи беруться з `ServiceMap` / `IServiceHolder`, виконання — через `RpcExecutor`, помилки — через `rpc.error`. Тоді `#[RPC\Assertions]`, `#[RPC\Cache]`, `#[RPC\Lock]`, конвертери й події працюють для вашого транспорту автоматично.
34
+
2. **Поважайте групи й версії API.** Визначайте [групу](/docs/api/json-rpc-bundle/functionality/groups) з маршруту чи конфігурації й записуйте її в `ApiGroupContext`; передавайте версію в `RpcRequest`.
35
+
3. **Перевіряйте токен самі.** `RpcExecutor` токен не перевіряє. Використовуйте `IRpcSecurity` з відповідним токен-холдером — так діятимуть ті самі `security.providers`, що й для основного API.
36
+
4. **Реєструйте маршрути через імпорт ядра.** Тоді кожен імпорт для окремої групи отримує унікальні назви маршрутів.
37
+
5. **Залежність від ядра — `ufo-tech/json-rpc-bundle: ^10.4.2`** або новіше, якщо використовуєте `RpcExecutor` та `IApiRouteImport`.
38
+
6. **Компоненти, що створюються під час компіляції** (`IServiceFiller`, `IConstraintGenerator`, `IParamConvertor`), бандл інстанціює сам під час збирання контейнера. Їхні конструктори можуть приймати лише сервіси, доступні на етапі компіляції, або теговані колекції — не скалярні параметри.
39
+
40
+
## Точки розширення
41
+
42
+
| Що | Як | Для чого |
43
+
| --- | --- | --- |
44
+
| `Routing\IApiRouteImport` | автоконфігурація, тег `ufo.rpc.route_import` | Підключити `router.yaml` розширення окремо для кожної групи API: `getResource()`, `getRouteNamePrefixAttribute()` |
45
+
| `Routing\RpcYamlFileLoader` / `ApiYamlFileLoader` | успадкування, тег `routing.loader` | Старіший спосіб власного завантажувача маршрутів |
46
+
| `Server\RpcExecutor` | автовайринг | `execute(IRpcRequestCarrier): RpcResponse` — виконати запит повним циклом ядра |
47
+
| `Server\RequestPrepare\IRpcRequestCarrier` / `IRpcHttpCarrier` | реалізація | Обгортка вашого вхідного запиту. `IRpcHttpCarrier::getHttpRequest()` прив'язує `rpc.post_response` до HTTP-запиту й дозволяє від'єднане виконання notifications |
48
+
| `Server\ServiceMap\IServiceHolder` | тег `rpc.service_holder` (вручну) | Власне джерело методів або фільтр поверх `ServiceMap` |
49
+
| `Security\Interfaces\IRpcSecurity`, `IRpcTokenHolder` | аліас / реалізація | Перевірка токена з вашого джерела (заголовок, параметр, повідомлення) |
50
+
| `Security\Interfaces\ITokenValidator` | аліас або `security.providers` | Власна перевірка токенів |
51
+
| `ParamConvertors\IParamConvertor` | автоконфігурація, тег `rpc.param_convertor` | Конвертація власних типів параметрів і результатів |
52
+
| `...\Reflections\Fillers\AbstractServiceFiller` | автоконфігурація, тег `ufo-rpc.service-iterator` | Читання власних атрибутів методів у метадані `Service` |
53
+
| `...\Generate\Interfaces\IConstraintGenerator` | тег `rpc.constraint` | JSON Schema для власних обмежень валідації |
54
+
| `Server\Batch\IBatchStrategy` | автоконфігурація, тег `rpc.batch_strategy` | Власна стратегія виконання batch |
55
+
| `DocAdapters\Outputs\AbstractPostmanAdapter` | успадкування | Колекція Postman для вашого транспорту |
56
+
| `Server\RpcLocaleNegotiator` | автовайринг | Вибір мови з `Accept-Language` для власної документації |
57
+
| `translations.paths` | `prependExtensionConfig()` | Переклади назв і описів методів, які постачає розширення |
58
+
| [Події](/docs/api/json-rpc-bundle/functionality/events) | `#[AsEventListener]` | Поведінка навколо виконання методів |
59
+
60
+
### Мінімальний адаптер
61
+
62
+
```php
63
+
// маршрути розширення для кожної групи API
64
+
final class AcmeRouteImport implements IApiRouteImport
65
+
{
66
+
public function getResource(): string { return __DIR__.'/../../config/router.yaml'; }
67
+
public function getRouteNamePrefixAttribute(): string { return '_acme_name_prefix'; }
68
+
}
69
+
70
+
// контролер розширення
71
+
final class AcmeController
72
+
{
73
+
public function __construct(
74
+
private RpcExecutor $executor,
75
+
private IRpcSecurity $security,
76
+
) {}
77
+
78
+
public function __invoke(Request $request): JsonResponse
79
+
{
80
+
$this->security->setTokenHolder(new HttpTokenHolder(/* ... */));
81
+
$this->security->isValidApiRequest();
82
+
83
+
$response = $this->executor->execute(new RpcFromAcme($request));
84
+
85
+
return new JsonResponse(/* серіалізований $response */);
86
+
}
87
+
}
88
+
```
89
+
90
+
```php
91
+
// переклади, що постачає розширення
92
+
public function prepend(ContainerBuilder $container): void
93
+
{
94
+
$container->prependExtensionConfig('ufo_json_rpc', [
95
+
'translations' => ['paths' => [__DIR__.'/../../translations']],
96
+
]);
97
+
}
98
+
```
99
+
100
+
Живі приклади — у коді `mcp-bundle` і `rest-bundle` (див. [Розширення](/docs/api/json-rpc-bundle/developers/extensions)).
101
+
102
+
## Розвиток екосистеми
103
+
104
+
Ми всіляко заохочуємо розвиток екосистеми навколо бандла. Кожен новий транспорт, адаптер чи інструмент робить JSON-RPC на Symfony зручнішим для всіх.
105
+
106
+
**Пишіть розширення.** Якщо вам бракує інтеграції — з брокером повідомлень, протоколом, системою моніторингу чи генератором клієнтів, — оформіть її окремим пакетом за загальними положеннями вище. Розкажіть про нього — і ми додамо його до [переліку розширень](/docs/api/json-rpc-bundle/developers/extensions).
107
+
108
+
**Повідомляйте про проблеми.** Знайшли помилку чи нестиковку з документацією — створіть issue в [репозиторії бандла](https://github.com/UFO-Tech/json-rpc-bundle/issues). Підтверджені проблеми ми описуємо в розділі [Відомі помилки](/docs/api/json-rpc-bundle/developers/known_issues/open).
109
+
110
+
**Пропонуйте зміни в ядро.** Якщо розширенню не вистачає точки розширення, це сигнал, що її варто додати в ядро. Порядок співпраці описано в [CONTRIBUTING.md](https://github.com/UFO-Tech/json-rpc-bundle/blob/main/CONTRIBUTING.md):
111
+
112
+
1. Зробіть fork і окрему гілку.
113
+
2. Перед роботою перевірте issue tracker; якщо обговорення немає — створіть issue з пропозицією.
114
+
3. Дотримуйтесь стилю коду проєкту.
115
+
4. Додайте тести для нових можливостей; усі наявні тести мають проходити.
116
+
5. Опишіть у pull request, яку проблему вирішено або що додано, і будьте готові до обговорення.
117
+
118
+
Беручи участь у проєкті, ви погоджуєтесь дотримуватись [правил поведінки](https://github.com/UFO-Tech/json-rpc-bundle/blob/main/CODE_OF_CONDUCT.md).
119
+
120
+
:::info
121
+
Про вразливості безпеки повідомляйте не через публічні issue, а за контактом із [SECURITY.md](https://github.com/UFO-Tech/json-rpc-bundle/blob/main/SECURITY.md) репозиторію.
122
+
:::