streamalism.org

1. Úvod

REST je bezstavová architektúra, v ktorej môžu klienti pristupovať k prostriedkom na serveri a manipulovať s nimi. Služby REST vo všeobecnosti využívajú protokol HTTP na inzerovanie množiny prostriedkov, ktoré spravujú, a na poskytovanie rozhrania API, ktoré umožňuje klientom získať alebo zmeniť stav týchto prostriedkov.

V tomto výučbe sa dozvieme o niektorých najlepších postupoch pri riešení chýb rozhrania REST API, vrátane užitočných prístupov k poskytovaniu relevantných informácií používateľom, príkladov z rozsiahlych webových stránok a konkrétnej implementácie pomocou príkladnej aplikácie Spring REST.

2. Stavové kódy HTTP

Keď klient zadá požiadavku na server HTTP - a server ju úspešne prijme - server musí informovať klienta, či bola požiadavka úspešne vybavená alebo nie. HTTP to dosahuje piatimi kategóriami stavových kódov:

• 100-úrovňový (informačný) - server potvrdzuje požiadavku
• 200 úrovní (Úspech) - Server dokončil požiadavku podľa očakávania
• 300 úrovní (presmerovanie) - klient musí na dokončenie žiadosti vykonať ďalšie kroky
• 400 úrovní (chyba klienta) - klient poslal neplatnú žiadosť
• 500 úrovní (chyba servera) - serveru sa nepodarilo splniť platnú požiadavku z dôvodu chyby servera

Na základe kódu odpovede môže klient predpokladať výsledok konkrétnej požiadavky.

3. Riešenie chýb

Prvým krokom pri riešení chýb je poskytnúť klientovi správny stavový kód. Možno budeme musieť poskytnúť viac informácií v tele odpovede.

3.1. Základné odpovede

Najjednoduchší spôsob, ako chyby spracovať, je odpovedať príslušným stavovým kódom.

Niektoré bežné kódy odpovedí zahŕňajú:

• 400 Chybná požiadavka - klient poslal neplatnú žiadosť - napríklad chýbajúci požadovaný text žiadosti alebo parameter
• 401 Neoprávnené - klientovi sa nepodarilo overiť totožnosť so serverom
• 403 Zakázané - klient je autentifikovaný, ale nemá povolenie na prístup k požadovanému prostriedku
• 404 Nenašiel sa - požadovaný zdroj neexistuje
• 412 Podmienka zlyhala - Jedna alebo viac podmienok v poliach hlavičky požiadavky vyhodnotených ako nepravdivé
• 500 Interná chyba servera - na serveri sa vyskytla všeobecná chyba
• 503 Služba nie je k dispozícii - požadovaná služba nie je k dispozícii

Aj keď sú tieto kódy základné, umožňujú klientovi porozumieť širokej podstate chyby, ku ktorej došlo. Napríklad vieme, že ak dostaneme chybu 403, chýbajú nám povolenia na prístup k požadovanému prostriedku.

V mnohých prípadoch však musíme vo svojich odpovediach uviesť ďalšie podrobnosti.

500 chýb signalizuje, že na serveri došlo počas vybavovania požiadavky k niektorým problémom alebo výnimkám. Táto interná chyba spravidla nie je vecou nášho klienta.

Preto, aby sa minimalizoval tento druh odpovedí na klienta, mali by sme sa usilovne snažiť zvládnuť alebo zachytiť vnútorné chyby a všade, kde je to možné, odpovedať ďalšími vhodnými stavovými kódmi. Napríklad, ak dôjde k výnimke, pretože požadovaný zdroj neexistuje, mali by sme to vystaviť ako chybu 404 a nie 500.

To neznamená, že 500 by sa nikdy nemalo vracať, malo by sa používať iba v prípade neočakávaných stavov, ako je napríklad výpadok služby, ktoré serveru bránia vo vykonaní požiadavky.

3.2. Predvolené odpovede na jarné chyby

Tieto princípy sú také všadeprítomné, že Spring ich kodifikoval vo svojom predvolenom mechanizme spracovania chýb.

Na demonštráciu predpokladajme, že máme jednoduchú aplikáciu Spring REST, ktorá spravuje knihy, s koncovým bodom na načítanie knihy podľa jej ID:

curl -X GET -H "Prijať: application / json" // localhost: 8082 / spring-rest / api / book / 1

Ak neexistuje kniha s ID 1, očakávame, že náš kontrolór hodí a BookNotFoundException. Vykonaním GET v tomto koncovom bode vidíme, že táto výnimka bola vyvolaná a telo odpovede je:

{"timestamp": "2019-09-16T22: 14: 45.624 + 0000", "status": 500, "error": "Interná chyba servera", "message": "Nie je k dispozícii žiadna správa", "cesta": " / api / kniha / 1 "}

Upozorňujeme, že tento predvolený obslužný program chýb obsahuje časovú značku, kedy k chybe došlo, stavový kód HTTP, nadpis ( chyba pole), správa (ktorá je v predvolenom nastavení prázdna) a cesta URL, kde sa vyskytla chyba.

Tieto polia poskytujú klientovi alebo vývojárovi informácie, ktoré mu pomôžu problém vyriešiť a tiež tvoria niekoľko polí, ktoré tvoria štandardné mechanizmy spracovania chýb.

Ďalej nezabudnite, že Spring automaticky vráti stavový kód HTTP 500, keď je náš BookNotFoundException je hodená. Aj keď niektoré API vrátia 500 stavových kódov alebo iné všeobecné, ako uvidíme pri API na Facebooku a Twitteri - kvôli zjednodušeniu uvádzame všetky chyby, najlepšie je použiť čo najkonkrétnejší kód chyby.

V našom príklade môžeme pridať a @ControllerAdvice aby keď a BookNotFoundException je vyhodené, naše API vracia stav 404, ktorý označuje Nenájdené namiesto 500 Interná chyba servera.

3.3. Podrobnejšie odpovede

Ako je vidieť vo vyššie uvedenom jarnom príklade, niekedy stavový kód nestačí na to, aby ukázal špecifiká chyby. V prípade potreby môžeme pomocou tela odpovede poskytnúť klientovi ďalšie informácie. Pri poskytovaní podrobných odpovedí by sme mali zahrnúť:

• Chyba - jedinečný identifikátor chyby
• Správa - krátka správa čitateľná pre človeka
• Detail - zdĺhavejšie vysvetlenie chyby

Napríklad, ak klient pošle žiadosť s nesprávnymi povereniami, môžeme poslať odpoveď 401 s textom:

{"error": "auth-0001", "message": "Nesprávne používateľské meno a heslo", "detail": "Uistite sa, že používateľské meno a heslo uvedené v žiadosti sú správne"}

The chyba pole by sa nemalo zhodovať s kódom odpovede. Namiesto toho by to mal byť chybový kód jedinečný pre našu aplikáciu. Všeobecne neexistuje dohovor pre chyba očakávajte, že bude jedinečný.

Toto pole zvyčajne obsahuje iba alfanumerické znaky a spojovacie znaky, napríklad pomlčky alebo podčiarkovníky. Napríklad, 0001, auth-0001a nesprávny používateľský preukaz sú kanonické príklady chybových kódov.

The správa časť tela sa zvyčajne považuje za prezentovateľnú na používateľských rozhraniach. Preto by sme mali tento názov preložiť, ak podporujeme internacionalizáciu. Takže ak klient pošle žiadosť s Prijať jazyk hlavička zodpovedajúca francúzštine, titul hodnota by mala byť preložená do francúzštiny.

The detail časť je určená na použitie vývojármi klientov, a nie koncovým používateľom, takže preklad nie je potrebný.

Ďalej by sme mohli poskytnúť aj adresu URL - napríklad Pomoc pole - podľa ktorého môžu klienti nájsť ďalšie informácie:

{"error": "auth-0001", "message": "Nesprávne používateľské meno a heslo", "detail": "Uistite sa, že používateľské meno a heslo uvedené v žiadosti sú správne", "help": "// príklad. com / help / error / auth-0001 "}

Niekedy možno budeme chcieť nahlásiť viac ako jednu chybu v prípade žiadosti. V takom prípade by sme mali vrátiť chyby v zozname:

{"errors": [{"error": "auth-0001", "message": "Nesprávne používateľské meno a heslo", "detail": "Uistite sa, že používateľské meno a heslo uvedené v žiadosti sú správne", "help" : "//example.com/help/error/auth-0001"}, ...]}

A keď sa vyskytne jedna chyba, odpovieme zoznamom obsahujúcim jeden prvok. Upozorňujeme, že odpoveď s viacerými chybami môže byť pre jednoduché aplikácie príliš zložitá. V mnohých prípadoch postačuje odpoveď s prvou alebo najvýznamnejšou chybou.

3.4. Štandardizované orgány reakcie

Zatiaľ čo väčšina rozhraní REST API dodržiava podobné konvencie, špecifiká sa zvyčajne líšia, vrátane názvov polí a informácií zahrnutých v tele odpovede. Tieto rozdiely sťažujú knižniciam a rámcom jednotné spracovanie chýb.

V snahe štandardizovať spracovanie chýb REST API IETF vymyslel RFC 7807, ktorý vytvára všeobecnú schému spracovania chýb.

Táto schéma sa skladá z piatich častí:

1. typu - Identifikátor URI, ktorý kategorizuje chybu
2. titul - Krátka, človekom čitateľná správa o chybe
3. postavenie - Kód odpovede HTTP (voliteľný)
4. detail - Ľudsky čitateľné vysvetlenie chyby
5. inštancia - URI, ktorý identifikuje konkrétny výskyt chyby

Namiesto použitia nášho vlastného tela na reakciu na chyby môžeme naše telo previesť na:

{"type": "/ errors / incorrect-user-pass", "title": "Nesprávne používateľské meno alebo heslo.", "status": 401, "detail": "Overenie zlyhalo z dôvodu nesprávneho používateľského mena alebo hesla.", "instance": "/ login / log / abc123"}

Všimnite si, že typu pole kategorizuje typ chyby, zatiaľ čo inštancia identifikuje konkrétny výskyt chyby podobným spôsobom ako triedy a objekty.

Pomocou identifikátorov URI môžu klienti sledovať tieto cesty a nájsť ďalšie informácie o chybe rovnakým spôsobom, akým sa dajú odkazy HATEOAS použiť na navigáciu v rozhraní REST API.

Dodržiavanie RFC 7807 je voliteľné, je však výhodné, ak sa vyžaduje jednotnosť.

4. Príklady

Vyššie uvedené postupy sú bežné v niektorých najpopulárnejších rozhraniach REST API. Aj keď sa konkrétne názvy polí alebo formátov môžu u jednotlivých stránok líšiť, všeobecné vzorce sú takmer univerzálne.

4.1. Twitter

Napríklad pošleme žiadosť GET bez zadania požadovaných autentifikačných údajov:

curl -X ZÍSKAŤ //api.twitter.com/1.1/statuses/update.json?include_entities=true

Rozhranie Twitter API reaguje s chybou s týmto textom:

{"errors": [{"code": 215, "message": "Bad Authentication data." }]}

Táto odpoveď obsahuje zoznam obsahujúci jednu chybu s jej chybovým kódom a správou. V prípade Twitteru nie je k dispozícii žiadna podrobná správa a na označenie zlyhania autentifikácie sa používa všeobecná chyba - nie konkrétnejšia chyba 401.

Niekedy je jednoduchšie implementovať všeobecnejší stavový kód, ako uvidíme v našom jarnom príklade nižšie. Umožňuje vývojárom zachytiť skupiny výnimiek a nerozlišovať stavový kód, ktorý by sa mal vrátiť. Ak je to možné, mal by sa použiť najkonkrétnejší stavový kód.

4.2. Facebook

Podobne ako Twitter, aj Graph Graph REST API Facebooku obsahuje vo svojich odpovediach podrobné informácie.

Poďme napríklad vykonať požiadavku POST na autentizáciu pomocou rozhrania Facebook Graph API:

curl -X ZÍSKAŤ //graph.facebook.com/oauth/access_token?client_id=foo&client_secret=bar&grant_type=baz

Dostávame nasledujúcu chybu:

{"error": {"message": "Chýba parameter redirect_uri.", "type": "OAuthException", "code": 191, "fbtrace_id": "AWswcVwbcqfgrSgjG80MtqJ"}}

Rovnako ako Twitter, aj Facebook používa na označenie zlyhania skôr všeobecnú chybu ako konkrétnejšiu chybu na úrovni 400. Okrem správy a číselného kódu obsahuje Facebook aj a typu pole, ktoré kategorizuje chybu a ID sledovania (fbtrace_id), ktorý slúži ako interný identifikátor podpory.

5. Záver

V tomto článku sme preskúmali niektoré z najlepších postupov pri spracovaní chýb rozhrania REST API, vrátane:

• Poskytnutie konkrétnych stavových kódov
• Vrátane ďalších informácií do orgánov reakcie
• Vybavovanie výnimiek jednotným spôsobom

Aj keď sa podrobnosti riešenia chýb budú líšiť podľa aplikácie, tieto všeobecné zásady platia pre takmer všetky rozhrania REST API a mali by sa dodržiavať, ak je to možné.

Toto nielen umožňuje klientom konzistentne spracovávať chyby, ale tiež zjednodušuje kód, ktorý vytvoríme pri implementácii rozhrania REST API.

Kód uvedený v tomto článku je k dispozícii na stránkach GitHub.