Jak cache'ować REST API w Magento 2 z Varnishem?

Dlaczego architektura headless zarzyna REST API Magento 2?

Odpalasz nowoczesny frontend — Next.js, Nuxt, Astro albo dedykowane PWA. Wygląda świetnie, w testach lokalnych śmiga błyskawicznie, ale po wdrożeniu na produkcję serwer zaczyna płonąć przy pierwszym większym skoku ruchu. Dlaczego? Bo front headless zasypuje backend tysiącami asynchronicznych zapytań HTTP do endpointów /rest/V1/*. W klasycznym, monolitycznym Magento 2 zapytania o stronę kategorii czy karty produktu trafiają w Full Page Cache (FPC), który przy odpowiedniej konfiguracji z serwerem Varnish serwuje gotowy HTML w kilkanaście milisekund, nie dotykając nawet interpretera PHP.

Gdy przechodzisz na architekturę headless, ta ochrona całkowicie znika. Domyślny mechanizm FPC w Magento 2 po prostu nie obejmuje zapytań REST API. Każde pojedyncze pobranie listy produktów, menu nawigacji, szczegółów wariantu czy konfiguracji sklepu przelatuje bezpośrednio przez cały stos frameworka: inicjalizację aplikacji, wstrzykiwanie zależności (ObjectManager), routing, autoryzację tokenów, aż po dziesiątki zapytań SQL do bazy danych. W efekcie czas odpowiedzi rośnie z 20 ms do 600–1200 ms, a serwer zamiast obsługiwać zamówienia, marnuje 95% zasobów CPU na generowanie w kółko tych samych struktur JSON.

Rozwiązaniem tego wąskiego gardła jest nasz darmowy moduł API Enhancer, który rozszerza działanie Varnisha o pełne wsparcie dla REST API, zachowując przy tym precyzyjną kontrolę nad spójnością danych.

Jak działa moduł API Enhancer i dlaczego Varnish potrzebuje nagłówków?

Varnish to niesamowicie szybki demon buforujący w pamięci RAM, ale sam z siebie nie wie, co znajduje się wewnątrz zwracanego payloadu JSON. Jeśli po prostu włączysz cache dla ścieżki /rest/* w pliku konfiguracyjnym VCL, błyskawicznie zaserwujesz jednemu klientowi koszyk innego użytkownika albo zamrozisz nieaktualne stany magazynowe na wieki.

Aby bezpiecznie cache'ować REST API, proxy buforujące musi otrzymać z Magento dwie kluczowe informacje:

• Instrukcję cache'owania (Cache-Control): czy dana odpowiedź jest publiczna, prywatna i jaki jest jej maksymalny czas życia (TTL).
• Tagi tożsamości (X-Magento-Tags): listę identyfikatorów encji (produktów, kategorii, stron CMS), które brały udział w wygenerowaniu odpowiedzi.
• Kontekst klienta (Customer Context): rozróżnienie odpowiedzi w zależności od grupy klienta, waluty czy wybranego widoku sklepu (store view), bez ujawniania danych personalnych.

W API Enhancer odpowiedź na zapytanie GET o dane produktu zostaje automatycznie oznaczona tagami, np. cat_p_482 oraz cat_c_15. Varnish zapisuje obiekt JSON w pamięci wraz z tymi metadanymi. Kiedy kolejne zapytanie o ten sam zasób trafia do serwera, Varnish zwraca odpowiedź w 2–5 ms bez kontaktu z PHP. Co kluczowe — moduł automatycznie pomija mutacje (POST, PUT, DELETE) oraz zapytania zawierające wrażliwe dane sesyjne, zabezpieczając sklep przed wyciekiem danych.

Czym różni się punktowe unieważnianie cache od czyszczenia wszystkiego?

Najprostszym i jednocześnie najbardziej destrukcyjnym sposobem radzenia sobie z nieaktualnym cache'em jest wykonanie pełnego czyszczenia (tzw. flush). Niestety, w sklepach o dużym natężeniu ruchu i bogatym katalogu, czyszczenie całego cache'u po zmianie ceny pojedynczego produktu to technologiczne samobójstwo.

Zjawisko cache stampede (inaczej: dog-piling) następuje w momencie, gdy zbuforowane odpowiedzi dla tysięcy produktów wygasają jednocześnie. Setki równoległych wątków z frontendu headless uderzają w nieogrzany backend, doprowadzając do natychmiastowego przeciążenia bazy danych i timeoutów HTTP 504.

Punktowe unieważnianie (targeted cache invalidation) rozwiązuje ten problem u podstaw. Gdy menedżer sklepu edytuje produkt o ID 482 w panelu administracyjnym, Magento wysyła do Varnisha komendę PURGE/BAN wyłącznie dla taga cat_p_482. Varnish usuwa z pamięci podręcznej tylko te wpisy JSON, w których ten konkretny produkt występował (kartę produktu, widok kategorii, w której się znajduje, oraz boksy promocyjne). Pozostałe 99,9% zbuforowanych endpointów pozostaje nienaruszone. Baza danych nie odczuwa żadnego skoku obciążenia, a klienci natychmiast widzą zaktualizowaną cenę lub dostępność.

Dlaczego oryginalny moduł trafił na cmentarz i jak go wskrzeszyliśmy?

Jako zespół SISL od lat realizujemy wdrożenia headless i PWA na Magento 2 / Adobe Commerce. Wiemy, że ekosystem open source bywa bezlitosny dla starszych rozszerzeń. Pierwowzorem naszego rozwiązania był ceniony w społeczności moduł msp/apienhancer autorstwa agencji MageSpecialist. Projekt był genialny w swoich założeniach, jednak został całkowicie porzucony w okolicach 2018 roku.

Jego reguły w composer.json zatrzymały się na sztywnym wymogu php: ^7.0|^7.1. W erze nowoczesnego e-commerce — gdzie standardem produkcyjnym stało się PHP 8.2, 8.3, a nadchodzące wydania Adobe Commerce 2.4.8 oraz 2.4.9 wprowadzają pełną zgodność z PHP 8.4 — oryginalny kod był kompletnie nieużywalny. Nowe wersje interpretera odrzucały przestarzałą składnię typowania, a zmiany w mechanizmach wstrzykiwania zależności w Magento uniemożliwiały kompilację.

Zamiast tworzyć koło na nowo, wzięliśmy odpowiedzialność za ten fundament. Przygotowaliśmy i aktywnie utrzymujemy nowoczesny fork: zaktualizowaliśmy sygnatury metod, usunęliśmy przestarzałe konstrukcje, dostosowaliśmy deklaracje typów pod PHP 8.4 i zweryfikowaliśmy pełne przejście procesu setup:di:compile oraz poprawną instancjację klas w najnowszych wersjach platformy. Kod źródłowy jest w pełni otwarty i dostępny w naszym repozytorium GitHub: SISL-source/magento2-api-enhancer.

Jak zainstalować i skonfigurować API Enhancer w Magento 2?

Instalacja modułu odbywa się w standardowy dla Composera sposób poprzez wskazanie naszych publicznych repozytoriów kodu źródłowego. Ponieważ rozszerzenie bazuje na wspólnej bibliotece narzędziowej, wymagane jest zdefiniowanie obu pakietów VCS w pliku composer.json Twojego projektu.

Wykonaj w terminalu w głównym katalogu instalacji Magento następujące polecenia:

composer config repositories.sisl-msp-common vcs https://github.com/SISL-source/magento2-msp-common
composer config repositories.sisl-apienhancer vcs https://github.com/SISL-source/magento2-api-enhancer
composer require msp/apienhancer:dev-main
bin/magento module:enable MSP_Common MSP_APIEnhancer && bin/magento setup:upgrade

Po pomyślnej instalacji i kompilacji kontenera DI, przejdź do panelu administracyjnego w ścieżkę Stores > Configuration > Services > MSP API Enhancer. W tym miejscu możesz:

1. Włączyć buforowanie wybranych publicznych zasobów REST API.
2. Skonfigurować domyślny czas życia obiektów (TTL) dla poszczególnych endpointów.
3. Zweryfikować poprawność wysyłanych nagłówków X-Magento-Tags w narzędziach deweloperskich przeglądarki (np. w zakładce Network po wywołaniu zapytania GET do katalogu).

Pamiętaj, że do pełnego działania w środowisku produkcyjnym niezbędny jest działający serwer Varnish skonfigurowany jako reverse proxy przed instancją Magento, obsługujący standardowe reguły PURGE/BAN.

Kiedy buforowanie REST API to absolutny obowiązek?

Jeżeli Twój sklep działa na klasycznym szablonie Luma lub Hyvä i nie korzysta intensywnie z mikroserwisów, wbudowany Full Page Cache zazwyczaj wystarcza. Sytuacja zmienia się diametralnie, gdy wchodzisz w świat aplikacji jednostronicowych (SPA), frameworków mobilnych czy architektury Composable Commerce.

Wdrożenie cache'owania REST API z tagami to krok konieczny, jeśli:

• Planujesz lub prowadzisz wdrożenie headless e-commerce i obserwujesz nieproporcjonalnie wysokie zużycie zasobów bazy danych.
• Średni czas odpowiedzi Twojego API przekracza 200 ms dla zapytań katalogowych.
• Prowadzisz kampanie marketingowe generujące nagłe piki ruchu na konkretnych landing page'ach pobierających dane przez REST.
• Chcesz obniżyć koszty infrastruktury chmurowej (AWS, GCP, bare-metal), redukując liczbę instancji web nodów PHP.

W SISL projektujemy i optymalizujemy architekturę wysokowydajnych sklepów internetowych na co dzień. Jeśli potrzebujesz audytu wydajności, wsparcia w konfiguracji Varnisha lub planujesz bezkompromisowe wdrożenie headless/PWA w oparciu o Adobe Commerce — napisz do nas. Przeanalizujemy Twój stos technologiczny i wyeliminujemy wąskie gardła, zanim odczują je Twoi klienci.