docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/json-rpc-bundle/add_rpc_service/README.md
новий файл +141
−0
1
+
# Власні API методи
2
+
3
+
Будь-який клас застосунку стає API-сервісом, якщо реалізує інтерфейс `Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService`. Інтерфейс не нав'язує логіки — він лише позначає клас тегом `ufo.rpc.service`, за яким бандл збирає карту методів під час компіляції контейнера.
4
+
5
+
Кожен публічний нестатичний метод такого класу (крім конструктора) стає JSON-RPC методом з назвою `<назва класу>.<метод>`.
6
+
7
+
```php
8
+
<?php
9
+
10
+
namespace App\Api;
11
+
12
+
use Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService;
13
+
use Ufo\RpcObject\RPC;
14
+
15
+
#[RPC\Info('Messenger')]
16
+
class MessengerApi implements IRpcService
17
+
{
18
+
public function __construct(private Mailer $mailer) {}
19
+
20
+
/**
21
+
* A method for sending an email message
22
+
* @param string $email The email address
23
+
* @param string $text Message body
24
+
* @param string $subject Optional message subject parameter
25
+
*/
26
+
public function sendEmail(string $email, string $text, string $subject = 'Message without subject'): bool
27
+
{
28
+
return $this->mailer->send($email, $subject, $text);
29
+
}
30
+
}
31
+
```
32
+
33
+
У прикладі з'явиться метод `Messenger.sendEmail`:
34
+
35
+
::::columns
36
+
:::col
37
+
**Request**
38
+
```json
39
+
{
40
+
"jsonrpc": "2.0",
41
+
"id": 1,
42
+
"method": "Messenger.sendEmail",
43
+
"params": {
44
+
"email": "user@example.com",
45
+
"text": "Hello!"
46
+
}
47
+
}
48
+
```
49
+
:::
50
+
:::col
51
+
**Response**
52
+
```json
53
+
{
54
+
"jsonrpc": "2.0",
55
+
"id": 1,
56
+
"result": true
57
+
}
58
+
```
59
+
:::
60
+
::::
61
+
62
+
Параметри можна передавати й позиційно: `"params": ["user@example.com", "Hello!"]`.
63
+
64
+
:::info
65
+
Карта методів будується під час компіляції контейнера. Після додавання чи зміни методів у `prod` виконайте `bin/console cache:clear`.
66
+
:::
67
+
68
+
## Іменування
69
+
70
+
Без атрибута назвою класу в API буде коротке ім'я класу (`MessengerApi.sendEmail`). Атрибут [`#[RPC\Info]`](/docs/api/json-rpc-bundle/add_rpc_service/info) задає псевдонім (`Messenger.sendEmail`), символ-роздільник і [версію API](/docs/api/json-rpc-bundle/functionality/versions).
71
+
72
+
:::success subtitle="Гарна практика"
73
+
Сприймайте назву класу як простір імен, а назву методу — як дію: `Cart.addProduct`, `Cart.getProducts`, `Messenger.sendEmail`, `Messenger.sendSms`. Так одноіменні методи різних класів не конфліктують (`Product.create`, `User.create`), а з назв зрозуміло, що вміє сервер.
74
+
:::
75
+
76
+
## Опис методів і параметрів
77
+
78
+
Документація будується з усього, що відомо про метод: назв, нативних типів, значень за замовчуванням і докблоків. Опис методу й параметрів береться з PHPDoc, а точний тип — з `@param` / `@return`, якщо нативного типу недостатньо:
79
+
80
+
```php
81
+
/**
82
+
* Creates an order
83
+
* @param OrderItemDto[] $items
84
+
* @return array<string, OrderItemDto>
85
+
*/
86
+
public function create(array $items, ?string $comment = null): array
87
+
```
88
+
89
+
Параметр з `null` за замовчуванням або зі значенням за замовчуванням необов'язковий. Детально про типи — на сторінці [Параметри методів](/docs/api/json-rpc-bundle/add_rpc_service/params), про результат — [Формат відповіді](/docs/api/json-rpc-bundle/add_rpc_service/response).
90
+
91
+
Назву (`summary`) і опис методу в документації можна перекласти, не змінюючи код — див. [Документація API](/docs/api/json-rpc-bundle/documentation).
92
+
93
+
## Застарілі методи
94
+
95
+
Метод з `@deprecated` у докблоці або з атрибутом `#[\Deprecated]` позначається в OpenRPC як `"deprecated": true`, але продовжує працювати.
96
+
97
+
```php
98
+
/**
99
+
* @deprecated use Orders.create
100
+
*/
101
+
public function createOrder(array $items): array
102
+
```
103
+
104
+
## Приховати метод з API
105
+
106
+
Публічний метод, який не має бути методом API, позначте `#[RPC\IgnoreApi]`: його немає ні в карті методів, ні в документації.
107
+
108
+
```php
109
+
#[RPC\IgnoreApi]
110
+
public function rebuildIndex(): void
111
+
```
112
+
113
+
## Сервіси в аргументах методу
114
+
115
+
Окрім ін'єкції через конструктор, сервіс можна отримати прямо в аргументі методу через `#[Autowire]`. Такий аргумент не є RPC-параметром: його немає в документації, і клієнт його не передає.
116
+
117
+
```php
118
+
use Symfony\Component\DependencyInjection\Attribute\Autowire;
119
+
120
+
public function report(int $id, #[Autowire(service: 'app.report_builder')] ReportBuilder $builder): array
121
+
```
122
+
123
+
:::warning
124
+
У версіях 10.0.1–10.3.0 `#[Autowire]` в аргументах методу не працював (виправлено в 10.3.1). На цих версіях використовуйте конструктор.
125
+
:::
126
+
127
+
## RPC атрибути
128
+
129
+
| Атрибут | Де | Призначення |
130
+
| --- | --- | --- |
131
+
| [`#[RPC\Info]`](/docs/api/json-rpc-bundle/add_rpc_service/info) | клас | Псевдонім, роздільник, версія API, видалені методи |
132
+
| [`#[RPC\APIGroups]`](/docs/api/json-rpc-bundle/functionality/groups) | клас, метод | До яких груп API належить метод |
133
+
| [`#[RPC\Assertions]`](/docs/api/json-rpc-bundle/add_rpc_service/assertions) | параметр | Валідація обмеженнями Symfony |
134
+
| [`#[RPC\Param]`](/docs/api/json-rpc-bundle/add_rpc_service/params) | параметр | Явна конвертація значення в об'єкт |
135
+
| [`#[RPC\DTO]`](/docs/api/json-rpc-bundle/add_rpc_service/response) | метод, властивість | Формат DTO для результату чи параметра |
136
+
| [`#[RPC\Cache]`](/docs/api/json-rpc-bundle/add_rpc_service/cache) | метод | Кешування відповіді |
137
+
| [`#[RPC\CacheRelation]`](/docs/api/json-rpc-bundle/add_rpc_service/cache) | метод | Інвалідація пов'язаного кешу |
138
+
| [`#[RPC\Lock]`](/docs/api/json-rpc-bundle/add_rpc_service/lock) | метод | Заборона одночасних викликів |
139
+
| `#[RPC\IgnoreApi]` | метод | Прибрати метод з API |
140
+
141
+
Усі атрибути — з пакета `ufo-tech/rpc-objects` (простір імен `Ufo\RpcObject\RPC`).