Integracija API-ja rijetko propadne zato što je netko zaboravio kako poslati HTTP zahtjev. Propadne zato što vanjski svijet nije dio vašeg sustava, a vaš proizvod ipak ovisi o tome da se ponaša kao da jest.

Pružatelj platnih usluga prekine vezu nakon što prihvati naplatu. CRM vrati neočekivani oblik polja. Partnerska usluga uspori tijekom vašeg najprometnijeg sata. Uzvodni API uvede novi status koji ne prepoznajete. Ako ti detalji izravno procure u kontrolere i poslovnu logiku, svaka vanjska ovisnost postaje izvor nestabilnosti u cijeloj aplikaciji.

Tada integracijski sloj postaje drugi mozak vašeg API-ja: promišljena granica koja pamti detalje protokola, primjenjuje obrambena pravila i ostatku aplikacije daje stabilan jezik za rad.

Zašto tanki HTTP klijent nije dovoljan

Primamljivo je staviti SDK poziv ili nekoliko HTTP zahtjeva izravno u servisnu klasu i smatrati posao završenim. Taj je pristup brz, a ponekad i prikladan za interni alat niskog rizika. No produkcijske integracije gomilaju pitanja koja ne pripadaju domenskom kodu: autentikaciju, paginaciju, vremenska ograničenja, ponovne pokušaje, idempotentnost, mapiranje odgovora, ograničenja stope, vidljivost rada sustava i klasifikaciju pogrešaka.

Vaš servis za narudžbe trebao bi odlučivati smije li se narudžba ispuniti. Ne bi trebao morati znati naziva li pružatelj dostave privremeni prekid rada 503, umotava li pogreške validacije u ugniježđeni objekt ili zahtijeva ključ idempotentnosti u određenom zaglavlju.

Korisni integracijski sloj pretvara vanjski ugovor u interni. Vanjska usluga može biti nedosljedna, imati neovisno verzioniranje ili nepotpunu dokumentaciju. Unutar vaše aplikacije pozivatelji bi trebali dobivati predvidive objekte, izričite neuspjehe i ponašanje koje odgovara vašim poslovnim pravilima.

Izgradite granicu protiv korupcije

Izraz „sloj protiv korupcije” može zvučati grandioznije nego što jest. U praksi znači odbiti dopustiti da se koncepti specifični za dobavljača prošire cijelom bazom koda.

Pretpostavimo da aplikacija treba kreirati pošiljke. Umjesto da kontroleri izravno pozivaju klijent prijevoznika, definirajte sučelje vlastitim pojmovima:

interface ShipmentGateway
{
    public function createShipment(CreateShipmentRequest $request): ShipmentResult;
}

Adapter specifičan za prijevoznika može taj zahtjev prevesti u teret podataka pružatelja i njegov odgovor natrag u ShipmentResult. Ostatak aplikacije ne zanima vraća li pružatelj URL naljepnice, kodirani dokument ili token za provjeravanje stanja. Zanima ga je li pošiljka kreirana, na čekanju ili nije uspjela iz razloga koji vrijedi prikazati korisniku.

Ta granica također čini promjene pružatelja podnošljivima. Zamjena prijevoznika, nadogradnja SDK-a ili dodavanje rezervnog pružatelja postaje lokalizirani zadatak, umjesto pretraživanja cijelog repozitorija za terminologijom dobavljača.

Namjerno normalizirajte podatke

Nemojte preslikati svako polje vanjskog odgovora u svoj interni model. Mapirajte samo ono što aplikacija treba, izvorni teret podataka zasebno sačuvajte kada je koristan za podršku ili reviziju te provjeravajte pretpostavke na granici.

Vanjski podaci zaslužuju isti oprez kao i korisnički unos. Polja koja nedostaju, promijenjene enum vrijednosti, neispravne datume i null vrijednosti tretirajte kao očekivane mogućnosti. Strogi mapper koji ne uspije s jasnom integracijskom iznimkom mnogo je sigurniji od dopuštanja da neispravni podaci dospiju do nepovezane poslovne logike i kasnije propadnu bez konteksta.

Učinite neuspjehe dijelom dizajna

Mrežni pozivi nisu obični pozivi funkcija. Zahtjev može propasti prije nego što stigne do pružatelja, nakon što ga pružatelj obradi ili dok odgovor putuje natrag. To su materijalno različite situacije.

Započnite korištenjem izričitih, ograničenih vremenskih ograničenja. Klijent bez vremenskog ograničenja može tijekom incidenta kod nizvodne ovisnosti neograničeno zauzimati radnike. Odvojite vremenska ograničenja povezivanja i ukupnog trajanja zahtjeva kada ih vaša HTTP biblioteka podržava, zatim odaberite vrijednosti koje odgovaraju korisničkom tijeku i redu poslova. Pozadinski posao sinkronizacije može čekati dulje od zahtjeva za naplatu; nijedan ne bi trebao čekati zauvijek.

Ponovni pokušaji zahtijevaju jednaku pažnju. Ponovno pokušavanje svake pogreške može pojačati prekid rada, iscrpiti ograničenja stope i duplicirati nuspojave. Ponovno pokušavajte samo neuspjehe koji su vjerojatno privremeni, poput resetiranja veze, vremenskog ograničenja ili odabranih poslužiteljskih pogrešaka. Koristite mali broj ponovnih pokušaja i eksponencijalno odgađanje s nasumičnim odstupanjem kako mnogi radnici ne bi ponovno pokušavali usklađeno.

for ($attempt = 1; $attempt <= 3; $attempt++) {
    try {
        return $client->send($request);
    } catch (TransientTransportException $e) {
        if ($attempt === 3) {
            throw $e;
        }

        usleep(random_int(100_000, 300_000) * $attempt);
    }
}

Ovaj primjer prikazuje oblik, a ne univerzalnu politiku. U web zahtjevu spavanje može biti pogrešan kompromis; posao u redu čekanja može biti bolje mjesto za ponovni pokušaj. Još važnije, operaciju s nuspojavama ponovno pokušavajte samo kada je to sigurno.

Idempotentnost je polovica ponovnih pokušaja koja nedostaje

Razmotrite vremensko ograničenje tijekom kreiranja plaćanja ili pošiljke. Ne možete sigurno zaključiti da se ništa nije dogodilo. Ako pružatelj podržava ključeve idempotentnosti, generirajte stabilan ključ za poslovnu operaciju i ponovno ga koristite pri ponovnim pokušajima. Ako ih ne podržava, pohranite vlastito stanje operacije te upotrijebite pretraživanje na strani pružatelja ili usklađivanje gdje je moguće.

Cilj nije samo „pokušati ponovno”. Cilj je „pokušati ponovno bez stvaranja druge radnje u stvarnom svijetu”. Ta razlika štiti i kupce i operativne timove.

Održavajte sinkrone putanje kratkima

Otporan sustav prepoznaje kada može odgoditi rad. Slanje obavijesti, sinkronizacija zapisa, generiranje dokumenta ili osvježavanje udaljenih metapodataka često se ne mora dogoditi unutar zahtjeva koji ih je pokrenuo.

Koristite trajni red čekanja za rad koji može biti asinkron. Najprije postojano pohranite lokalno stanje, stavite integracijski zadatak u red čekanja i prepustite radniku ponovne pokušaje prema jasnoj politici. To smanjuje latenciju zahtjeva i odvaja dostupnost za korisnike od turbulencija nizvodnih ovisnosti.

Redovi čekanja ipak nisu magija. Poslovi trebaju idempotentne obrađivače, smislena ograničenja ponovnih pokušaja, obradu mrtvih poruka ili usporediv tijek rada za neuspjehe te nadzor. Posao koji pokušava zauvijek nije otporan; on je nevidljivi zaostatak koji čeka da postane incident.

Promatrajte granicu, a ne samo iznimku

Kada integracija ne uspije, korisno pitanje obično nije „jesmo li dobili iznimku?” Nego: „koja ovisnost, operacija, klasa statusa i ishod ponovnog pokušaja utječu na proizvod?”

Bilježite strukturirani kontekst oko poziva, pritom čuvajući tajne i osjetljive podatke kupaca izvan zapisnika. Korisna polja često uključuju identifikator korelacije, naziv pružatelja, naziv operacije, trajanje zahtjeva, status odgovora, broj ponovnih pokušaja i sigurno ograničen sažetak pogreške.

• Metrike otkrivaju rastuću latenciju, stope pogrešaka i dubinu reda čekanja prije nego što stignu zahtjevi podršci.
• Praćenje povezuje spor korisnički zahtjev s konkretnim nizvodnim pozivom koji je odgovoran.
• Upozoravanje treba biti usmjereno na smislene simptome, poput trajnih neuspjeha ili rasta rada koji se ne može oporaviti, a ne na svaki pojedinačni ponovni pokušaj.

Također stvorite operativni put za nejasnoće. Ako je udaljena radnja možda uspjela, ali vaša aplikacija to ne zna, učinite to stanje vidljivim i uskladivim. „Nepoznato” je često iskrenije i sigurnije od pogrešnog označavanja radnje kao neuspjele.

Testirajte ugovore i neugodne putanje

Jedinični testovi trebali bi provjeravati mapiranje, klasifikaciju pogrešaka i odluke o ponovnim pokušajima bez stvarnih mrežnih poziva. Integracijski testovi mogu provjeravati sandbox ili kontrolirano okruženje kada postoji, ali ne bi trebali biti jedina zaštita.

Testovi usmjereni na ugovore posebno su vrijedni: proslijedite reprezentativne terete podataka pružatelja u svoj mapper, uključujući polja koja nedostaju i nepoznate statuse. Testirajte vremenska ograničenja, duplicirane isporuke, djelomičan uspjeh i granice paginacije. Sretan put obično je najmanje zanimljiva stvar koju integracijski sloj radi.

U PHP-u transportni kod držite dovoljno izoliranim da testovi mogu zamijeniti lažni gateway. Takav dizajn poboljšava mogućnost testiranja, ali i pojašnjava arhitekturu: domenske usluge ovise o vašem sučelju, dok adapteri pružatelja ovise o HTTP klijentima, SDK-ovima i vjerodajnicama.

Najsmireniji kod upravlja kaosom

Vanjski sustavi će se mijenjati, usporavati i povremeno sami sebi proturječiti. Otporan integracijski sloj ne uklanja tu neizvjesnost. On je zadržava.

Dajte vanjskom svijetu jedan jasno definiran ulaz u svoju aplikaciju. Prevedite njegov rječnik, ograničite njegove načine neuspjeha, sačuvajte dovoljno dokaza za istragu i učinite ponovne pokušaje sigurnima. Vaš poslovni kod postaje jednostavniji ne zato što su integracije postale jednostavne, nego zato što ste njihovoj složenosti dali odgovoran dom.