docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/json-rpc-bundle/add_rpc_service/cache.md
+62
−1
65
65
66
66
Проте, інколи, для певних методів, результат яких змінюється не часто, є сенс ввімкнути кешування відповіді задля підвищення швидкості обробки запитів, для збереження лімітів, зниження навантаження на частини системи, тощо.
67
67
68
−
RPC Server використовує саме ту реалізацію CacheInterface від Symfony, яка використовується в вашому в проєкті. Таким чином, немає потреби в додатковому налаштуванні.
68
+
Відповіді зберігаються в окремому пулі кешу бандла (`rpc.cache.pool`, файловий у `%kernel.cache_dir%`). Його можна замінити будь-яким пулом застосунку, наприклад спільним Redis, через `cache.pool` у [налаштуваннях](/docs/api/json-rpc-bundle/config).
69
69
70
70
Ввімкнути кешування максимально просто, єдине що вам потрібно зробити це до певного методу додати атрибут `#[RPC\Cache]`.
71
71
83
83
84
84
Це налаштування дозволить кешувати відповідь впродовж однієї хвилини, кожен наступний запит на цей метод з тими самими параметрами буде отримувати відповідь миттєво з кеша.
85
85
86
+
Ключ кешу складається з реалізації методу (`Class::method`), версії API та відсортованих параметрів запиту, тож порядок ключів у вкладених об'єктах на ключ не впливає. Методи без `#[RPC\Cache]` до кешу взагалі не звертаються.
87
+
86
88
Скинути кеш можна як і завжди, виконавши Symfony команду
87
89
88
90
```bash
129
131
#[RPC\Cache(lifetimeSecond: RPC\Cache::T_DAY, environments: ['dev', 'prod'])]
130
132
public function methodThatWorksForALongTime(): void {}
131
133
}
134
+
```
135
+
136
+
## Обійти кеш для одного запиту
137
+
138
+
Спеціальний параметр `$rpc.ignoreCache` змушує обчислити відповідь заново й перезаписати її в кеші:
139
+
140
+
```json
141
+
{"jsonrpc": "2.0", "id": 1, "method": "SomeApiMethod.methodThatWorksForALongTime", "params": {"$rpc": {"ignoreCache": true}}}
142
+
```
143
+
144
+
## `#[RPC\CacheRelation]`
145
+
146
+
Метод, що змінює дані, може скидати закешовані відповіді пов'язаних методів і, за потреби, одразу прогрівати їх знову.
147
+
148
+
```php
149
+
public function __construct(
150
+
public ?string $serviceFQCN = null, // клас пов'язаних методів; за замовчуванням — поточний
151
+
public array $methods = [], // назви пов'язаних методів
152
+
public bool $warmUp = false, // одразу виконати їх знову, щоб наповнити кеш
153
+
)
154
+
```
155
+
156
+
```php
157
+
use Ufo\RpcObject\RPC;
158
+
159
+
#[RPC\Info('User')]
160
+
final class UserProcedure implements IRpcService
161
+
{
162
+
#[RPC\Cache(lifetimeSecond: RPC\Cache::T_HOUR)]
163
+
public function get(int $id): UserDto { /* ... */ }
164
+
165
+
#[RPC\CacheRelation(methods: ['get'], warmUp: true)]
166
+
public function rename(int $id, string $name): bool { /* ... */ }
167
+
}
168
+
```
169
+
170
+
Після успішного `User.rename {"id": 5, ...}` закешований `User.get {"id": 5}` видаляється і будується заново. Ключ пов'язаного запиту складається з тих параметрів поточного запиту, чиї назви збігаються з параметрами пов'язаного методу. Атрибут можна вказувати кілька разів.
171
+
172
+
Інвалідація виконується на події `rpc.post_response`, тобто після відправлення відповіді клієнту. Для відповіді з помилкою вона не запускається.
173
+
174
+
:::tip
175
+
На кількох серверах налаштуйте спільний `cache.pool` — інакше інвалідація спрацює лише на сервері, що обробив запит.
176
+
:::
177
+
178
+
## Керування кешем з коду
179
+
180
+
`Ufo\JsonRpcBundle\Server\RpcCache\RpcCacheService` дає ті самі можливості програмно:
181
+
182
+
| Метод | Що робить |
183
+
| --- | --- |
184
+
| `deleteRelationCache(string $class, array $methods, array $params)` | Видаляє кешовані відповіді вказаних методів |
185
+
| `warmCache(string $class, array $methods, array $params, bool $deleteCache = true)` | Видаляє й одразу заново будує кеш |
186
+
| `deleteRequestCache(RpcRequest $request)` | Видаляє відповідь одного запиту |
187
+
188
+
```php
189
+
public function __construct(private RpcCacheService $rpcCache) {}
190
+
191
+
// після оновлення сутності поза RPC
192
+
$this->rpcCache->deleteRelationCache(UserProcedure::class, ['get'], ['id' => $id]);
132
193
```