Jak zaprojektować skalowalny REST API w PHP: dobre praktyki dla nowoczesnych aplikacji webowych

Po co w ogóle mówić o „skalowalnym” REST API w PHP

Działające API kontra skalowalne API

REST API w PHP można postawić w weekend. Formularz logowania, kilka endpointów CRUD, prosty token w tabeli users i gotowe. Problem zaczyna się, gdy liczba użytkowników rośnie, pojawiają się kolejne zespoły (np. mobilny i frontend SPA), a biznes wymaga nowych funkcji co sprint. Wtedy „działające” API przestaje wystarczać.

„Działające” API to takie, które obsługuje bieżący ruch, ale:

• każda większa zmiana wymaga ruszania kilku miejsc naraz,
• dodanie pola w odpowiedzi potrafi zepsuć starą wersję aplikacji mobilnej,
• przy skoku ruchu (kampania, integracja z większym partnerem) serwer po prostu się dławi,
• deweloperzy boją się refaktoringu, bo testy są szczątkowe albo wcale ich nie ma.

Skalowalne API to takie, które:

• można poziomo powiększyć (więcej instancji) bez zmiany kodu,
• da się rozwijać równolegle przez kilka zespołów, nie trącąc się co commit,
• wytrzymuje rosnący ruch bez wykładniczych kosztów sprzętowych,
• jest przewidywalne dla klientów (stabilny kontrakt, sensowne wersjonowanie).

Fundamentalna różnica: „działające” API skupia się na tym, żeby request dostał jakąkolwiek odpowiedź. „Skalowalne” API skupia się na tym, żeby odpowiedzi nie zabrakło wtedy, kiedy naprawdę zaczyna się biznes.

Granice PHP: co naprawdę boli, a co jest mitem

Wokół PHP narosło sporo mitów. Jednym z najpopularniejszych jest to, że „PHP się nie skaluje”. Tymczasem duże serwisy internetowe od lat działają na klasycznym stosie PHP-FPM + Nginx, a ich limitem wcale nie jest interpreter języka, tylko baza danych, I/O i chaos architektoniczny.

PHP ma swoje realne ograniczenia:

• model „request–response” – brak długotrwałych procesów z natury (chyba że użyjesz Swoole/RoadRunner),
• brak wbudowanego, niskopoziomowego mechanizmu współbieżności znanego z innych języków,
• łatwość pisania „na skróty” – jeden plik, kilka zapytań SQL i już coś działa.

Jednocześnie sprzętowo i architektonicznie PHP skaluje się dobrze: instancje można powielać niemal bezmyślnie, bo proces nie trzyma stanu między requestami. Klucz tkwi w tym, by stan trzymać w bazie, cache (Redis, Memcached) i dobrze przemyślanej warstwie domenowej, a nie w sesjach klejonych na szybko.

Mitem jest za to przekonanie, że zmiana PHP na „modniejszy” język automatycznie rozwiąże problemy ze skalą. Jeśli model danych jest zły, endpointy są nieprzemyślane, a każde odpytywanie listy użytkowników robi 40 zapytań SQL, to przepisywanie na inny język jedynie drogo utrwali te same błędy.

Mikroserwisy jako lekarstwo? Niekoniecznie od razu

Gdy ruch zaczyna rosnąć, pierwszym odruchem wielu zespołów jest techniczna ucieczka w mikroserwisy. To dobra droga – ale za wcześnie wdrożona potrafi zabić produktywność. Mikroserwisy mają sens, gdy:

• masz już wyraźne granice domen (np. płatności, katalog produktów, konta użytkowników),
• zespoły są na tyle duże, że monolit utrudnia równoległą pracę nad kodem,
• istnieje realna potrzeba różnego skalowania poszczególnych części systemu,
• masz minimum dojrzałości w CI/CD, logowaniu, monitoringu, testach kontraktowych.

Mikroserwisy nie rozwiązują bałaganu w kodzie – tylko go rozpraszają po sieci. Jeśli logika biznesowa jest w kontrolerach, nazwy endpointów są chaotyczne, a baza danych to jeden wspólny kocioł, to rozbijanie systemu jedynie mnoży miejsca, gdzie ten chaos trzeba opanować.

Przeciwnie, dobrze zorganizowany monolit API w PHP z jasnymi modułami, sensowną warstwą domenową i kontraktem opisanym OpenAPI jest w wielu przypadkach lepszym i tańszym wyborem przez lata. Dopiero kiedy faktycznie pojawia się konieczność wydzielania fragmentów – np. część płatnicza musi mieć osobny cykl releasów – można myśleć o przejściu w stronę mikroserwisów.

Gdy prosty CRUD staje się wąskim gardłem

Klasyczny scenariusz: aplikacja startuje jako prosty panel z API dla SPA. Jeden serwer PHP, jedna baza, kilka endpointów CRUD. Zespół szybko dowozi funkcje, bo nie ma rozbudowanej architektury. Kampania marketingowa wypala, produkt rośnie, pojawia się aplikacja mobilna i integracje z zewnętrznymi partnerami.

Nagle:

• liczba requestów rośnie kilkukrotnie,
• prosta lista zasobów generuje timeouty (bo dochodzą filtry, joiny i sortowanie po kilku polach),
• każda zmiana odpowiedzi API wymaga aktualizacji kilku klientów,
• bug w jednym endpointzie potrafi wyłożyć cały proces PHP-FPM z racji złej konfiguracji.

Wprawdzie kod nadal „działa”, ale staje się wąskim gardłem zarówno wydajnościowo, jak i organizacyjnie. To dokładnie ten moment, kiedy zaczyna się rozmowa o skalowalnym REST API w PHP – nie tylko w sensie serwerów i cache, ale przede wszystkim kontraktu, architektury i sposobu pracy zespołu.

Dobrze zaprojektowane API od początku wymaga trochę więcej dyscypliny, ale znakomicie ułatwia późniejsze ruchy w stronę kontenerów, autoskalowania i nawet przejścia do modelu mikroserwisowego. Warunek: trzeba od początku myśleć w kategoriach zasobów i stabilnego kontraktu, a nie jedynie szybkich endpointów pod pojedynczą funkcję frontendu.

Fundamenty architektury REST w praktyce, a nie w książkach

Resource-oriented design zamiast endpointów do funkcji

Kluczowa różnica między REST-em „z książki” a REST-em, który pomaga skalować system, tkwi w tym, czy projektujesz zasoby, czy operacje. Popularny zły wzorzec to API w stylu:

• POST /doLogin
• POST /getUserData
• POST /updateUserProfile

Takie podejście traktuje endpoint jak „zdalne wywołanie funkcji”. Z pozoru działa, ale psuje spójność, utrudnia cache’owanie i generuje chaos w nazewnictwie. Resource-oriented design buduje adresację wokół bytów biznesowych:

• POST /auth/tokens – stworzenie tokenu (logowanie),
• GET /users/{id} – pobranie profilu użytkownika,
• PATCH /users/{id} – aktualizacja profilu.

Zaletą takiego podejścia jest to, że struktura URL-i odzwierciedla model domenowy. Można z łatwością dołożyć powiązane zasoby (np. /users/{id}/orders), a także niezależnie rozwijać logikę związaną z danym zasobem bez mnożenia niepowiązanych nazw typu /getOrdersByUser, /getUserOrdersV2 itd.

Kontrakt API jako kod: OpenAPI/Swagger

Skalowalny REST API w PHP nie istnieje bez jasnego kontraktu. Przy małej skali zespołu wystarczą notatki w README i kilka przykładów w Postmanie. W momencie, gdy dochodzą oddzielne zespoły frontendowe, mobilne, integracje zewnętrzne i QA, kontrakt musi stać się kodem.

OpenAPI (Swagger) pełni w dojrzałych projektach trzy role naraz:

• specyfikacji – opisuje dokładnie zasoby, parametry, modele danych, kody odpowiedzi,
• źródła generatorów – clients SDK, stuby serwerów, przykłady w dokumentacji,
• podstawy testów kontraktowych – sprawdzenie, czy backend i frontend mówią tym samym językiem.

Kluczowe jest traktowanie specyfikacji jako części repozytorium, wersjonowanej razem z kodem. Nie PDF wrzucony na dysk, nie statyczna strona aktualizowana „od święta”. W praktyce dobry przepływ wygląda tak:

• zmiana w API zaczyna się od zmiany w pliku OpenAPI,
• specyfikacja przechodzi code review jak zwykły kod,
• dopiero na tej podstawie powstaje implementacja i testy.

Takie podejście unika typowej bolączki: „frontend już wdrożył, backend coś zmienił, dogadują się na Slacku, a dokumentację poprawimy później”. Przy większej skali to „później” nigdy nie nadchodzi, a efektem jest API, którego nikt do końca nie rozumie.

Gdzie trzymać logikę: po stronie API czy klienta

Bardzo częsta, a niedoceniana decyzja projektowa: ile logiki biznesowej włożyć w API, a ile zostawić klientowi (SPA, aplikacjom mobilnym, innym serwisom). Zbyt częsta rada brzmi: „API ma być tylko cienką warstwą nad bazą danych, reszta logiki w frontendzie”. Na papierze wygląda elegancko, w praktyce kończy się tym, że:

• logika walidacji i uprawnień jest zdublowana w kilku klientach,
• zmiana reguły biznesowej wymaga releasu wszystkich aplikacji,
• zabezpieczenia stają się powierzchowne, bo klient jest z definicji podatny na manipulację.

Lepszym podejściem jest dzielenie logiki na trzy poziomy:

• logika prezentacji – układ ekranu, kolejność kroków, lokalne walidacje UX (np. format numeru telefonu),
• logika interakcji – sekwencje wywołań API, stany formularzy, tymczasowe dane,
• logika domenowa – zasady biznesowe, uprawnienia, reguły przetwarzania, które muszą być spójne niezależnie od klienta.

To właśnie logika domenowa powinna siedzieć w API i warstwie serwerowej. Cienkie API nad bazą jest atrakcyjne na start, ale zwykle mści się przy pierwszym większym redesignie aplikacji mobilnej. Znacznie bezpieczniej jest przyjąć, że API jest źródłem prawdy o regułach biznesowych, a klient dodaje jedynie logikę związaną z interfejsem i doświadczeniem użytkownika.

Cienkie endpointy kontra tłuste frontendy – gdzie jest granica

Popularna rada mówi: „rób maksymalnie cienkie endpointy, niech API będzie tylko bramką do bazy, dzięki temu łatwiej je przetestować”. Ten koncept ma sens w mikroserwisach skupionych na jednym wąskim przypadku użycia, ale w klasycznym REST API dla nowoczesnej aplikacji webowej szybko tworzy „tłuste frontendy”.

Przykład z życia: frontend musi wyświetlić widok zamówienia, na którym jest:

• status zamówienia,
• lista produktów,
• informacje o płatności,
• dane o dostawie,
• historia zmian statusu.

Przy „cienkim API” klient robi 5–7 różnych wywołań, łączy dane u siebie, a potem i tak musi znać wszystkie reguły biznesowe dotyczące prezentacji statusu, płatności itp. Przy dużej liczbie użytkowników każde takie mnożenie requestów jest mordercze. Z drugiej strony, jedno ogromne „GET /getOrderDetails” zwracające gigantyczny JSON i robiące wszystko w jednym miejscu również nie jest dobrą strategią.

Rozsądna, pragmatyczna równowaga polega na tym, by API dostarczało specyficzne projekcje danych (widoki), ale nadal trzymało logikę domenową u siebie. To często prowadzi do wzorców w stylu CQRS (osobne endpointy do odczytu i do zapisu). Klient odpyta jedno sensowne GET /orders/{id}, które zwraca wszystkie potrzebne dane w zoptymalizowanej strukturze, a reguły prezentacji bazują na polach zdefiniowanych centralnie w API.

Wybór stosu technologicznego w PHP: frameworki, serwery, kontenery

Laravel, Symfony, Slim i „goły” PHP – co naprawdę się skaluje

Spór o to, który framework PHP „lepiej się skaluje”, najczęściej sprowadza się do porównywania wyników z prostych benchmarków typu „Hello World”. W praktyce, dla skalowalnego REST API ważniejsze są:

• dojrzałość ekosystemu,
• dostępność narzędzi (ORM, migracje, messaging, testowanie),
• spójne konwencje i standardy zespołu,
• łatwość utrzymania i rekrutacji.

Laravel daje szybki start, dużo gotowych komponentów i bardzo rozbudowany ekosystem. Świetnie nadaje się do budowy API w modelu „product-first”, gdzie ważna jest szybkość dowożenia funkcji. Z kolei Symfony wygrywa tam, gdzie oczekuje się bardziej granularnej kontroli nad komponentami, lepszej integracji z zaawansowanymi narzędziami (np. Messenger, serwisy asynchroniczne) i bardziej „enterprise’owego” podejścia.

Slim i inne mikroframeworki (Mezzio, Lumen) są sensowne tam, gdzie głównym celem jest minimalny narzut i pełna kontrola nad każdym elementem stosu. Sprawdzają się w małych, wyspecjalizowanych serwisach, bramkach API, adapterach do zewnętrznych systemów. Skaluje je nie tyle sam framework, ile prostota – mniej „magii”, mniej zależności, mniejszy koszt poznawczy dla nowych osób w zespole. „Goły” PHP ma podobną zaletę, ale tylko wtedy, gdy zespół naprawdę potrafi narzucić sobie konwencje i konsekwentnie ich pilnować. Bez tego bardzo szybko robi się drugi monolit „legacy”, tyle że bez wsparcia narzędziowego.

Popularna rada brzmi: „bierz najlżejszy framework, bo wtedy będzie szybciej”. To działa w mikrobenchmarkach, natomiast przy prawdziwym ruchu wąskim gardłem rzadko jest sam framework. Częściej są to: baza danych, blokujące wywołania HTTP, sesje trzymane w wolnym storage’u, brak cache’owania lub źle zaprojektowany model domenowy. Zamiast obsesyjnie ścinać milisekundy w warstwie routera, zwykle lepiej zainwestować w spójne moduły, testowalność i monitoring, które realnie obniżają koszt zmian przy rosnącym obciążeniu.

Z drugiej strony, „enterprise’owy” stos oparty na pełnym Symfony też ma swoje granice. Tam, gdzie potrzebnych jest wiele bardzo prostych, krótko żyjących usług (np. narzędziowe API do ETL, webhooki techniczne, małe integracje), pełny kontener DI, rozbudowany event dispatcher i kilkumegabajtowy bootstrap potrafią być po prostu przerostem formy. Praktyczny kompromis to mieszana architektura: główne, „grube” API w Laravelu lub Symfony, a obok mniejsze serwisy w Slimie lub nawet w „gołym” PHP, ale spięte tym samym obserwowalnym środowiskiem (logi, metryki, tracing).

Skalowanie na poziomie serwera to osobny wątek. PHP-FPM z Nginxem wciąż jest standardem bojowo sprawdzonym w setkach dużych projektów i najczęściej wystarcza, dopóki nie wchodzisz w ekstremalne obciążenia czy długotrwałe połączenia (websockety, SSE). Rozwiązania typu RoadRunner czy Swoole, utrzymujące procesy w pamięci, zyskują sens dopiero wtedy, gdy naprawdę wiesz, że overhead „request per process” jest problemem, a zespół jest gotowy na inne wzorce zarządzania stanem (brak gwarancji „czystego” procesu na każde żądanie, konieczność ostrożnego obchodzenia się z singletonami i pamięcią). Zbyt wczesne przejście na takie rozwiązania zwykle po prostu komplikuje debugowanie bez realnych zysków.

Na poziomie kontenerów i orkiestracji większość „mądrości” sprowadza się do kilku prostych decyzji: obraz oparty na oficjalnym PHP (alpine tylko jeśli rozumiesz koszty), budowanie wieloetapowe (oddzielenie builda od runtime), osobne kontenery dla PHP-FPM i reverse proxy, rozsądne limity CPU/RAM i health checki odzwierciedlające prawdziwy stan aplikacji (np. dostęp do bazy, kolejki). Kubernetes nie naprawi źle zaprojektowanego modelu danych ani nie odciąży jednego, centralnego monolitu, ale ułatwi replikację i rollouty, gdy backend jest już sensownie pocięty na moduły i potrafi żyć w wielu instancjach.

Po więcej kontekstu i dodatkowych materiałów możesz zerknąć na Porady-IT.pl – Kurs PHP, Webmastering i Skrypty dla Nowoczesnych.

Skalowalny REST API w PHP nie jest efektem jednej magicznej technologii ani idealnego frameworka. Powstaje raczej z serii świadomych kompromisów: między „czystością” a pragmatyzmem, między cienkim API a spójną logiką domenową, między szybkim startem a możliwością bezbolesnej rozbudowy. Jeśli adresacja zasobów jest spójna, kontrakt traktowany jak kod, a zespół rozumie granice swojego stosu, to nawet „zwykły” PHP-FPM na kilku replikach potrafi obsłużyć zaskakująco duży ruch bez dramatycznych refaktoryzacji.

Serwer HTTP, PHP-FPM i reverse proxy – jak nie przestrzelić z „optymalizacją”

Typowy stos dla REST API w PHP to Nginx (lub Apache) + PHP-FPM. Powszechna rada brzmi: „dokręć workerów FPM i zwielokrotnij instancje, żeby obsłużyć więcej ruchu”. Kiedy aplikacja jest jeszcze młoda, działa to znakomicie. Po pewnym czasie pojawia się jednak efekt uboczny: kolejki procesów, rosnące czasy odpowiedzi, a CPU wcale nie jest na 100% – zamiast tego blokuje się I/O.

Źródło problemu leży często nie w liczbie procesów, ale w tym, co one robią. Jeżeli większość requestów:

• czeka na wolną bazę danych,
• odpycha się o ten sam zamek (np. sesja w pliku, blokujący cache),
• wykonuje wiele zewnętrznych requestów HTTP w trybie synchronicznym,

to zwiększanie liczby procesów PHP-FPM tylko zwiększa presję na najsłabsze ogniwo. Zamiast „tuningu” w ciemno, trafniejsze jest krótkie ćwiczenie z metryk: czas obsługi w PHP, czas zapytań do DB, occupancy workerów. Dopiero wtedy ma sens decydować, czy podnosimy limity FPM, czy raczej rozdzielamy obciążenie na oddzielne pule (np. osobna pula FPM do ciężkich zadań administracyjnych).

Dobrą praktyką jest też jasny podział:

• Nginx/Apache – SSL, routing na poziomie hostów, prosty caching,
• PHP-FPM – logika biznesowa, generowanie odpowiedzi,
• serwisy pomocnicze – kolejki, cache, storage plików, monitoring.

Ładowanie wszystkiego do jednej instancji „web + PHP + cron + worker” kusi prostotą, ale dopiero rozdzielenie ról pozwala skalować niezależnie poszczególne elementy. Przy większych API to właśnie osobne skalowanie workerów kolejki (np. konsumentów RabbitMQ) często ratuje API przed padnięciem, gdy nagle pojawi się nietypowe obciążenie jedną klasą zadań (np. importy, generowanie raportów).

Konteneryzacja bez religii – Docker, obrazy i granice izolacji

Jeżeli zespół przechodzi z „klasycznego” deploya na Docker + orchestrator, dość popularne jest założenie, że „teraz wszystko będzie skalowalne z definicji”. Rzeczywistość bywa inna: aplikacja, która wcześniej ledwo zipała na jednym serwerze, w kontenerach potrafi wolniej odpowiadać, a jednocześnie zużywać więcej RAM.

Kontenery pomagają wtedy, gdy:

• aplikacja jest stateless (albo przynajmniej sesje i pliki przeniesiono poza lokalny dysk),
• można ją uruchomić w wielu replikach bez złożonej koordynacji stanów,
• monitoring i logi są scentralizowane (ELK, Loki, otagowane logi JSON).

Jeśli REST API nadal trzyma sesje w plikach na lokalnym dysku albo opiera się na współdzielonym montowanym NFS, to każdy „scale up” w orchestratorze tylko zwiększa szansę na race condition w IO. W takim scenariuszu prostsze i bezpieczniejsze jest najpierw przeniesienie sesji do Redis/Memcached (albo w ogóle eliminacja sesji na rzecz stateless JWT), a dopiero potem wejście w świat auto-scalingów.

Obraz aplikacji PHP dobrze jest traktować jak artefakt – budowany w sposób powtarzalny, z minimalną ilością narzędzi w warstwie runtime. Typowy schemat:

1. etap build – instalacja zależności (Composer), testy, budowanie assetów (jeśli to samo repo),
2. etap runtime – tylko PHP + rozszerzenia + skompilowany kod + entrypoint.

„Alpine wszędzie” brzmi atrakcyjnie, ale bywa pułapką, jeśli zespół nie ma doświadczenia z różnicami w bibliotekach systemowych, SSL albo gdb/strace. Oszczędność kilkudziesięciu megabajtów w obrazie potrafi kosztować godziny śledzenia subtelnych różnic w zachowaniu rozszerzeń PHP.

Projekt kontraktu API: adresacja zasobów, wersjonowanie i kompatybilność

Zasoby, nie akcje – jak nie przemycać RPC przez HTTP

Popularna praktyka: „REST-owe” endpointy w stylu POST /user/create, POST /user/delete, POST /user/updatePassword. Wygląda to jak REST, ale semantycznie bliżej mu do RPC – kolekcja akcji zamiast zasobów. Przy małej aplikacji jeszcze to działa, przy większej trudniej utrzymać spójność i rozsądne wersjonowanie.

Posługiwanie się zasobami wymusza inny sposób myślenia:

• POST /users – utworzenie użytkownika,
• GET /users/{id} – pobranie reprezentacji,
• PATCH /users/{id} – częściowa aktualizacja,
• DELETE /users/{id} – usunięcie (lub deaktywacja).

Dopiero gdy występują operacje faktycznie „akcyjne”, które trudno zredukować do CRUD (np. „wygeneruj jednorazowy token logowania”, „przelicz raport”), sensownym kompromisem są podzasoby lub kolekcje operacji:

Jeśli interesują Cię konkrety i przykłady, rzuć okiem na: Case study: integracja API pogodowego w aplikacji turystycznej.

• POST /users/{id}/password-reset,
• POST /reports/generation-requests.

Taki kontrakt ułatwia skalowanie, ponieważ:

• cache HTTP ma sens – GET na tych samych URL-ach jest idempotentny,
• łatwiej agregować logi i metryki per typ zasobu,
• zmiana implementacji (monolit → mikroserwisy) nie wymusza zmiany kontraktu.

API, które od początku budowane jest jako „zestaw komend”, kończy z endpointami specyficznymi dla pojedynczych ekranów. To przywiązuje backend do frontendu i drastycznie utrudnia reużycie w nowych klientach (np. partner B2B, aplikacja CLI).

Adresacja i paginacja – kompromis między prostotą a elastycznością

Spory o to, czy lepsze jest /users/{id} czy /users?id= zazwyczaj są jałowe – istotniejsze są spójne zasady adresacji i rozsądna paginacja. Jeśli w jednym miejscu używasz /users/{id}, a w innym /user/{id} lub /accounts/{userId}, to problem nie jest semantyczny, tylko organizacyjny.

Dziwna, ale częsta praktyka przy API w PHP: domyślna paginacja w stylu ?page=1&per_page=10, bez limitów z góry i bez jasnych zasad sortowania. Działa, dopóki nie pojawi się endpoint, z którego korzystają intensywnie integracje zewnętrzne, robiąc „pobierz wszystko” bez filtra. Serwer, który wcześniej znosił ruch użytkowników, nagle dostaje kilkaset żądań pobierających kolejne strony z 10 000 rekordów, każdy z kosztownymi JOIN-ami.

Bezpieczniej jest z góry narzucić:

• twarde maksimum per_page (np. 100–200),
• domyślne sortowanie po stabilnym polu (np. created_at, id),
• preferowanie paginacji stronicowanej lub opartej o kursor (np. ?cursor=...).

Paginacja kursorowa jest mniej „przyjazna” wizualnie, ale lepiej skaluje się przy dużych tabelach i intensywnych zapisach. W PHP nie jest trudna w implementacji – wystarczy deterministyczne pole (zazwyczaj monotoniczny id lub timestamp) i enkodowanie kursora (np. jako base64 z JSON-em). Zyskujesz m.in. mniej kosztowne zapytania (WHERE id > :lastId LIMIT :limit) i brak przeskakiwania rekordów między stronami.

Wersjonowanie: nagłówek, ścieżka czy brak wersji?

Dość często powtarzana rada mówi: „dodaj od razu /v1 w ścieżce, łatwiej będzie wprowadzić v2”. Rzeczywistość: większość API latami pozostaje przy „v1”, ewentualnie dorabiając /v2 tylko do pojedynczych endpointów, co kończy się „mixem epok”.

Praktyczne podejście do wersjonowania w REST API w PHP może wyglądać tak:

• na starcie – bez wersji w URL, za to z dyscypliną semantycznych zmian (dodawanie pól jest dozwolone, zmiana znaczenia istniejących – tylko po bardzo świadomej decyzji),
• jeżeli pojawia się potrzeba radykalnej zmiany – wydzielana jest druga aplikacja lub moduł (np. /v2 jako osobny kontroler / router, a nie „if v2” w kodzie v1),
• dla klientów B2B – wersjonowanie per kontrakt (np. osobne klucze API przypisane do konkretnej wersji).

Wersjonowanie w nagłówkach (Accept: application/vnd.myapp.v2+json) ma sens w organizacjach, które mają już dojrzałe narzędzia do API gateway i kontraktów. W większości zespołów PHP dodatkowo komplikuje debugowanie (trudniej o proste curl w logach) i jest przerostem formy. Bardziej realnym problemem jest zachowanie kompatybilności wstecznej przy ewolucji jednego endpointu niż „uroczyste” wprowadzanie nowej wersji całego API.

Kontrakt jako kod: OpenAPI, testy i „prywatne publiczne API”

Częsty błąd to traktowanie kontraktu API jako dokumentu „dla integratorów”, który powstaje później niż sama implementacja. Przy rosnącym ruchu to właśnie niespójność między kodem a kontraktem generuje najwyższe koszty – klient wysyła dane w formacie X, backend oczekuje X’, a bug wychodzi dopiero w produkcji.

Przygotowanie definicji OpenAPI (Swagger) przed implementacją nie jest akademicką zabawą. W praktyce wymusza decyzje:

• jakie typy przyjmujemy (string, integer, enum),
• które pola są obowiązkowe, a które opcjonalne,
• jak wyglądają błędy (format error_code, message, ew. details).

W PHP dodanie warstwy walidacji opartej o kontrakt jest trywialne, jeśli narzucisz sobie zasadę: każdy endpoint ma powiązaną specyfikację, a testy integracyjne weryfikują zarówno poprawne odpowiedzi, jak i błędy przy złych danych. Tego typu testy są dużo cenniejsze z punktu widzenia skalowalności niż kolejne testy jednostkowe „czy serwis OrderService wywołał repozytorium”. Ograniczają ryzyko, że przy wprowadzaniu nowych klientów (np. druga aplikacja mobilna) backend będzie musiał nagle tworzyć dziwne „tryby kompatybilności”.

Dobrym kompromisem między elastycznością a bezpieczeństwem jest podejście „publiczne prywatne API”: nawet jeśli API jest używane tylko przez frontend tego samego zespołu, kontrakt traktuje się jak publiczny. Zakłada się, że po jego wydaniu nie wolno z dnia na dzień zmienić znaczenia pól. Zmniejsza to pokusę „naprawiania” błędów frontendem i przerzucania odpowiedzialności za spójność na klienta.

Model domenowy i warstwy logiki: jak nie zamienić API w spaghetti

Warstwa aplikacji, domeny i infrastruktury – ile rozdzielać w PHP

Spotkać można dwa skrajne podejścia. Pierwsze: „MVC wystarczy, wszystko da się zmieścić w kontrolerze i modelu Eloquent/Doctrine”. Drugie: „pełny DDD z agregatami, event sourcingiem i kilkunastoma warstwami abstrakcji”. Oba potrafią zabić skalowalność: pierwsze przez chaos, drugie przez paraliż decyzyjny i przesadną złożoność.

Do REST API w PHP zwykle wystarcza prosty, ale konsekwentny podział:

• warstwa aplikacji – use case’y (komendy i zapytania), orkiestracja kroków, transakcje,
• warstwa domeny – encje, wartości, reguły biznesowe (metody, nie tylko gettery/settery),
• warstwa infrastruktury – bazy danych, kolejki, HTTP do integracji, filesystem, cache.

Kontroler nie powinien znać szczegółów domeny ani bazy danych. Przetwarza żądanie (walidacja inputu), wywołuje odpowiedni „use case” (np. CreateOrderHandler), a potem mapuje wynik na odpowiedź HTTP. Use case operuje na interfejsach repozytoriów lub serwisów domenowych i zawiera minimalną ilość logiki – tylko to, co dotyczy konkretnej operacji (np. „utwórz zamówienie, wyślij event, jeżeli to pierwsze zamówienie użytkownika, ustaw flagę”).

Taki podział ma praktyczny efekt: gdy rośnie ruch, łatwiej wyodrębnić najbardziej obciążone moduły i przenieść je do oddzielnych serwisów lub osobnych procesów (np. workerów). Nie jesteś uwiązany do jednego, monolitycznego kontrolera, który po trochu robi wszystko – od walidacji danych po specyficzne zapytania SQL.

DTO, mapery i „anemiczny model” – kiedy to nie przesada

Często pojawia się zarzut, że używanie osobnych obiektów DTO między warstwami robi z kodu „Javę w PHP”. Tymczasem, przy większym REST API, mieszanie encji ORM z reprezentacją JSON w odpowiedziach HTTP to prosta droga do sprzężenia bazy z kontraktem API.

W praktyce dobrze jest rozdzielić:

• encje domenowe / ORM – reprezentacja stanu wewnątrz systemu,
• DTO wejściowe – dane z żądania już po walidacji,
• DTO wyjściowe – dane przygotowane do serializacji (view models, read models).

DTO nie muszą być rozbudowane. Często wystarczy prosta klasa z kilkoma polami i konstrukcją tylko przez konstruktor. Zyskujesz coś ważniejszego niż „czystość” – kontrolę nad miejscem, w którym dodajesz nowe pola czy zmieniasz nazwy. Gdy frontend poprosi o kolejne właściwości w odpowiedzi, nie musisz dotykać encji ani repozytoriów, tylko rozszerzasz DTO i mapper. To dokładnie ten rodzaj „tarcia”, który chroni przed sytuacją, w której przy drobnej zmianie responsa musisz przepisywać pół warstwy bazodanowej.

Popularna rada „unikaj anemicznego modelu” w aplikacjach CRUD-owych zwykle nie działa. Jeżeli logika biznesowa jest skromna, wymuszanie „bogatych encji” z dziesiątkami metod tylko po to, by kod wyglądał „DDD-owo”, kończy się teatralnym wzorcem, a nie realną korzyścią. Dużo rozsądniejsze bywa utrzymanie encji stosunkowo prostych, za to otoczenie ich dobrze zaprojektowanymi serwisami domenowymi i solidnymi testami scenariuszy. Zysk skalowalności bierze się tu z przewidywalności – łatwo przewidzieć, które metody są używane przy jakich endpointach i jakie mają skutki uboczne.

Mapowanie między warstwami nie musi też oznaczać dziesiątek ręcznie pisanych klas „Mapper”. W wielu zespołach sprawdza się prosty wzór: jawne mapowanie w kilku metodach statycznych (np. UserDto::fromEntity(), UserResponse::fromDto()) i ewentualnie cienka warstwa pomocnicza tam, gdzie konwersji jest najwięcej. Narzędzia typu automapper brzmią kusząco, ale przy większym API mocno utrudniają śledzenie, skąd bierze się konkretna struktura JSON. Skalowalność operacyjna (debugowanie w stresie, w piątek wieczorem) jest tu często ważniejsza niż skrócenie kilku klas o kilkanaście linii.

Dobrym testem na to, czy podział na DTO i encje ma sens, jest hipotetyczne przeniesienie warstwy API do innego procesu lub języka. Jeżeli model domenowy daje się wtedy wynieść prawie w całości, a zmienia się głównie kontrakt i mapery, to znaczy, że separacja warstw działa. Jeżeli odwrotnie – JSON-y, encje i zapytania SQL są ze sobą tak splecione, że każda zmiana kontraktu wymaga ingerencji w całą resztę – monolit tylko udaje modularność.

Transakcje i spójność: gdzie kończy się „magia frameworka”

Przy prostym CRUD-zie kusi, aby transakcje zostawić ORM-owi: wywołanie save() lub flush() i gotowe. Problem pojawia się, gdy pojedyncze wywołanie API wykonuje kilka kroków: zapisuje kilka encji, wysyła event, dotyka zewnętrznego systemu płatności. Wtedy brak świadomego zarządzania transakcjami skutkuje „pół-operacjami” – część stanu zapisana, część nie.

Praktycznym podejściem jest wyraźne określenie granic transakcji w warstwie aplikacji. Każdy „use case” powinien dbać o spójność swojego procesu, zwykle w formie:

• otwarcie transakcji na początku obsługi komendy,
• wszystkie zmiany w bazie wewnątrz tej transakcji,
• commit dopiero po pomyślnym przejściu walidacji domenowej i zapisach,
• wszelkie integracje zewnętrzne (HTTP, kolejki) – po commicie lub w workerach.

Popularna rada „wyślij event w tej samej transakcji, co zapis w bazie” rozpada się przy pierwszym poważniejszym incydencie produkcyjnym. Nie masz gwarancji, że broker kolejki zadziała identycznie jak baza, a rollback w jednej warstwie nie cofa tego, co już zostało wypchnięte na zewnątrz. Dużo rozsądniejsze jest stosowanie wzorca outbox: zapis eventu do tabeli w tej samej transakcji co zmiany domenowe, a dopiero osobny proces (worker) publikuje go do kolejki.

W PHP „magia frameworka” często kończy się na adnotacji @Transactional lub mechanizmie middleware. To działa, dopóki 99% żądań robi jedną rzecz. Gdy pojawiają się złożone kompozycje (np. „stwórz zamówienie, zaktualizuj limit kredytowy, wyślij powiadomienie”), dobrze jest mieć jawny, testowalny kod inicjujący i kończący transakcję – nawet kosztem kilku dodatkowych linii.

Granice modułów a granice transakcji

Skalowalne API rzadko jest jedną płaską aplikacją. Często dzielisz je logicznie na moduły: zamówienia, płatności, użytkownicy, katalog produktów. Intuicyjna rada „każdy moduł ma swoją bazę” brzmi nowocześnie, ale w monolicie PHP bywa pułapką – kończysz z transakcjami rozproszonymi, które w praktyce są seriami „best effort” bez silnej spójności.

Bezpieczniejszym krokiem pośrednim jest podział na moduły w kodzie, ale trzymane na jednej fizycznej bazie (lub jednym klastrze). Transakcje wtedy mają jasne granice: operujesz w ramach jednego połączenia DB, a integracje między modułami realizujesz przez:

• jawne wywołania use case’ów (in-process),
• eventy domenowe (in-process) transformowane na eventy integracyjne,
• docelowo – osobne serwisy z komunikacją asynchroniczną.

Rada „wszystko asynchroniczne” brzmi atrakcyjnie, ale przy zbyt wczesnym zastosowaniu rozsypuje gwarancje biznesowe. Jeżeli proces ma znaczenie prawne (np. utworzenie zamówienia i rezerwacja środków), spójność musi być jasno zdefiniowana: albo oba kroki przechodzą, albo nie ma żadnego. Podział na kilka luźno powiązanych mikroserwisów bez twardych kontraktów kończy się trudnymi do odtworzenia błędami – z punktu widzenia klienta API operacja wygląda na „udana”, ale któryś z kroków nie został wykonany.

Dobrym kompromisem jest model: twarda spójność w ramach modułu/serwisu, miękka spójność między nimi. Jeden endpoint API wykonuje tylko tę część biznesu, która może być atomowa. Wszystko, co jest „dodatkową wartością” (np. powiadomienia, rekomendacje, synchronizacja z CRM), idzie asynchronicznie.

Baza danych, transakcje i zapytania: to tutaj kończy się skalowalność

Projektowanie schematu pod API, a nie pod ORM

Popularna rada „najpierw model obiektowy, reszta sama się ułoży” jest wygodna dla programisty PHP, ale baza danych nie rozumie dziedziczenia, interfejsów ani serwisów. Schemat, który powstaje „przy okazji”, rzadko jest gotowy na rosnący ruch. Zazwyczaj ma za dużo relacji many-to-many, za mało indeksów i kolumny typu TEXT, w których ląduje każdy pół-strukturalny fragment danych.

Projektując API, warto myśleć od strony typowych zapytań, a nie tylko CRUD-u na encjach. Kilka pytań, które trzeba sobie zadać wcześniej, a nie przy pierwszym „time-oucie” w produkcji:

• jakie listy i filtry będą najczęściej używane (np. lista zamówień po dacie i statusie, a nie tylko po ID klienta),
• jakie dane będą pobierane razem w jednym endpointcie (np. zamówienia z pozycjami i podstawowymi danymi o produkcie),
• które pola będą sortowane i wyszukiwane (text search vs. proste porównania).

Z perspektywy bazy lepiej, gdy schemat jest dostosowany do realnych odczytów niż idealny wobec diagramów klas. Jeżeli większość kluczowych endpointów wymaga trzech joinów i filtrów po niezaindeksowanych kolumnach, skalowanie przez dokładanie kolejnych replik niewiele zmieni – zbyt ciężkie zapytania wciąż będą obciążać główną instancję.

Przy większych API opłaca się wprowadzić warstwę raportową lub osobny model odczytu (read model), nawet jeśli na starcie brzmi to jak „overengineering”. Zamiast jednego zestawu tabel obsługujących wszystko, tworzysz dodatkowe tabele lub widoki zoptymalizowane pod konkretne odczyty (np. pod listy w panelu administracyjnym). Pisanie ich ręcznie jest tańsze niż późniejsze gaszenie pożarów wydajnościowych.

Indeksy, plany zapytań i realne profile ruchu

Przy rosnącym API często powtarza się ten sam schemat: pojawia się pierwszy Slack „API zwalnia”, zespół dorzuca losowe indeksy, przez chwilę jest lepiej, a potem baza zaczyna cierpieć z powodu nadmiaru indeksów i kosztownych insertów. Kluczowa jest dyscyplina: indeksy dodaje się świadomie, na podstawie realnych profili zapytań, a nie „na wszelki wypadek”.

Minimalny proces, który zwiększa szanse na skalowalność:

• logowanie wolnych zapytań (slow query log) i ich regularna analiza,
• przegląd planów zapytań (EXPLAIN) dla krytycznych endpointów,
• cykliczny przegląd indeksów – usuwanie tych nieużywanych, a nie tylko dodawanie nowych.

Popularna rada „dodaj indeks do każdej kolumny, po której filtrujesz” ma sens tylko do czasu. Zbyt wiele indeksów wydłuża zapisy, a przy dużym ruchu na INSERT/UPDATE robi się z tego poważny problem. W praktyce trzeba wybierać: krytyczne ścieżki odczytu optymalizujesz mocno, a „raporty poboczne” obsługujesz osobną ścieżką (np. generujesz je asynchronicznie do osobnych tabel).

Narzędzia ORM potrafią generować zaskakujące zapytania. W jednym z projektów REST API w Symfony, pojedynczy endpoint „lista zamówień” generował ponad dziesięć zapytań przez leniwe ładowanie powiązanych encji. Dopiero jawne zdefiniowanie zapytań DQL z joinami i wybieranie tylko potrzebnych pól sprowadziło liczbę zapytań do dwóch, a czas odpowiedzi z kilkuset do kilkunastu milisekund. „Automagiczne” relacje są wygodne, dopóki nie wchodzisz w tysiące rekordów per żądanie.

ORM vs SQL „na piechotę” – gdzie postawić granicę

Rada „używaj ORM, bo przyspiesza development” działa świetnie w pierwszych tygodniach. Po kilku miesiącach, przy bardziej skomplikowanych zapytaniach, ORM przestaje maskować złożoność – zaczyna ją multiplikować. Czasem łatwiej i szybciej jest napisać jedno konkretne zapytanie SQL niż walczyć z ograniczeniami abstrakcji.

Sensowny kompromis to trzymanie ORM-u dla operacji prostych (CRUD, pojedyncze agregacje), a dla krytycznych odczytów i zapisów – świadome używanie natywnego SQL lub query buildera. Wówczas:

• model domenowy nadal korzysta z encji i repozytoriów tam, gdzie to wygodne,
• najcięższe zapytania (raporty, listy, agregacje) są pisane ręcznie i profilowane,
• granica jest jasna: ORM służy wygodzie, nie zastępuje myślenia o wydajności.

W PHP przejście do „niższego poziomu” nie jest zdradą wzorców, tylko narzędziem. Bardziej niebezpieczne bywa trzymanie się „czystego” podejścia mimo dowodów w logach, że generowane zapytania są nieoptymalne. Żaden pattern z książki nie obroni API, jeśli baza przestaje odpowiadać.

N+1, lazy loading i „niewidzialne” zapytania

Zjawisko N+1 jest teoretycznie dobrze znane, a w praktyce wraca w każdym większym projekcie. Typowy scenariusz: endpoint zwraca listę obiektów z powiązanymi danymi (np. zamówienia z klientami i produktami). ORM domyślnie ładuje dane leniwie, więc dostajesz jedno zapytanie po zamówienia, a potem po jednym zapytaniu dla każdego klienta i produktu. Na testowych danych wygląda to niewinnie; przy kilku tysiącach rekordów – zabija bazę.

Najprostsze zabezpieczenie to jawne określanie strategii ładowania zależności dla endpointów listujących dane. Zamiast globalnego włączenia „eager loading wszędzie” (co rodzi inne problemy), lepiej jest per-zapytanie wskazać, co ma być dociągnięte od razu. W Laravelu mogą to być relacje with(), w Doctrine – JOIN FETCH w DQL albo mapowanie fetch mode na poziomie repozytorium.

Popularna rada „profiluj API na danych z produkcji” często jest ignorowana, bo „nie ma na to czasu”. Efekt: błędy wydajnościowe wychodzą dopiero po kilku miesiącach. Rozsądne minimum to cykliczne odpalanie testów wydajnościowych na zanonimizowanym zrzucie bazy i logowanie zapytań dla kilku kluczowych endpointów. Wielu problemów N+1 nie da się zauważyć na developerce z kilkudziesięcioma rekordami.

Cache aplikacyjny i bazodanowy: nie wszystko musi wychodzić z MySQL-a

Przy większym ruchu naturalną reakcją jest „dorzucić więcej serwerów PHP”. Często taniej jest jednak zmniejszyć presję na bazę. Caching bywa przedstawiany jako „optymalizacja później”, ale przy API czytającym znacznie częściej niż zapisującym jest jednym z głównych elementów architektury.

W praktyce można wyróżnić kilka warstw cache:

• cache odpowiedzi HTTP – po stronie CDN lub reverse proxy (np. dla publicznych endpointów katalogu produktów),
• cache aplikacyjny – Redis/memcached dla drogich zapytań lub agregacji,
• cache w bazie – materializowane widoki, tabele z preagregowanymi danymi.

Rada „cache’uj wszystko, co się da” rozpada się przy pierwszym problemie spójności. Kluczowe pytanie brzmi: jak długo dane mogą być nieaktualne i jak trudne jest ich unieważnianie. Dla endpointu „lista produktów” opóźnienie kilkudziesięciu sekund bywa akceptowalne, ale dla salda konta – już nie.

Bardziej praktyczne podejście: wybierz kilka najdroższych endpointów (według logów i metryk) i nadaj im świadomą politykę cache. Na przykład:

• katalog produktów – cache na poziomie CDN przez 30–60 sekund, z unieważnianiem po zmianach,
• statystyki dzienne – generowane okresowo do osobnej tabeli, a API tylko je odczytuje,
• listy „moje zamówienia” – lokalny cache per użytkownik w Redis z krótkim TTL.

Kluczowy jest też dobór kluczy cache. Łączenie ich z kontraktem API (np. user:{id}:orders:v1) ułatwia ewolucję – zmiana formatu odpowiedzi lub logiki nie wymaga skomplikowanych migracji cache, wystarczy nowa przestrzeń kluczy.

Rozdzielenie odczytów i zapisów: repliki, CQRS i granice odpowiedzialności

Gdy baza zaczyna być wąskim gardłem, pierwsza popularna rada to „dołóż repliki do odczytu”. Technicznie to proste: główna baza obsługuje zapisy, repliki – część odczytów. W kodzie PHP pojawia się wtedy abstrakcja typu read/write connection, a ORM pozwala kierować zapytania w odpowiednie miejsce.

Na koniec warto zerknąć również na: Role i obowiązki w zespole projektującym mikroserwisy — to dobre domknięcie tematu.

Problemem jest spójność. Repliki nie są natychmiastowo aktualne; opóźnienie może sięgać od ułamków sekund do kilku sekund. Dla endpointu „lista produktów” to zwykle akceptowalne. Dla „saldo konta po wykonaniu przelewu” – już nie.

Dlatego rozsądniej jest nie stosować ślepo „read from replica everywhere”, tylko:

• oznaczyć endpointy, które mogą czytać nieco przestarzałe dane,
• trzymać operacje „czytaj tuż po zapisie” (read-after-write) na głównej bazie,
• agregacje i raporty kierować na repliki lub osobne modele odczytu.

Bardziej radykalne podejście to CQRS – rozdzielenie modelu zapisu (command side) od modelu odczytu (query side). W PHP nie oznacza to od razu osobnych aplikacji; może to być po prostu oddzielny zestaw repozytoriów i zapytań zoptymalizowanych pod odczyt, trzymanych w innym schemacie lub nawet innym typie bazy (np. Elasticsearch dla pełnotekstowego wyszukiwania). Koszt architektoniczny rośnie, ale zyskujesz dużą elastyczność: możesz skalować warstwę odczytu niezależnie od zapisu.

CQRS bywa sprzedawane jako „srebrna kula na skalowalność”, a tymczasem potrafi zabić mały zespół ilością dodatkowego kodu i problemów ze spójnością. Najrozsądniej wchodzić w ten wzorzec stopniowo: najpierw wydzielić kilka krytycznych zapytań do osobnych repozytoriów i modeli odczytu, dopiero później – jeśli korzyści są widoczne w metrykach – rozdzielać schematy czy bazy. Zbyt szybkie rozczłonkowanie systemu kończy się tym, że deweloperzy spędzają więcej czasu na synchronizacji modeli niż na dostarczaniu funkcjonalności.

Granica między „jedną bazą z replikami” a „pełnym CQRS + osobne storage” zwykle przebiega tam, gdzie zaczynasz mieć różne wymagania niefunkcjonalne dla odczytu i zapisu. Jeśli operacje zapisujące są krytyczne pod kątem spójności, a odczyty mają rosnące wymagania wydajnościowe, to naturalny sygnał, by rozważyć osobny model odczytu. Jeżeli natomiast większość endpointów wymaga silnie aktualnych danych, rozstrzeliwanie ich po replikach i osobnych storage’ach wygeneruje więcej problemów niż oszczędności.

Dobrym testem jest odpowiedź na pytanie: czy gdyby jutro trzeba było całkowicie przeprojektować warstwę odczytu (inne indeksy, inne zapytania, może inna baza), to logika biznesowa zapisu ocalałaby w dużej mierze bez zmian? Jeśli tak – jesteś blisko sensownego rozdziału. Jeśli nie – być może za wcześnie na CQRS, a wystarczy lepsze indeksowanie, profilowanie i rozsądne użycie cache.

Skalowalne REST API w PHP nie powstaje z jednego wielkiego przełomu, tylko z serii przyziemnych decyzji: świadomego kontraktu, prostego modelu, dobrze dobranych indeksów, paru kluczowych miejsc z cache i kilku endpointów napisanych „po staremu” w czystym SQL. Zamiast ścigać modne hasła architektoniczne, lepiej systematycznie usuwać wąskie gardła pokazywane przez metryki – wtedy stos technologiczny przestaje być ograniczeniem, a staje się po prostu jednym z narzędzi, które można spokojnie wymieniać i skalować.

Najczęściej zadawane pytania (FAQ)

Co to znaczy, że REST API w PHP jest „skalowalne”?

Skalowalne REST API w PHP to takie, które wytrzymuje rosnący ruch i zmianę wymagań biznesowych bez przepisywania połowy systemu co kilka miesięcy. Chodzi nie tylko o wydajność, ale też o to, by dało się je rozwijać równolegle przez wiele zespołów, bez ciągłych konfliktów i „przypadkowego” psucia istniejących klientów.

W praktyce skalowalne API:

• można poziomo rozbudować (więcej instancji PHP) bez zmiany kodu,
• ma stabilny kontrakt – nowe pola i wersje nie wywracają starych aplikacji mobilnych,
• trzyma stan poza procesem PHP (baza, cache), dzięki czemu instancje są wymienne.

To jakościowa różnica względem „działającego” API, które po prostu odpowiada na requesty, dopóki liczba użytkowników jest niska.

Czy PHP faktycznie się nie skaluje przy budowie REST API?

Mit o „nieskalowalnym PHP” bierze się głównie z kiepskich implementacji, a nie z samego języka. Klasyczny stos PHP-FPM + Nginx działa z powodzeniem w dużych serwisach – problemy zwykle wywołuje baza danych, brak cache, zły model danych albo chaotyczna architektura.

PHP ma swoje ograniczenia (brak długotrwałych procesów z pudełka, brak natywnej współbieżności na wzór Go czy Node), ale jednocześnie bardzo łatwo je powielać poziomo, bo proces nie trzyma stanu między requestami. Jeśli logika domenowa jest sensownie wydzielona, a dane trzymane w bazie i cache, skalowanie odbywa się głównie przez dokładanie instancji i optymalizację I/O, a nie zmianę języka.

Kiedy warto przejść z monolitu w PHP na mikroserwisy?

Ucieczka w mikroserwisy „bo rośnie ruch” to typowa reakcja obronna – często przedwcześnie. Mikroserwisy zaczynają mieć sens, gdy:

• masz wyraźne granice domen (np. płatności, katalog produktów, konta),
• zespoły są na tyle duże, że monolit blokuje niezależne releasy,
• różne części systemu naprawdę trzeba skalować inaczej,
• istnieją sensowne fundamenty: CI/CD, monitoring, logowanie, testy kontraktowe.

Bez tego problem z bałaganem w kodzie po prostu przenosi się w sieć – zamiast jednego trudnego do ogarnięcia monolitu mamy kilka lub kilkanaście mniejszych, trudnych do ogarnięcia usług.

Dobry, modułowy monolit PHP, z jasną warstwą domenową i kontraktem opisanym OpenAPI, często wytrzyma lata wzrostu. Rozbijanie na mikroserwisy ma wtedy sens, gdy konkretna domena (np. płatności) potrzebuje osobnego cyklu wydań lub rygorystycznie innego poziomu niezawodności.

Jak projektować endpointy REST w PHP: zasoby czy „funkcje”?

Projektowanie w stylu „zdalnych funkcji” (np. POST /doLogin, POST /getUserData) szybko kończy się chaosem. Takie API jest trudniejsze do cache’owania, mniej przewidywalne dla klientów i zwykle gorzej odwzorowuje logikę biznesową.

Spójniejsze podejście to resource-oriented design, w którym adresujesz zasoby biznesowe, a nie operacje:

• POST /auth/tokens – utworzenie tokenu (logowanie),
• GET /users/{id} – pobranie użytkownika,
• PATCH /users/{id} – aktualizacja profilu.

Taka struktura URL-i odzwierciedla model domenowy i ułatwia skalowanie w przyszłości – można naturalnie dołożyć np. /users/{id}/orders bez wymyślania kolejnej serii /getUserOrdersV3.

Jak używać OpenAPI/Swagger, żeby faktycznie pomagał skalować REST API?

OpenAPI ma sens dopiero wtedy, gdy jest traktowane jak kod, a nie jak ładny PDF dla partnerów. Specyfikacja powinna być częścią repozytorium, przechodzić code review i zmieniać się razem z implementacją. Inaczej staje się tylko „ładniejszą dokumentacją, która zawsze jest nieaktualna”.

Praktyczny workflow wygląda tak:

• zmiana w API zaczyna się od edycji specyfikacji OpenAPI,
• specyfikacja jest przeglądana jak zwykły kod, także przez frontend/mobilkę,
• na tej bazie powstają implementacje, testy i ewentualne generatory SDK.

Wtedy OpenAPI staje się realnym kontraktem między zespołami i narzędziem do testów kontraktowych, a nie wyłącznie „ładniejszym Postmanem”.

Jak uniknąć problemów ze skalą, gdy API startuje jako prosty CRUD?

Najczęstszy scenariusz: na początku jest jeden serwer, jedna baza i kilka prostych endpointów CRUD. Działa to dobrze, dopóki nie pojawi się ruch z kampanii, aplikacja mobilna i integracje z partnerami. Wtedy każde dołożenie filtra czy sortowania powoduje timeouty, a zmiana formatu odpowiedzi psuje istniejących klientów.

Żeby nie wpaść w tę pułapkę:

• projektuj API od razu w kategoriach zasobów i stabilnego kontraktu, nie „szybkich endpointów pod widok”,
• wcześnie wprowadź wersjonowanie i politykę dodawania pól (backward compatible),
• pilnuj liczby zapytań SQL na request – agresywny N+1 zabije każdy „prosty CRUD”.

To kilka decyzji, które na starcie spowalniają development o dni, ale przy pierwszym poważnym wzroście ruchu oszczędzają tygodnie gaszenia pożarów.

Gdzie trzymać logikę biznesową: w PHP API czy na kliencie (SPA, mobile)?

Popularna rada „API ma być jak najcieńsze, cała logika w kliencie” sprawdza się tylko przy bardzo prostych produktach. W momencie, gdy dochodzą aplikacje mobilne, panel administracyjny i integracje partnerskie, powielanie złożonej logiki walidacji czy reguł biznesowych po stronach klientów staje się trudne do utrzymania.

Sensowny kompromis to:

• klienci odpowiadają za prezentację, prostą walidację UI i lokalne interakcje,
• serwer (PHP) trzyma reguły biznesowe, spójność danych, autoryzację i „prawdę o domenie”.

Dzięki temu zmiana reguły biznesowej (np. warunków promocji) wymaga głównie zmiany po stronie API, a nie jednoczesnego wdrażania nowej wersji SPA, iOS, Androida i integracji z zewnętrznymi partnerami.

Co warto zapamiętać

• „Działające” REST API to zbyt mało: dopóki ruch jest mały, prosty CRUD zadziała, ale bez stabilnego kontraktu, testów i sensownej architektury bardzo szybko staje się blokadą dla rozwoju produktu i zespołu.
• Skalowalne API skupia się na przewidywalności i wzroście: musi dać się łatwo replikować poziomo, mieć jasne wersjonowanie i kontrakt, który pozwala wielu zespołom rozwijać funkcje równolegle bez ciągłego „psucia” klientów.
• PHP nie jest wąskim gardłem z definicji: prawdziwym problemem są baza danych, I/O i chaos w modelu domenowym, a nie sam interpreter; zmiana języka bez poprawy architektury jedynie przenosi ten sam bałagan na nowy stos.
• Stateless procesy PHP dobrze się skalują, jeśli stan trzymany jest w bazie i cache: kluczowe jest unikanie „sprytnych” sesji i logiki porozrzucanej po kontrolerach, bo to one utrudniają skalowanie, a nie sam model request–response.
• Mikroserwisy nie są lekarstwem na słaby monolit: rozbijanie źle zaprojektowanego API tylko rozprasza problemy po sieci; sens mają dopiero wtedy, gdy domeny są jasno wydzielone, zespoły duże, a narzędzia CI/CD, monitoring i testy kontraktowe już działają.
• Dobrze ułożony monolit API w PHP często wygrywa kosztowo i organizacyjnie: klarowne moduły, warstwa domenowa i kontrakt opisany np. OpenAPI pozwalają latami rosnąć na jednym serwisie, a dopiero później spokojnie wydzielać krytyczne fragmenty.