Većina PHP API-ja počinje s dobrim namjerama: framework, nekoliko kontrolera, ORM model i krajnje točke koje vraćaju JSON. To je dovoljno da se dokaže ideja. Nije dovoljno da se proizvod provede kroz rastući promet, promjenjive zahtjeve, pozadinski rad i tim koji treba sigurno mijenjati sustav.

Stvarno skaliranje manje se svodi na pronalaženje pametne apstrakcije, a više na jasno definiranje granica. Održiv API čini uobičajeni rad jednostavnim, rizičan rad vidljivim i daje pogreškama predvidljivo mjesto kamo mogu otići.

Započnite s modularnim monolitom

Za mnoge proizvode modularni monolit najpraktičnija je polazna točka. Izbjegava opterećenje distribuiranih sustava, a istodobno sprječava da aplikacija postane jedna nediferencirana zbirka kontrolera i modela.

Organizirajte kod oko poslovnih sposobnosti, a ne samo prema tehničkim mapama. Modul narudžbi, primjerice, može posjedovati svoje HTTP radnje, aplikacijske servise, domenska pravila, pojedinosti trajne pohrane i događaje. Ostali moduli komuniciraju putem jasnih sučelja umjesto da izravno pristupaju njegovim tablicama ili internim klasama.

final class PlaceOrder
{
    public function __construct(
        private OrderRepository $orders,
        private InventoryService $inventory,
        private TransactionManager $transactions,
    ) {}

    public function handle(PlaceOrderCommand $command): Order
    {
        return $this->transactions->run(function () use ($command) {
            $this->inventory->reserve($command->items);

            $order = Order::place(
                $command->customerId,
                $command->items
            );

            $this->orders->save($order);

            return $order;
        });
    }
}

Kontroler treba prevesti HTTP zahtjev u naredbu i pretvoriti rezultat u odgovor. Ne bi trebao odlučivati o pravilima zaliha, sastavljati višekoračna pisanja ili potajno izvršavati upite prema bazi podataka kroz nepovezane modele. Tanki kontroleri nisu estetska preferencija; olakšavaju testiranje ponašanja i njegovu ponovnu upotrebu iz CLI naredbe, radnika reda čekanja ili buduće verzije API-ja.

Dizajnirajte ugovore prije pojedinosti implementacije

API je ugovor koji koristi kod nad kojim nemate kontrolu. Tretirajte njegov oblik kao površinu proizvoda. Koristite stabilne nazive resursa, dosljedne omotnice pogrešaka, predvidljivu paginaciju i izričite poruke za provjeru valjanosti.

Verzioniranje je korisno kada je prijelomna promjena neizbježna, ali ne bi trebalo biti zamjena za pažnju. Dodavanje neobaveznog polja obično je sigurnije od promjene značenja ili vrste postojećeg polja. Uklanjanje polja, promjena ponašanja paginacije ili redefiniranje koda pogreške zaslužuje plan migracije i dokumentirano razdoblje zastarijevanja.

Učinite pogreške strojno čitljivima

Korisnik ne bi trebao analizirati prozu da bi odlučio što učiniti sljedeće. Vratite odgovarajući HTTP status i strukturirano tijelo sa stabilnim kodom pogreške. Pojedinosti namijenjene ljudima neka budu korisne, ali nemojte ih učiniti ugovorom.

{
  "error": {
    "code": "inventory_unavailable",
    "message": "One or more requested items are unavailable.",
    "details": {
      "items": ["sku-42"]
    }
  }
}

Idempotentnost je važna svaki put kada klijent može ponovno pokušati pisanje. Mrežni kvarovi događaju se nakon što je poslužitelj možda dovršio rad, ali prije nego što klijent primi odgovor. Za operacije kao što su stvaranje plaćanja ili slanje narudžbe prihvatite ključ idempotentnosti, pohranite dobiveni ishod uz taj ključ i vratite isti ishod za ponovljeni zahtjev. To je pouzdanije od nade da klijenti nikada neće pokušati ponovno.

Koristite bazu podataka kao alat za ispravnost

Provjera valjanosti u aplikaciji nužna je, ali nije konačni autoritet. Ograničenja baze podataka štite podatke kada se više zahtjeva natječe, kada radnici rade istodobno ili kada skripta za održavanje zaobilazi uobičajeni put koda.

• Koristite strane ključeve tamo gdje odnosi moraju ostati valjani.
• Koristite jedinstvena ograničenja za identitete i ključeve deduplikacije.
• Koristite transakcije za promjene koje moraju zajedno uspjeti ili ne uspjeti.
• Stvorite indekse za podršku stvarnim obrascima upita, a zatim ih provjerite planovima upita.

ORM-ovi ubrzavaju uobičajeni rad, ali ne uklanjaju ponašanje baze podataka. Pazite na N+1 upite pri serijalizaciji kolekcija, neograničene skupove rezultata i učitavanje cijelih zapisa kada je potrebno samo nekoliko polja. Eager učitavanje može riješiti jedan problem, a stvoriti drugi ako u memoriju povuče velik povezani graf. Mjerite broj upita, odabrane stupce i količinu redaka za važne krajnje točke.

Konkurentnost zaslužuje promišljen dizajn. Smanjenje zalihe izraženo kao „pročitaj količinu, oduzmi jedan, spremi” može dovesti do prekomjerne prodaje pri paralelnim zahtjevima. Upotrijebite transakciju s odgovarajućom strategijom zaključavanja ili uvjetnog ažuriranja i provjerite rezultat prije potvrđivanja narudžbe. Ispravan pristup ovisi o modelu podataka i bazi podataka, ali temeljno načelo je stalno: učinite invarijantu provedivom pri konkurenciji.

Premjestite spor rad iz putanje zahtjeva

API zahtjev bi obično trebao provjeriti valjanost, autorizirati, trajno spremiti nužno stanje i odgovoriti. Slanje e-pošte, obrada slika, generiranje izvještaja, webhookovi i nebitne integracije pripadaju pozadinskim poslovima.

Red čekanja nije čarobni prekidač za performanse. Poslovi moraju biti sigurni za ponovni pokušaj, vidljivi i dizajnirani za dvostruku isporuku. Radnik može dovršiti vanjsku radnju i ne uspjeti prije potvrđivanja poruke; ponovni pokušaj tada može ponovno pokrenuti posao. Koristite ključeve idempotentnosti s vanjskim servisima gdje su dostupni, bilježite lokalno stanje obrade i izbjegavajte pretpostavku točno jednokratnog izvršavanja.

Kada transakcija mijenja podatke i trebala bi pokrenuti posao, razmotrite outbox obrazac: upišite promjenu domene i zapis događaja u istoj transakciji, a zatim neka radnik objavi događaje na čekanju. Time se izbjegava opasan jaz u kojem predaja baze podataka uspije, ali se proces sruši prije stavljanja naknadnog rada u red čekanja.

Neka kontejneri budu jednostavni, a implementacije reverzibilne

Docker bi trebao učiniti okruženja lokalnog razvoja i implementacije dosljednijima, a ne prikrivati operativnu složenost. Konfiguraciju držite u varijablama okruženja ili namjenskom konfiguracijskom sustavu, nikada u slici koja sadrži produkcijske tajne. Izgradite nepromjenjivu sliku aplikacije, pokrenite instalaciju ovisnosti tijekom izgradnje i upotrijebite zaseban proces za web zahtjeve i radnike reda čekanja kada se njihovo skaliranje i životni ciklus razlikuju.

Sigurnost implementacije proizlazi iz ponovljivosti. Pokrećite migracije kao namjeran korak implementacije i dizajnirajte ih za kompatibilnost sa starom i novom verzijom aplikacije tijekom postupnog izdanja. Dodavanje stupca koji dopušta NULL često je lakše sigurno implementirati nego odmah dodati stupac koji ne dopušta NULL bez zadane vrijednosti u popunjenu tablicu. Popunjavanja podataka i destruktivne promjene sheme treba fazno provoditi umjesto objedinjavanja u jedno nepovratno izdanje.

Promatrajte sustav koji doista imate

Zapisnici, metrike i tragovi ulazni su podaci za dizajn, a ne ukrasi nakon incidenta. Svaki zahtjev trebao bi nositi identifikator korelacije kroz zapisnike aplikacije i odlazne pozive. Bilježite strukturirani kontekst kao što su ruta, status, trajanje i siguran identifikator zahtjeva; izbjegavajte bilježenje vjerodajnica, tokena ili nepotrebnih osobnih podataka.

Pratite ponašanje koje korisnici doživljavaju: stope pogrešaka, latenciju odgovora, starost reda čekanja, neuspjele poslove i pritisak na veze s bazom podataka. Sporu krajnju točku mogu uzrokovati neučinkovit upit, iscrpljen skup veza, udaljena ovisnost ili zasićen radnik. Dobra vidljivost sužava pitanje prije nego što netko počne podešavati pogrešan sloj.

Skalirajte odluke, a ne samo poslužitelje

PHP se dobro skalira kada je aplikacija bez stanja između zahtjeva, skup rad je kontroliran, a pristup podacima discipliniran. No kapacitet infrastrukture ne može nadoknaditi nejasno vlasništvo, nestabilne ugovore ili tihe putanje neuspjeha.

Najjača arhitektura API-ja nije ona s najviše servisa ili obrazaca. To je ona u kojoj razvojni inženjer može pratiti zahtjev, razumjeti pravila koja štite podatke, sigurno ponovno pokušati neuspjelu operaciju i implementirati promjenu bez kockanja s produkcijom. Izgradite ta svojstva rano, pa predložni kod postaje stabilan temelj umjesto stropa.