docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/json-rpc-bundle/functionality/groups.md
новий файл +132
−0
1
+
# Групи API
2
+
3
+
:::info
4
+
Доступно з версії 10.2. Застосунки без груп працюють як раніше: усе належить до групи за замовчуванням `general`.
5
+
:::
6
+
7
+
Групи дозволяють мати в одному застосунку кілька RPC API — наприклад, публічний для клієнтів, внутрішній для адмінки та окремі BFF. Кожна група має свою адресу, набір методів, версії, документацію та, за потреби, свою перевірку токенів.
8
+
9
+
## Точки входу
10
+
11
+
Імпортуйте маршрути бандла один раз для кожного API. `prefix` задає адресу, а `defaults.api_group` — групу (без нього — `general`):
12
+
13
+
```yaml
14
+
# config/routes/ufo_json_rpc.yaml
15
+
ufo_json_rpc:
16
+
resource: ../../vendor/ufo-tech/json-rpc-bundle/config/router.yaml
17
+
prefix: /rpc
18
+
trailing_slash_on_root: false
19
+
20
+
ufo_json_rpc_internal:
21
+
resource: ../../vendor/ufo-tech/json-rpc-bundle/config/router.yaml
22
+
prefix: /rpc/internal
23
+
defaults:
24
+
api_group: internal
25
+
trailing_slash_on_root: false
26
+
27
+
ufo_json_rpc_public:
28
+
resource: ../../vendor/ufo-tech/json-rpc-bundle/config/router.yaml
29
+
prefix: /rpc/public
30
+
defaults:
31
+
api_group: public
32
+
trailing_slash_on_root: false
33
+
```
34
+
35
+
`POST /rpc/internal` виконує запит, `GET /rpc/internal` повертає OpenRPC, `GET /rpc/internal/postman` — Postman; версійні адреси — `/rpc/internal/v2` тощо. Документація групи містить лише її методи й версії.
36
+
37
+
Назви маршрутів отримують префікс групи: `general_ufo_rpc_api_server`, `internal_ufo_rpc_api_server`, … Старі назви без префікса лишаються аліасами для `general`, тож `router->generate('ufo_rpc_api_server')` працює як раніше.
38
+
39
+
## `#[RPC\APIGroups]`
40
+
41
+
Атрибут на класі або методі визначає, до яких груп належить метод:
42
+
43
+
```php
44
+
public function __construct(array $groups = [], bool $withDefault = true)
45
+
```
46
+
47
+
`withDefault: true` додає групу `general`, `false` — ні.
48
+
49
+
```php
50
+
use Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService;
51
+
use Ufo\RpcObject\RPC;
52
+
53
+
#[RPC\Info('catalog')]
54
+
#[RPC\APIGroups(['internal', 'public'], false)]
55
+
class CatalogApi implements IRpcService
56
+
{
57
+
public function list(): array { /* ... */ } // internal і public
58
+
59
+
#[RPC\APIGroups(['internal'], false)]
60
+
public function updatePrice(int $productId, int $price): true { return true; } // лише internal
61
+
62
+
#[RPC\APIGroups(['public'], false)]
63
+
public function featured(): array { return [1]; } // лише public
64
+
65
+
#[RPC\APIGroups()]
66
+
public function status(): string { return 'ok'; } // лише general
67
+
68
+
#[RPC\APIGroups(['internal'], false)]
69
+
#[RPC\IgnoreApi]
70
+
public function rebuildIndex(): true { return true; } // ніде не публікується
71
+
}
72
+
```
73
+
74
+
| Метод | `/rpc` (general) | `/rpc/internal` | `/rpc/public` |
75
+
| --- | --- | --- | --- |
76
+
| `catalog.list` | — | так | так |
77
+
| `catalog.updatePrice` | — | так | — |
78
+
| `catalog.featured` | — | — | так |
79
+
| `catalog.status` | так | — | — |
80
+
| `catalog.rebuildIndex` | — | — | — |
81
+
82
+
Правила:
83
+
84
+
* атрибут методу повністю замінює групи класу; без атрибутів метод належить до `general`;
85
+
* `APIGroups([], false)` не публікує метод у жодній групі; `#[RPC\IgnoreApi]` має пріоритет над групами;
86
+
* `general` — це не «усі групи», а звичайна група за замовчуванням;
87
+
* карти методів і [версії](/docs/api/json-rpc-bundle/functionality/versions) розділені за групами: метод іншої групи повертає `Method not found`;
88
+
* для HTTP групу визначає маршрут, а не поле в JSON.
89
+
90
+
## Токени для груп
91
+
92
+
Без додаткових налаштувань усі групи перевіряє базовий валідатор (`security.clients_tokens` або ваш `ITokenValidator`). Окрему перевірку для груп задає `security.providers`. Кожен провайдер має **рівно один** з параметрів `service` або `clients_tokens` і непорожній `api_groups`.
93
+
94
+
```yaml
95
+
ufo_json_rpc:
96
+
security:
97
+
protected_api: true
98
+
token_name: 'Ufo-RPC-Token'
99
+
clients_tokens:
100
+
- '%env(resolve:UFO_API_TOKEN)%' # general та групи без провайдера
101
+
providers:
102
+
internal:
103
+
api_groups: [internal]
104
+
clients_tokens:
105
+
- '%env(resolve:UFO_INTERNAL_API_TOKEN)%'
106
+
public:
107
+
service: App\Security\UserTokenValidator # реалізує ITokenValidator
108
+
api_groups: [public]
109
+
```
110
+
111
+
* Провайдер замінює базову перевірку для своїх груп; якщо він відхилив токен, базова перевірка не запускається.
112
+
* Два провайдери для однієї групи, відсутній сервіс або клас без `ITokenValidator` — помилка компіляції контейнера.
113
+
* `protected_api`, `protected_doc` і `token_name` спільні для всіх груп; захищена документація перевіряється провайдером своєї групи.
114
+
115
+
## Консоль і async
116
+
117
+
```bash
118
+
bin/console ufo:rpc:process '{"jsonrpc":"2.0","id":1,"method":"catalog.updatePrice","params":{"productId":1,"price":100}}' \
119
+
--api-group=internal --ver=v1
120
+
```
121
+
122
+
Дочірні процеси batch зберігають групу й версію маршруту. Для Symfony Messenger групу передають явно:
123
+
124
+
```php
125
+
$message = new \Ufo\RpcObject\RpcAsyncRequest($request, $token, apiGroup: 'internal');
126
+
```
127
+
128
+
Повідомлення без групи виконуються в `general`.
129
+
130
+
## Переклади для групи
131
+
132
+
Назви й описи методів у документації можна перевизначити для окремої групи — файлами `translations/rpc/<group>.<locale>.yaml`. Див. [Документація API](/docs/api/json-rpc-bundle/documentation).