Кеширование методов

#[Cacheable] запоминает результат метода: первый вызов выполняет тело, следующие с тем же ключом получают сохранённое значение без похода в базу. Набор атрибутов, их параметры и поведение взяты у Spring Cache.

Что это и зачем

Кеширование метода — сохранение того, что метод вернул, чтобы при следующем вызове с теми же аргументами отдать готовый ответ, а не вычислять его снова.

Проблема. Часть данных читается намного чаще, чем меняется: справочник стран, карточка товара, настройки тарифа. Каждый запрос всё равно идёт за ними в базу, и нагрузка на неё растёт вместе с трафиком, хотя ответ раз за разом один и тот же. Кеш, написанный вручную, — это проверка «есть ли в кеше», запись после вычисления и удаление при изменении, размазанные по всем методам сервиса. Забытое удаление незаметно до тех пор, пока пользователь не увидит старые данные.

Решение. Пометьте метод атрибутом — фреймворк сам проверит кеш, вызовет тело при промахе и сохранит результат. Удаление при изменении объявляется так же, атрибутом на методе, который меняет данные.

Родословная

Где Winter отличается от Spring

Ключ — шаблон, а не выражение. Вместо SpEL — подстановка параметров: '{id}', '{filter.region}:{page}'. Шаблон разбирается один раз при сборке, и опечатка в имени параметра останавливает сборку, а не превращается в ключ, который ни с чем не совпадает. Условий condition и unless нет.

Время жизни задаётся здесь же. В Spring TTL — забота конкретного хранилища; в Winter это параметр ttl у кеша и у атрибута.

Вызов соседнего метода тоже кешируется. В Spring @Cacheable не срабатывает, когда метод вызывается из того же класса через this. В Winter прокси — подкласс вашего сервиса, поэтому вызов через $this идёт через кеш.

Каждое попадание — копия. Хранилище держит сериализованное значение, и каждый вызов получает свой экземпляр. Изменить объект из кеша, а потом увидеть изменения у соседнего запроса нельзя.

Быстрый старт

Три шага: включить, объявить кеш, пометить метод.

use Flytachi\Winter\Kernel\App\Attribute\EnableCaching;
use Flytachi\Winter\Kernel\App\Attribute\EnableWeb;

#[EnableWeb]
#[EnableCaching]
final class Application extends WinterApplication
{
  public static function main(array $argv): never
  {
      parent::run($argv);
  }
}

namespace Main\Config;

use Flytachi\Winter\Kernel\Cache\CacheConfigurer;
use Flytachi\Winter\Kernel\Cache\Caches;

final class CacheConfig implements CacheConfigurer
{
  public function configureCaches(Caches $caches): void
  {
      $caches->table('countries');   // умолчания: 64 записи до 16 КБ, ≈1,6 МБ
  }
}

namespace Main\Service;

use Flytachi\Winter\Kernel\Cache\Attribute\Cacheable;

class CountryService
{
  #[Cacheable('countries', key: '{code}')]
  public function find(string $code): ?Country
  {
      return $this->repository->find($code);   // выполнится один раз на код
  }
}

Сервис внедряется как обычно — контейнер сам отдаст версию с кешем:

#[Inject]
private CountryService $countries;

$this->countries->find('UZ');   // тело выполнено, результат сохранён
$this->countries->find('UZ');   // из кеша, без запроса к базе

Хранилища

Каждый кеш объявляется в CacheConfigurer и живёт в одном из четырёх хранилищ: table и memory — в памяти сервера, file и redis — вне её, поэтому их видят консольные команды и перезапуск им не страшен.

Какое выбрать

Короче: один сервер и данные меняются — table; нужно пережить перезапуск или видеть кеш из консоли — file; экземпляров несколько — redis; данные не меняются или сами устаревают по ttl — memory.

table — общая для всех процессов

Таблица создаётся в мастер-процессе до того, как от него отделяются воркеры, и поэтому общая: значение, вычисленное одним воркером, сразу отдают все остальные, а удаление в одном воркере убирает запись у всех. Её видят и процессы, поднятые рядом с сервером через #[EnableProcess], #[EnableDaemon] и #[EnableScheduler].

Умолчания рассчитаны на самый частый случай — несколько значений: токен, настройки, короткий справочник. Такая таблица занимает ≈1,6 МБ.

Готовые настройки table

// 1. Несколько значений — токен, настройки, короткий список.  ≈1,6 МБ
$caches->table('api-token');

// 2. Справочник поштучно: до тысячи записей по 2 КБ.          ≈3,2 МБ
$caches->table('countries', rows: 1_024, valueSize: 2 * 1024);

// 3. Сущности по id: десять тысяч карточек по 2 КБ.           ≈51 МБ
$caches->table('products', rows: 10_000, valueSize: 2 * 1024, ttl: 300);

Цифры памяти — замер на живом процессе. Не нужно знать, сколько записей будет: важно, сколько их может стать. Таблица заполнится — запись не сохранится, и в логе появится предупреждение.

Что помещается в значение

valueSize ограничивает значение после serialize(). Замеры, чтобы не гадать:

Ориентир: одна запись-сущность занимает около 350 байт, объект и массив той же формы весят почти одинаково. Точное число для своих данных:

echo strlen(serialize($service->all()));   // байт — сравните с valueSize

Сколько памяти займёт таблица

Память резервируется целиком в момент запуска — сколько бы записей потом ни появилось. Swoole округляет число строк вверх до степени двойки и добавляет запас на коллизии, поэтому оценка такая:

степень двойки ≥ rows  ×  1.5  ×  (valueSize + 120) байт

rows: 64,     valueSize: 16384  →     64 × 1.5 × 16504  ≈ 1,6 МБ
rows: 10_000, valueSize: 4096   →  16 384 × 1.5 × 4216   ≈ 99 МБ

Итог виден в баннере при запуске:

   web         http://0.0.0.0:8000
 cache       2 table · 1 memory · ≈53 MB shared

Когда значение не помещается

Значение длиннее valueSize или запись в заполненную таблицу не сохраняются: метод всё равно возвращает правильный результат, просто без кеша. Сам Swoole слишком длинную строку молча обрезает, а обрезанное значение уже не прочитать — поэтому такая запись до таблицы не доходит, а старая запись под тем же ключом удаляется, чтобы не отдавать устаревшее.

Перед отказом таблица один раз удаляет просроченные записи. Если места всё равно нет, в лог пишется предупреждение — не чаще раза в минуту на кеш, со счётчиком пропусков:

[WARN ] Cache 'settings' skipped a write: a value of 21480 bytes does not fit valueSize 16384;
raise valueSize in the CacheConfigurer. The value was returned uncached; 12 write(s) skipped
since the last warning.

Такое сообщение означает, что кеш перестал работать на часть данных и нагрузка на базу вернулась. Поднимите то, что названо в сообщении: valueSize или rows.

memory — своя у каждого воркера

Обычный массив PHP: ничего не резервируется заранее, подходит значение любого размера. Цена — у каждого воркера своя копия, и каждый вычисляет её сам.

Когда записей становится больше maxItems, вытесняется та, которую дольше всех не читали. Это обычная работа такого кеша, и предупреждений она не пишет.

Память растёт по мере записи: каждая запись стоит своего значения и ещё около 370 байт. Тысяча сущностей по ~350 байт — около 0,7 МБ на воркер, пять тысяч — около 3,4 МБ.

Готовые настройки memory

// 1. Справочник, неизменный до деплоя: живёт, пока жив воркер.
$caches->memory('currencies');

// 2. Курсы: сотня пар, каждая живёт минуту.
$caches->memory('rates', maxItems: 100, ttl: 60);

// 3. Остатки: тысячи позиций, полминуты.
$caches->memory('stock', maxItems: 5_000, ttl: 30);

file — на диске

Записи лежат файлами в storage/cache/winter-cache/<имя>/. Их читают все воркеры и процессы, видят команды call, а перезапуск и деплой им не страшны. Запись атомарная — временный файл и переименование, — поэтому половину значения никто не прочтёт.

Чтение — около 17 мкс, запись — около 150 мкс: в десятки раз медленнее table, но в сотни раз быстрее запроса к базе. Просроченные файлы удаляются при чтении и одной чисткой при запуске сервера; каталог очищает и call storage clean.

// Токен, который переживёт перезапуск и виден командам call.
$caches->file('api-token', ttl: 3300);

// Настройки, которые сбрасывает консольная команда.
$caches->file('settings', version: 'v2');

Под FPM, где процесс живёт один запрос, это хранилище по-прежнему кеширует.

redis — общий для всех экземпляров

Единственное хранилище, которое разделяют несколько экземпляров приложения: реплики в Kubernetes, серверы за балансировщиком. Удаление на одном сервере видят все. Нужен пакет winter-redis — без него объявление redis() остановит запуск с подсказкой, что установить.

$caches->redis('products', MainRedisConfig::class, ttl: 300);

Ключи в Redis видны как есть: #[Cacheable('products', key: '{id}')] с версией v2 пишет в cache:products:v2:42. allEntries и call cache clear удаляют только ключи с префиксом этого кеша — остальная база не трогается.

Если хранилище недоступно

Упавший кеш не должен ронять приложение. Если Redis не отвечает или файл нельзя записать:

• чтение считается промахом — метод выполняется и возвращает правильный результат;
• запись пропускается;
• в лог пишется warning — не чаще раза в минуту на кеш, со счётчиком;
• воркер 5 секунд не обращается к хранилищу и работает без кеша, потом пробует снова.

Пауза важна. Недоступный Redis не всегда отвечает отказом мгновенно: попытка может ждать таймаута соединения — с настройками winter-redis по умолчанию около трёх секунд. Без паузы каждый вызов платил бы их дважды, на чтение и на запись, и приложение, которое «не упало», на деле стояло бы.

Атрибуты

#[Cacheable] — вернуть из кеша или вычислить

#[Cacheable('products', key: '{id}', ttl: 300)]
public function find(int $id): ?Product

Если запись есть — тело не выполняется. Если нет — выполняется, и результат сохраняется. Исключение из тела не кешируется: следующий вызов попробует снова.

#[CachePut] — всегда выполнить и обновить

Для методов, которые меняют данные и возвращают новое состояние. Тело выполняется всегда, а результат записывается в кеш — следующее чтение его найдёт.

#[CachePut('products', key: '{result.id}')]
public function save(Product $product): Product

Параметры те же, что у #[Cacheable], кроме sync. В ключе доступен {result} — возвращённое значение. С cacheNull: false результат null удаляет запись, а не оставляет старую.

#[CacheEvict] — удалить

#[CacheEvict('products', key: '{id}')]
#[CacheEvict('product-lists', allEntries: true)]
public function delete(int $id): void

Атрибут повторяемый: один метод может чистить несколько кешей. Он сочетается с #[Cacheable] или #[CachePut] на том же методе.

По умолчанию запись удаляется после того, как тело завершилось успешно. Если тело бросило исключение, изменение не состоялось, и запись остаётся — она по-прежнему верна. С beforeInvocation: true запись удаляется до вызова, что бы ни случилось дальше.

#[CacheConfig] — значения по умолчанию для класса

#[CacheConfig('products', ttl: 300)]
class ProductService
{
  #[Cacheable(key: '{id}')]                 // кеш products, 300 секунд
  public function find(int $id): ?Product

  #[Cacheable(key: 'all', ttl: 60)]         // кеш products, 60 секунд
  public function all(): array
}

Значение на методе всегда важнее значения на классе.

Ключи

Ключ определяет, какая запись относится к вызову. Это шаблон над именами параметров метода:

В ключ годятся строки, числа, bool, null, перечисления (enum), массивы и объекты с __toString(). Объект целиком в ключ не попадает — укажите его свойство: '{order.id}'.

Без key ключ строится из всех аргументов по порядку. У метода без параметров ключ постоянный — одна запись.

Время жизни

ttl — в секундах. Значение берётся с первого уровня, где оно задано:

1. параметр атрибута на методе;
2. #[CacheConfig] на классе;
3. ttl кеша в CacheConfigurer;
4. нигде — запись живёт, пока её не удалят или не перезапустят приложение.

ttl: 0 означает «бессрочно» и перекрывает уровень выше — так один метод в классе с #[CacheConfig(ttl: 60)] можно сделать бессрочным. Просроченная запись считается промахом при чтении: метод выполняется заново, результат перезаписывает её.

null тоже кешируется

По умолчанию, как в Spring, null сохраняется так же, как любое значение: «такой записи нет» — тоже ответ, и база не должна получать один и тот же пустой запрос на каждый вызов.

Следствие: если запись появилась позже, кеш продолжит отдавать null, пока его не удалят. Метод создания должен сообщить об этом кешу:

#[Cacheable('users', key: '{email}')]
public function findByEmail(string $email): ?User

#[CacheEvict('users', key: '{user.email}')]
public function register(User $user): User

Если это неудобно, отключите сохранение пустого результата: cacheNull: false.

sync — одно вычисление на промах

Когда запись истекает под нагрузкой, десятки запросов разом получают промах и одновременно идут в базу за одним и тем же. С sync: true первый запрос вычисляет значение, остальные ждут его и получают готовый результат.

#[Cacheable('reports', key: 'daily', ttl: 600, sync: true)]
public function dailyReport(): Report

Проверки при сборке

Всё, что можно проверить по объявлению, проверяется при call di build и при старте приложения — а не на первом вызове в проде:

Опечатка в имени кеша у #[CacheEvict] особенно опасна: такой метод просто ничего не удалял бы, и пользователи видели бы старые данные. Поэтому имя проверяется до запуска.

Требования к классу и методу

Те же, что у #[Async], потому что работает тот же механизм — сгенерированный подкласс:

• класс не final, метод не final, не static и не private;
• сервис получен из контейнера, а не создан через new — иначе прокси не применяется, и call di build предупредит об этом;
• #[Cacheable] и #[CachePut] — на методе, который возвращает сохраняемое значение: не void, never, Generator, Closure, callable или iterable;
• значение должно проходить через serialize(): замыкание внутри объекта не сохранится, метод вернёт его без кеша и предупредит в логе.

Один класс может сочетать методы #[Async] и методы с кешем — у него будет один общий прокси. На одном методе их совместить нельзя.

Чего кеш не видит

• Консольные команды — table и memory. call … — отдельный процесс со своей памятью: команда, которая меняет данные, такой кеш сервера не очистит. Если это нужно, берите file или redis — до них дойдут и #[CacheEvict] в команде, и call cache clear.
• Другие экземпляры приложения — всё, кроме redis. Каждый контейнер держит свою таблицу и свой каталог; изменение в одном не удалит запись в другом.
• FPM — table и memory. Процесс живёт один запрос, и такой кеш вместе с ним.

Деплой и старые данные

table и memory после перезапуска пустые. file и redis переживают деплой — а с ним и записи, сохранённые старым кодом. Если класс значения изменился, например появилось новое типизированное свойство, объект из такой записи восстановится неполным.

Против этого три меры:

• запись, которая не восстанавливается, — исчезнувший класс, испорченные байты — считается промахом: удаляется и вычисляется заново;
• version у кеша — сменили, и старые записи просто не находятся: в redis они истекут сами, в file их уберёт чистка;
• call cache clear — очистить кеш явно, например в скрипте деплоя.

php call cache clear --all   # все file и redis кеши
php call run

Примеры

Токен внешнего API на час

Самый частый случай. Сервис авторизации выдаёт токен на час, и запрашивать его на каждый вызов — лишняя задержка и риск упереться в лимит выдачи.

use Flytachi\Winter\Kernel\Cache\Attribute\CacheEvict;
use Flytachi\Winter\Kernel\Cache\Attribute\Cacheable;

class PaymentGateway
{
  #[Cacheable('api-token', key: 'payment', ttl: 3300, sync: true, cacheNull: false)]
  public function token(): string
  {
      $response = $this->http->post('https://auth.example.com/oauth/token', [
          'client_id'     => $this->clientId,
          'client_secret' => $this->clientSecret,
          'grant_type'    => 'client_credentials',
      ]);

      return $response['access_token'];
  }

  #[CacheEvict('api-token', key: 'payment')]
  public function forgetToken(): void
  {
  }

  public function charge(Order $order): array
  {
      $response = $this->send($order, $this->token());

      // Токен отозвали раньше срока: забыть, получить новый, повторить один раз.
      if ($response['status'] === 401) {
          $this->forgetToken();
          $response = $this->send($order, $this->token());
      }

      return $response;
  }
}

$caches->table('api-token');   // умолчания: ≈1,6 МБ, хватит на десятки токенов

Что здесь важно:

• ttl: 3300 — 55 минут при часовом токене. Запас нужен, чтобы кеш не отдал токен, которому осталась секунда: запрос с ним уйдёт и вернётся с 401.
• sync: true — когда токен истёк, десятки одновременных запросов не пойдут за новым разом: один получит, остальные подождут его.
• cacheNull: false — если сервис авторизации вернул пустой ответ, это не запомнится на 55 минут. Исключение не кешируется в любом случае.
• key: 'payment' — один кеш api-token может хранить токены нескольких сервисов под разными ключами.
• $this->token() внутри charge() идёт через кеш: прокси — подкласс сервиса, поэтому вызов собственного метода тоже кешируется.
• table, а не memory: токен один на все воркеры и процессы, а forgetToken() сбрасывает его у всех сразу. Должен пережить перезапуск — file('api-token'); экземпляров несколько — redis('api-token', …). Атрибуты при этом не меняются.

Константы из базы

Настройки, тарифы, тексты — читаются на каждом запросе, меняются раз в неделю.

#[CacheConfig('settings')]
class SettingsService
{
  #[Cacheable(key: 'all')]
  public function all(): array
  {
      return $this->repository->pairs();   // ['name' => 'value', ...]
  }

  public function get(string $name, ?string $default = null): ?string
  {
      return $this->all()[$name] ?? $default;   // из кеша
  }

  #[CacheEvict(key: 'all')]
  public function set(string $name, string $value): void
  {
      $this->repository->save($name, $value);
  }
}

$caches->table('settings');   // до 16 КБ настроек — сотни пар

Все настройки — одно значение под ключом 'all': один запрос к базе на всех, а set() сбрасывает его сразу во всех воркерах. ttl не нужен — запись живёт, пока её не изменят. Если настройки меняют в обход сервиса (руками в базе), добавьте ttl, например 600: тогда изменение подхватится не позже чем через десять минут.

Справочник

Данные почти не меняются, ключ — код, удалять нечего.

#[CacheConfig('currencies')]
class CurrencyService
{
  #[Cacheable(key: '{code}')]
  public function find(string $code): ?Currency
  {
      return $this->repository->find($code);
  }

  #[Cacheable(key: 'all')]
  public function all(): array
  {
      return $this->repository->findAll();
  }
}

$caches->memory('currencies');   // меняется только с деплоем — memory достаточно

Сущность: чтение, изменение, удаление

#[CacheConfig('products', ttl: 300)]
class ProductService
{
  #[Cacheable(key: '{id}')]
  public function find(int $id): ?Product
  {
      return $this->repository->find($id);
  }

  // Новое состояние сразу кладётся в кеш, списки сбрасываются.
  #[CachePut(key: '{result.id}')]
  #[CacheEvict('product-lists', allEntries: true)]
  public function save(Product $product): Product
  {
      return $this->repository->save($product);
  }

  #[CacheEvict(key: '{id}')]
  #[CacheEvict('product-lists', allEntries: true)]
  public function delete(int $id): void
  {
      $this->repository->delete($id);
  }

  #[Cacheable('product-lists', key: '{category}:{page}', ttl: 60)]
  public function byCategory(string $category, int $page = 1): array
  {
      return $this->repository->byCategory($category, $page);
  }
}

$caches
  ->table('products', rows: 10_000, valueSize: 2 * 1024)         // ≈51 МБ
  ->table('product-lists', rows: 512, valueSize: 16 * 1024);     // страница до 45 карточек, ≈12 МБ

Остатки — часто меняются, быстро устаревают

Значение живёт полминуты, а общая память не нужна: каждый воркер держит свою копию.

#[Cacheable('stock', key: '{sku}', ttl: 30)]
public function available(string $sku): int

// CacheConfig:
$caches->memory('stock', maxItems: 5_000);

Дальше

• Асинхронные вызовы — тот же механизм прокси для #[Async]
• Команда cache — посмотреть и очистить кеши file и redis
• Команда di — сборка прокси и проверка имён кешей
• Внедрение зависимостей — почему сервис нужно внедрять, а не создавать
• Настройка веб-слоя — SERVER_WORKERS и перезапуск воркеров