System kolejek w Drupal to potężny, a jednocześnie często niedoceniany mechanizm, który pozwala rozwiązywać problemy z wydajnością, skalowalnością oraz integracją z usługami zewnętrznymi. Dzięki Queue API można rozłożyć ciężkie operacje w czasie, wykonywać je asynchronicznie i chronić serwis przed przeciążeniem. Znajomość kolejek jest kluczowa, jeśli projektujesz rozbudowane serwisy, integracje lub obsługujesz duże ilości danych.
Podstawy działania Queue API w Drupal
Czym jest kolejka w kontekście Drupal
Kolejka to struktura, w której zadania (tzw. itemy) są odkładane do późniejszego przetworzenia. Zamiast wykonywać ciężką operację w trakcie pojedynczego żądania HTTP, możemy dodać zadanie do kolejki, a przetwarzanie odroczyć. W Drupal rolę pośrednika pełni Queue API, dostarczające zunifikowany interfejs do tworzenia i przetwarzania kolejek.
Kluczowe elementy to:
- item: pojedyncze zadanie, np. zapis rekordu, wysłanie e-maila, wygenerowanie pliku;
- worker: klasa odpowiedzialna za wykonanie logiki przetwarzania itemu;
- backend: mechanizm przechowywania zadań (np. tabela w bazie danych);
- claim: oznaczenie, że dany item został pobrany przez proces przetwarzający i jest w toku;
- release lub usunięcie: zwolnienie elementu po przetworzeniu lub jego wycofanie z kolejki.
Rodzaje kolejek dostępnych w Drupal
Drupal udostępnia kilka trybów kolejek, które rozwiązują odmienne problemy architektoniczne. Najważniejsze z nich to:
- QueueFactory: podstawowy mechanizm tworzenia kolejek, używany do przetwarzania zadań asynchronicznych, wywoływany z kodu PHP;
- Cron queue: kolejka powiązana z mechanizmem cron, która jest przetwarzana przy każdym wywołaniu CRON przez system;
- Reliable queue: tryb, w którym zadania są traktowane bardziej niezawodnie (np. item nie znika, dopóki nie zostanie wyraźnie usunięty po sukcesie);
- kolejki oparte o alternatywne backendy, np. Redis czy RabbitMQ, dostępne dzięki modułom zewnętrznym.
W typowej instalacji Drupal wykorzystuje backend oparty o bazę danych, co wystarcza dla średnich serwisów. Przy dużej skali lub bardzo intensywnym ruchu warto rozważyć bardziej zaawansowane backendy.
Zalety stosowania kolejek
Wprowadzenie kolejek do architektury serwisu przynosi szereg korzyści:
- odciążenie żądań użytkownika: ciężkie operacje nie blokują ładowania strony;
- skalowalność: można uruchamiać wiele procesów pracujących na tej samej kolejce;
- odporność na błędy zewnętrznych systemów: nieudane zadania można ponowić;
- kontrola nad tempem przetwarzania: liczba itemów przetwarzanych w jednym cyklu cron może być ograniczana;
- modułowość: kolejkowanie logiki pozwala budować luźno powiązane komponenty systemu.
Kiedy warto sięgnąć po Queue API
Mechanizm kolejek ma sens wszędzie tam, gdzie przetwarzanie jest kosztowne lub wrażliwe na opóźnienia. Typowe scenariusze to:
- integracje z zewnętrznymi API, gdzie czas odpowiedzi bywa niestabilny;
- masowy import danych z plików CSV, XML, JSON;
- generowanie miniatur, raportów, plików PDF, dużych zestawień;
- wysyłka dużej liczby e-maili transakcyjnych lub powiadomień;
- aktualizacja indeksów wyszukiwarki, np. Solr lub Elasticsearch;
- czyszczenie, archiwizacja i inne zadania porządkowe w tle.
Zastosowanie Queue API to inwestycja w stabilność projektu i komfort użytkownika, który nie musi czekać na zakończenie ciężkich procesów w trakcie zwykłej wizyty na stronie.
Tworzenie i rejestrowanie kolejek w module
Definiowanie kolejek w pliku services.yml
W Drupal 8+ kolejki są obsługiwane głównie przez system usług. Najczęściej definiuje się je pośrednio, przez konfigurację workera w pliku modul.services.yml. Przykładowa definicja wygląda następująco (w uproszczonej formie, bez cudzysłowów na początku i końcu):
queue_worker.example_import:
class: Drupal\example\Plugin\QueueWorker\ExampleImportQueue
tags:
- { name: queue_worker, title: Example import, cron: 60 }
Kluczowe pola w tagu queue_worker:
- name: informuje Drupal, że to definicja workera kolejki;
- title: etykieta pojawiająca się np. w panelu administracyjnym;
- cron: liczba sekund, jaką Drupal powinien przeznaczyć na przetwarzanie tej kolejki w jednym przebiegu cron.
Po zarejestrowaniu usługi system automatycznie rozpozna worker jako obsługujący daną kolejkę. Nazwa serwisu jest zwykle jednocześnie identyfikatorem kolejki używanym w kodzie.
Adnotacja @QueueWorker i plugin
Klasa workera jest pluginem z adnotacją @QueueWorker. Przykład deklaracji:
/**
* @QueueWorker(
* id = example_import,
* title = Example import,
* cron = 60
* )
*/
class ExampleImportQueue extends QueueWorkerBase {
public function processItem($data) {
// Logika przetwarzania itemu
}
}
Istotne jest zrozumienie, że:
- id: identyfikator kolejki, wykorzystywany przy dodawaniu elementów;
- processItem: metoda, która będzie wywoływana dla każdego elementu kolejki;
- parametr cron: określa, ile czasu cron może spędzić na tej kolejce.
Dodawanie elementów do kolejki
Dodawanie zadań odbywa się zazwyczaj w serwisach lub kontrolerach. Najczęściej używa się do tego serwisu queue lub queue_factory. Przykład:
$queue = \Drupal:queue(example_import);
$queue->createItem([
uid => 123,
file => public://import.csv,
]);
Przekazywany do createItem parametr może być tablicą, obiektem lub inną strukturą serializowalną. Im prostsze dane przechowujesz, tym łatwiej utrzymać kompatybilność przy zmianach kodu.
Warto zadbać, aby dane w itemie były minimalne: jeśli możesz, zapisuj w nim tylko identyfikatory i odtwarzaj pełne obiekty w trakcie przetwarzania. Zmniejsza to ryzyko błędów po aktualizacji schematów encji.
Ręczne wywoływanie i testowanie kolejki
Oprócz crona, kolejkę można uruchamiać ręcznie, np. do testów lub w procesach CLI. Moduły takie jak Devel lub Drush udostępniają komendy pozwalające na szybkie sprawdzenie działania:
- uruchamianie crona, który pośrednio przetworzy kolejki;
- bezpośrednie wywołanie pojedynczej kolejki (jeśli moduł udostępnia taką komendę);
- pisanie własnych skryptów CLI, które pobierają itemy z kolejki i wywołują processItem.
W środowisku developerskim warto logować szczegóły przetwarzania do watchdoga, aby szybko diagnozować ewentualne błędy.
Implementacja QueueWorker i logika przetwarzania
Struktura klasy QueueWorkerBase
Typowa implementacja workera dziedziczy po klasie QueueWorkerBase. Podstawowy szkielet wygląda następująco:
namespace Drupal\example\Plugin\QueueWorker;
use Drupal\Core\Queue\QueueWorkerBase;
/**
* @QueueWorker(
* id = example_import,
* title = Example import,
* cron = 60
* )
*/
class ExampleImportQueue extends QueueWorkerBase {
public function processItem($data) {
// Implementacja
}
}
Metoda processItem przyjmuje jeden argument: dane itemu, jakie zostały umieszczone w kolejce. Wewnątrz tej metody powinna znaleźć się cała logika przetwarzania: pobieranie encji, wywołania API, zapis do bazy, generowanie plików itp.
Obsługa błędów i ponawianie zadań
Przy projektowaniu workerów kluczowe jest odpowiednie traktowanie błędów. Możliwe scenariusze:
- błąd krytyczny, którego nie można naprawić (np. usunięte dane wejściowe): item można uznać za porażkę i usunąć z kolejki, ewentualnie zlogować szczegóły;
- błąd tymczasowy, np. niedostępne API: warto rozważyć ponowne dodanie itemu do kolejki lub jego zwolnienie, jeśli używany backend to wspiera;
- błąd częściowy, np. część danych zostało przetworzonych: można zaktualizować stan i pozostawić kolejne zadanie w kolejce.
W prostych implementacjach wystarczy rzucić wyjątek i pozwolić, aby system zalogował błąd, jednak przy dużej skali zaleca się:
- dodawanie liczników prób w strukturze danych itemu;
- rezygnację z ponowień po przekroczeniu maksymalnej liczby prób;
- logowanie błędów wraz z kontekstem (identyfikatory, parametry żądania).
Wydajność, limity czasu i pamięci
Przetwarzanie kolejek często odbywa się w tle, ale wciąż podlega ograniczeniom serwera: limitowi czasu wykonania, pamięci oraz liczbie jednoczesnych procesów. Warto:
- projektować małe zadania: zamiast jednego ogromnego importu stworzyć wiele drobniejszych itemów;
- unikać przechowywania w pamięci dużych kolekcji: przetwarzać dane strumieniowo, jeśli to możliwe;
- czyścić zbędne zmienne i bufory, aby nie doprowadzić do przekroczenia limitu pamięci;
- ustawić rozsądne wartości parametru cron w adnotacji @QueueWorker, tak aby nie blokować całego procesu cron zbyt długo.
W projektach o dużym ruchu warto również rozważyć uruchamianie niezależnych procesów CLI, które przetwarzają kolejki równolegle do crona, odciążając standardowy mechanizm Drupal.
Idempotencja i bezpieczeństwo przetwarzania
Idempotencja oznacza, że wielokrotne wykonanie tego samego zadania prowadzi do tego samego efektu końcowego. W kontekście kolejek w Drupal jest to niezwykle ważne, ponieważ:
- itemy mogą zostać przetworzone ponownie przy błędach lub restartach procesów;
- może dojść do kolizji, gdy kilka procesów pracuje na tej samej kolejce;
- czasem celowo ponawiamy zadania, aby obsłużyć tymczasowe błędy.
Aby osiągnąć idempotencję, można:
- opierać się na unikalnych kluczach w bazie danych (INSERT ... ON DUPLICATE KEY UPDATE);
- sprawdzać aktualny stan encji przed wprowadzeniem zmian;
- stosować znaczniki wersji (revision id) i odrzucać operacje na przestarzałych danych.
Integracja z cron, narzędziami CLI i zewnętrznymi backendami
Przetwarzanie kolejek przez Drupal cron
Standardowym sposobem przetwarzania kolejek jest cron. Przy każdym przebiegu system:
- odnajduje wszystkie zarejestrowane pluginy QueueWorker;
- sprawdza ich konfigurację (m.in. parametr cron w adnotacji);
- przetwarza określoną liczbę itemów lub do wyczerpania przydzielonego czasu.
Administrator może zarządzać harmonogramem wywoływania cron z poziomu panelu administracyjnego lub za pomocą crontaba systemowego. Zbyt rzadkie wywołania mogą powodować zatory w kolejkach, zbyt częste: niepotrzebne zużycie zasobów.
Drush i dedykowane procesy robocze
W środowiskach produkcyjnych często stosuje się dodatkowe procesy pracujące poza standardowym cron, aby uzyskać lepszą kontrolę i wydajność. Drush oraz inne narzędzia CLI umożliwiają:
- ręczne uruchamianie przetwarzania kolejek;
- monitorowanie długości kolejki i statystyk przetwarzania;
- tworzenie własnych komend, np. dla konkretnej kolejki.
Dedykowane procesy robocze mogą działać w trybie demonów: w pętli pobierać elementy z kolejki i je przetwarzać. W takim scenariuszu kolejka staje się pełnoprawnym systemem asynchronicznym, w którym Drupal jest jedynie jednym z klientów.
Alternatywne backendy: Redis, RabbitMQ, inne
Domyślny backend oparty o bazę danych jest prosty i wygodny, ale ma swoje ograniczenia: przy bardzo dużej liczbie zadań rosną obciążenie bazy oraz ryzyko blokad. Dlatego w bardziej zaawansowanych projektach stosuje się:
- Redis: szybki magazyn w pamięci, świetny do kolejek wysokiej przepustowości;
- RabbitMQ: rozbudowany broker komunikatów, pozwalający na skomplikowane scenariusze routingu i potwierdzeń;
- inne systemy kolejkowe, dostępne przez moduły społeczności.
Integracja polega najczęściej na zainstalowaniu odpowiedniego modułu i konfiguracji kontenera usług, tak aby serwis queue_factory zwracał instancje kolejek oparte na nowym backendzie. Pozwala to zachować ten sam interfejs programistyczny, a jednocześnie wykorzystać możliwości dedykowanych systemów kolejkowych.
Monitorowanie, diagnostyka i utrzymanie kolejek
Aby kolejki pozostały stabilne w długim okresie, konieczne jest ich monitorowanie. Dobre praktyki obejmują:
- logowanie liczby przetworzonych itemów oraz czasu wykonania processItem;
- sprawdzanie długości kolejki i reagowanie na narastające zatory;
- definiowanie alertów, gdy kolejka przekracza ustalone progi;
- regularne czyszczenie starych lub porzuconych zadań.
Przydatne jest również tworzenie paneli administracyjnych, w których można:
- podejrzeć listę oczekujących zadań;
- usunąć błędne itemy;
- ponowić wybrane zadania;
- zmieniać parametry pracy workera (np. liczbę itemów na cykl).
Utrzymanie kolejek wymaga systematyczności, ale w zamian zapewnia większą przewidywalność i kontrolę nad zachowaniem całego serwisu Drupal, szczególnie w projektach o dużej skali i złożonych integracjach.
Yulia Dovha
Yulia Dovha tworzy treści dla bloga icomSEO: praktyczne poradniki o SEO, reklamie i marketingu internetowym.
