Većina API kvarova ne počinje neispravnim retkom koda. Počinju nejasnim ugovorom, dvosmislenim prijelazom stanja ili operativnom pretpostavkom koja nikada nije zapisana. Do trenutka kada pogreška dosegne klijenta, tim je često duboko u zapisnicima, petljama ponovnih pokušaja i upitima prema bazi podataka—otklanjajući simptome stvorene mnogo ranije tijekom dizajna.

Predvidivi sustavi nisu sustavi koji nikada ne otkazuju. To su sustavi čiji su kvarovi razumljivi, ograničeni i sigurni za obradu. Ta razlika mijenja način dizajniranja pozadinskog sustava: od imenovanja krajnjih točaka i ograničenja baze podataka do Docker konfiguracije i ponašanja pri implementaciji.

Predvidivost je značajka proizvoda

API je obećanje između sustava. Klijenti trebaju znati što zahtjev znači, kako izgleda uspjeh, koje su pogreške moguće i je li ponovni pokušaj siguran. Ako bilo koji od tih odgovora ovisi o skrivenim detaljima implementacije, svaka integracija postaje vježba otklanjanja pogrešaka.

Razmotrite operaciju nalik plaćanju koja stvara narudžbu. Do isteka vremena može doći nakon što je poslužitelj potvrdio narudžbu, ali prije nego što klijent primi odgovor. Ako klijent ponovi običan zahtjev POST, sustav može stvoriti dvije narudžbe. Neposredni problem izgleda kao mrežni problem. Stvarni je problem to što operacija nije dizajnirana da podnese neizvjesnost.

Za operacije koje se mogu ponoviti upotrijebite ključ idempotentnosti i učinite ga dijelom ugovora. Pohranite ključ s rezultatom dovršene operacije, a zatim vratite isti rezultat kada se isti ključ ponovno pošalje.

$key = $request->header('Idempotency-Key');

if (!$key) {
    return response()->json([
        'error' => 'idempotency_key_required'
    ], 400);
}

$existing = OrderRequest::where('key', $key)->first();

if ($existing) {
    return response()->json($existing->response_body, $existing->status_code);
}

Točna implementacija varira, ali načelo ne: ponovni pokušaji ne smiju privremenu neizvjesnost pretvoriti u duplicirane poslovne radnje.

Učinite ugovore eksplicitnima na granicama

Pozadinski kod može ostati fleksibilan interno. Javne granice trebaju biti stroge. Rano validirajte ulaz, jednom ga normalizirajte i vratite dosljedan oblik odgovora. Klijent ne bi trebao zaključivati je li pogreška niz znakova, polje ili djelomično prikazana HTML stranica na temelju toga koji je middleware obradio iznimku.

Korisni odgovor na pogrešku razlikuje neuspjele validacije, neuspjele autentikacije, nedostajuće resurse, sukobe i neočekivane pogreške poslužitelja. Trebao bi izložiti dovoljno informacija da klijent može ispravno reagirati bez otkrivanja stack traceova, SQL fragmenata ili interne topologije.

{
  "error": {
    "code": "email_already_registered",
    "message": "An account already exists for this email.",
    "details": {
      "field": "email"
    }
  }
}

Dosljednost je važnija od domišljatosti. Ako jedna krajnja točka prijavljuje 409 Conflict za duplicirani resurs, dok druga vraća 422 Unprocessable Content, klijenti moraju učiti vaše iznimke umjesto vaših pravila. Odaberite konvencije, dokumentirajte ih i primjenjujte ih u cijelom API-ju.

Neka baza podataka provodi istinu

Provjere na razini aplikacije poboljšavaju korisničko iskustvo, ali nisu dovoljne za ispravnost. Dva zahtjeva mogu proći istu provjeru „postoji li ovaj zapis?” prije nego što bilo koji od njih upiše podatke u bazu. Bez ograničenja baze podataka, uvjet utrke može tiho proizvesti nevaljane podatke.

Ako e-pošta mora biti jedinstvena, stvorite jedinstveno ograničenje. Ako podređeni zapis mora referencirati nadređeni, upotrijebite strani ključ kada odgovara operativnom modelu. Ako vrijednost mora biti prisutna, provedite to stupcem koji ne dopušta null vrijednosti. Baza podataka je konačni autoritet jer vidi istodobne upise iz svakog procesa aplikacije.

To također mijenja obradu neuspjeha. Kršenje jedinstvenosti tretirajte kao uobičajen sukob koji se može dogoditi pri istodobnom radu, a ne kao nemoguću iznimku. Aplikacija može prvo validirati radi prijateljskog odgovora, a zatim prevesti neuspjeh ograničenja baze podataka u istu stabilnu API pogrešku ako dođe do utrke.

Transakcije trebaju štititi poslovnu odluku

Upotrijebite transakciju kada nekoliko upisa predstavlja jednu odluku: rezervirajte zalihe, stvorite narudžbu i zabilježite njezine stavke; ili stvorite račun i dodijelite potrebne uloge. Nemojte koristiti transakcije samo zato što se više upita slučajno nalazi jedan do drugoga.

Neka transakcije budu kratke. Izbjegavajte pozivanje udaljenih usluga, slanje e-pošte ili čekanje na redove dok je transakcija otvorena. Te radnje uvode spore, nepouzdane ovisnosti dok su zaključavanja zadržana. Prvo potvrdite autoritativno stanje, a zatim objavite naknadni rad putem pouzdanog mehanizma primjerenog sustavu.

Dizajnirajte putanje neuspjeha prije sretne putanje

Svaka vanjska ovisnost može postati spora, nedostupna ili nedosljedna. Predvidiva usluga unaprijed odlučuje što se tada događa. Ne uspijeva li zahtjev brzo? Vraća li predmemorirane podatke? Stavlja li se posao u red za kasnije? Može li pozivatelj sigurno ponoviti pokušaj?

Ponovni pokušaji zaslužuju posebnu pažnju. Ponovno pokušavanje svakog neuspjeha može pojačati prekid rada umnažanjem prometa prema već nezdravoj usluzi. Ponovite samo pogreške koje su vjerojatno prolazne, ograničite broj pokušaja, upotrijebite odgodu i postavite vremenska ograničenja. Zahtjev bez vremenskog ograničenja nije otporan; jednostavno je spreman čekati neograničeno dugo.

• Postavite vremenska ograničenja povezivanja i odgovora za odlazne HTTP pozive.
• Ponovite pokušaj samo kada je operacija sigurna ili zaštićena idempotentnošću.
• Upotrijebite ograničene redove i jasno rukovanje neuspjesima za pozadinske poslove.
• Uključite identifikatore korelacije u zapisnike i odgovore gdje je prikladno.
• Vraćajte pogreške koje omogućuju djelovanje umjesto da prisiljavate klijente na nagađanje.

Opservabilnost pripada dizajnu, a ne retrospektivi incidenta. Strukturirani zapisnici trebaju identificirati zahtjev, relevantne identifikatore resursa, ishod i trajanje. Metrike bi trebale omogućiti razlikovanje povećanog prometa od povećanog broja neuspjeha. Praćenje može razjasniti lance ovisnosti, ali čak i skroman sustav ima veliku korist od dosljednih ID-ova zahtjeva i smislenih zapisnika.

Neka ponašanje implementacije bude dosadno

Docker može učiniti lokalna i implementirana okruženja dosljednijima, ali samo ako je konfiguracija promišljena. Slika bi trebala sadržavati aplikaciju i njezine ovisnosti vremena izvođenja. Vrijednosti specifične za okruženje—vjerodajnice baze podataka, URL-ovi usluga, zastavice značajki i postavke zapisivanja—trebaju se ubrizgati tijekom izvođenja, umjesto da se ugrađuju u sliku.

Pokretanje također mora biti predvidivo. Ako spremnik pretpostavlja da je baza podataka spremna samo zato što je proces pokrenut, implementacije će povremeno neuspjeti. Spremnost nije isto što i stvaranje procesa. Izgradite eksplicitno ponašanje ponovnih pokušaja oko ovisnosti pri pokretanju, s ograničenjima i korisnim zapisnicima, te osigurajte da aplikacija može jasno neuspjeti kada ne može postati spremna.

Migracije sheme zahtijevaju istu disciplinu. Implementacija ne bi trebala pretpostavljati da sve pokrenute instance aplikacije mijenjaju verzije odjednom. Dajte prednost kompatibilnim promjenama: dodajte stupac koji dopušta null prije nego što ga učinite obaveznim, implementirajte kod koji može rukovati obama oblicima, po potrebi popunite postojeće podatke, a zatim u kasnijoj promjeni provedite strože ograničenje.

Optimizirajte pitanja koja postavljate

Rad na performansama postaje mirniji kada počne s ponašanjem, a ne nagađanjem. Zapitajte se koji je zahtjev spor, koji je upit skup, koja ovisnost dominira latencijom i je li taj rad potreban. Zatim izmjerite odgovor u reprezentativnom okruženju.

Uobičajene neučinkovitosti pozadinskog sustava rijetko su egzotične: neograničeni skupovi rezultata, ponovljeni upiti u petljama, nedostajući indeksi za stvarne obrasce pristupa, nepotrebna serijalizacija i udaljeni pozivi na kritičnim putanjama zahtjeva. Paginacija, selektivna polja, eager loading gdje je prikladno i indeksi usklađeni sa stvarnim upitima često donose veću vrijednost od preuranjenog predmemoriranja.

Predmemoriranje je korisno kada su zastarjeli podaci prihvatljivi i kada je poništavanje predmemorije razumljivo. Opasno je kada se doda kao općeniti odgovor na spor upit koji nije ispitan. Predmemorija može sakriti problem dizajna, a pritom dodati drugi izvor istine.

Arhitekturirajte za sljedeću osobu koja čita kod

Održivost je predvidivost tijekom vremena. Jasna imena, mali moduli, stabilne granice i usmjereni testovi smanjuju broj pretpostavki potrebnih za sigurnu promjenu sustava. Cilj nije maksimalna apstrakcija. Cilj je kod u kojem sljedeći inženjer može pronaći poslovno pravilo, razumjeti njegove ulaze i vidjeti kako se obrađuje neuspjeh.

Prestanite tretirati otklanjanje pogrešaka kao primarni odgovor na nepouzdan softver. Otklanjanje pogrešaka uvijek će biti važno, ali treba biti posljednji alat, a ne zadani operativni model. Kada su ugovori eksplicitni, integritet podataka proveden, neuspjesi dizajnirani, a implementacije namjerno dosadne, API postaje lakši za upravljanje i lakši za povjerenje. To je ono što dobra arhitektura donosi: manje misterija, brže odluke i sustav koji se ponaša kao da misli ono što govori.