A REST API hibakezelésének bevált módszerei
1. Bemutatkozás
A REST egy hontalan architektúra, amelyben az ügyfelek hozzáférhetnek és manipulálhatják a szerver erőforrásait. Általában a REST szolgáltatások a HTTP-t használják az általuk kezelt erőforrások halmazának reklámozására, és olyan API-t biztosítanak, amely lehetővé teszi az ügyfeleknek, hogy megszerezzék vagy megváltoztassák ezen erőforrások állapotát.
Ebben az oktatóanyagban megismerkedhetünk a REST API-hibák kezelésének legjobb gyakorlataival, beleértve a hasznos információkkal kapcsolatos megközelítéseket, amelyek a felhasználók számára releváns információkkal szolgálnak, a nagyszabású webhelyekről szóló példákat, valamint a Spring REST példa egyik alkalmazásának konkrét megvalósítását.
2. HTTP állapotkódok
Amikor az ügyfél kérést küld egy HTTP szerverhez - és a szerver sikeresen fogadja a kérést -, a szervernek értesítenie kell az ügyfelet, ha a kérést sikeresen kezelték vagy sem. A HTTP ezt öt állapotkód-kategóriával valósítja meg:
- 100 szintes (Információs) - A szerver nyugtázza a kérést
- 200 szint (siker) - A kiszolgáló a várakozásoknak megfelelően teljesítette a kérést
- 300 szint (átirányítás) - Az ügyfélnek további műveleteket kell végrehajtania a kérelem teljesítéséhez
- 400 szint (kliens hiba) - Az ügyfél érvénytelen kérést küldött
- 500-szintű (szerverhiba) - A szerver nem teljesítette az érvényes kérést a szerver hibája miatt
A válaszkód alapján az ügyfél feltételezheti egy adott kérés eredményét.
3. A hibák kezelése
A hibák kezelésének első lépése az, hogy az ügyfélnek megfelelő státuskódot kell megadnia. Lehetséges, hogy további információkat kell megadnunk a válaszadó testületben.
3.1. Alapvető válaszok
A hibák kezelésének legegyszerűbb módja az megfelelő állapotkóddal válaszoljon.
Néhány általános válaszkód a következőket tartalmazza:
- 400 hibás kérés - az ügyfél érvénytelen kérést küldött - például hiányzott a szükséges kérelem törzs vagy paraméter
- 401 Jogosulatlan - Az ügyfél nem tudta hitelesíteni magát a szerverrel
- 403 Tiltott - Az ügyfél hitelesített, de nincs engedélye a kért erőforrás elérésére
- 404 nem található - a kért erőforrás nem létezik
- 412 Előfeltétel sikertelen - A kérés fejlécének mezőiben egy vagy több feltétel hamisnak minősül
- 500 belső kiszolgáló hiba - általános hiba történt a szerveren
- 503 Szolgáltatás nem érhető el - A kért szolgáltatás nem érhető el
Bár alapvetőek, ezek a kódok lehetővé teszik az ügyfél számára, hogy megértse a történt hiba tág természetét. Például tudjuk, ha 403-as hibát kapunk, hogy nincs engedélyünk a kért erőforráshoz való hozzáféréshez.
Sok esetben azonban kiegészítő részleteket kell megadnunk válaszainkban.
500 hiba jelzi, hogy néhány probléma vagy kivétel történt a kiszolgálón egy kérés kezelése közben. Ez a belső hiba általában nem az ügyfelünk dolga.
Ezért az ügyfélre adott ilyen jellegű válaszok minimalizálása érdekében szorgalmasan kell megkísérelnünk kezelni vagy elkapni a belső hibákat, és lehetőség szerint más megfelelő állapotkódokkal válaszolni. Például, ha kivétel következik be, mert a kért erőforrás nem létezik, akkor ezt inkább 404-es, mint 500-as hibának kell kitenni.
Ez nem azt jelenti, hogy az 500-at soha nem szabad visszaküldeni, csak azt, hogy váratlan körülmények esetén - például szolgáltatáskimaradás esetén - fel kell használni, amelyek megakadályozzák a szervert a kérés végrehajtásában.
3.2. Alapértelmezett tavaszi hibaválaszok
Ezek az elvek annyira mindenütt jelen vannak, hogy a Spring az alapértelmezett hibakezelési mechanizmusban kodifikálta őket.
Tegyük fel, hogy van egy egyszerű tavaszi REST alkalmazásunk, amely könyveket kezel, és amelynek végpontja egy könyv beolvasása az azonosítója alapján:
curl -X GET -H "Elfogadás: application / json" // localhost: 8082 / spring-rest / api / book / 1
Ha nincs 1-es azonosítójú könyv, akkor arra számítunk, hogy kontrollerünk a-t dob BookNotFoundException. GET végrehajtása ezen a végponton azt látja, hogy ezt a kivételt elvetették, és a válasz test:
{"időbélyeg": "2019-09-16T22: 14: 45.624 + 0000", "status": 500, "error": "Belső szerverhiba", "message": "Nincs elérhető üzenet", "path": " / api / book / 1 "}
Ne feledje, hogy ez az alapértelmezett hibakezelő tartalmaz egy időbélyeget, amikor a hiba bekövetkezett, a HTTP állapotkódot, a címet (a hiba mező), egy üzenet (amely alapértelmezés szerint üres), és az URL elérési útja, ahol a hiba bekövetkezett.
Ezek a mezők információkat nyújtanak az ügyfélnek vagy a fejlesztőnek a probléma elhárításához és néhány olyan mezőt is alkot, amelyek a szokásos hibakezelési mechanizmusokat alkotják.
Ezenkívül vegye figyelembe, hogy a Spring automatikusan 500-as HTTP-állapotkódot ad vissza, amikor a BookNotFoundException dobják. Bár egyes API-k 500 állapotkódot vagy más általános kódot adnak vissza, amint azt a Facebook és a Twitter API-kkal láthatjuk - az egyszerűség kedvéért minden hiba miatt, a legjobb, ha lehetséges, a legspecifikusabb hibakódot használni.
Példánkban hozzáadhatunk a @ControllerAdvice hogy amikor a BookNotFoundException dobják, API-junk visszaadja a 404 státuszt, hogy jelölje Nem található 500 helyett Belső Szerverhiba.
3.3. Részletesebb válaszok
Amint a fenti tavaszi példában látható, néha egy állapotkód nem elegendő a hiba sajátosságainak bemutatásához. Ha szükséges, használhatjuk a válasz törzsét, hogy további információkat nyújtsunk az ügyfélnek. A részletes válaszok megadásakor a következőket kell tartalmaznunk:
- Hiba - A hiba egyedi azonosítója
- Üzenet - Rövid, ember által olvasható üzenet
- Részlet - A hiba hosszabb magyarázata
Például, ha egy ügyfél hibás hitelesítő adatokkal küld kérést, akkor a 401-es választ a következő törzsből küldhetjük:
{"error": "auth-0001", "message": "Helytelen felhasználónév és jelszó", "detail": "Győződjön meg arról, hogy a kérelemben szereplő felhasználónév és jelszó helyes"}
A hiba mezőnek nem kell egyeznie a válaszkóddal. Ehelyett az alkalmazásunknak megfelelő hibakódnak kell lennie. Általában nincs egyezmény a hiba elvárja, hogy egyedi legyen.
Ez a mező általában csak alfanumerikus számokat és összekötő karaktereket tartalmaz, például kötőjeleket vagy aláhúzásokat. Például, 0001, auth-0001, és helytelen-user-pass kanonikus példák a hibakódokra.
A üzenet A test egy részét általában a felhasználói felületeken tekinthetjük láthatónak. Ezért ezt a címet le kell fordítanunk, ha támogatjuk a nemzetközivé válást. Tehát, ha az ügyfél kérést küld egy Elfogadás-Nyelv a francia nyelvnek megfelelő fejléc, a cím értéket le kell fordítani francia nyelvre.
A Részlet része az ügyfelek fejlesztői, és nem a végfelhasználó számára készült, ezért a fordítás nem szükséges.
Ezenkívül megadhatunk egy URL-t is - például a Segítség mező - amelyet az ügyfelek követhetnek további információk felfedezéséhez:
{"error": "auth-0001", "message": "Helytelen felhasználónév és jelszó", "detail": "Győződjön meg arról, hogy a kérelemben szereplő felhasználónév és jelszó helyes", "help": "// példa. com / help / error / auth-0001 "}
Néha, kérhetünk egynél több hibát is egy kéréshez. Ebben az esetben vissza kell adnunk a hibákat egy listában:
{"hibák": [{"hiba": "auth-0001", "üzenet": "Helytelen felhasználónév és jelszó", "részletek": "Győződjön meg arról, hogy a kérelemben szereplő felhasználónév és jelszó helyes", "help" : "//pelda.com/segits/hiba/auth-0001"}, ...]}
És amikor egyetlen hiba történik, akkor egy elemet tartalmazó listával válaszolunk. Vegye figyelembe, hogy a több hibával történő válaszadás túl bonyolult lehet az egyszerű alkalmazásokhoz. Sok esetben elegendő az első vagy a legjelentősebb hibával reagálni.
3.4. Standardizált válaszadó testületek
Míg a legtöbb REST API hasonló konvenciót követ, a sajátosságok általában eltérnek, beleértve a mezők nevét és a válasz testében szereplő információkat. Ezek a különbségek megnehezítik a könyvtárak és a keretrendszerek számára a hibák egységes kezelését.
A REST API hibakezelésének egységesítése érdekében az IETF kidolgozta az RFC 7807-et, amely általános hibaelhárítási sémát hoz létre.
Ez a séma öt részből áll:
- típus - URI azonosító, amely kategorizálja a hibát
- cím - Rövid, ember által olvasható üzenet a hibáról
- állapot - A HTTP válaszkód (opcionális)
- Részlet - A hiba ember által olvasható magyarázata
- példa - URI, amely azonosítja a hiba konkrét előfordulását
Ahelyett, hogy egyedi hibaválasz-testünket használnánk, a következőket alakíthatjuk át:
{"type": "/ hibák / helytelen-user-pass", "title": "Helytelen felhasználónév vagy jelszó.", "status": 401, "detail": "A hitelesítés nem megfelelő felhasználói név vagy jelszó miatt sikertelen.", "példány": "/ login / log / abc123"}
Vegye figyelembe, hogy a típus mező a hiba típusát kategorizálja, míg a példa osztályokhoz és objektumokhoz hasonló módon azonosítja a hiba meghatározott előfordulását.
Az URI-k használatával az ügyfelek ezeket az útvonalakat követve további információkat találhatnak a hibáról ugyanúgy, mint a HATEOAS hivatkozások használhatók a REST API navigálásában.
Az RFC 7807 betartása opcionális, de előnyös, ha egységességre van szükség.
4. Példák
A fenti gyakorlatok elterjedtek a legnépszerűbb REST API-kban. Míg a mezők vagy formátumok megnevezése webhelyenként változhat, az általános minták szinte univerzálisak.
4.1. Twitter
Küldjünk például egy GET kérést a szükséges hitelesítési adatok megadása nélkül:
curl -X GET //api.twitter.com/1.1/statuses/update.json?include_entities=true
A Twitter API hibával válaszol a következő törzsre:
{"hibák": [{"code": 215, "message": "Rossz hitelesítési adatok". }]}
Ez a válasz egy hibát tartalmazó listát tartalmaz, annak hibakódjával és üzenetével. A Twitter esetében nincs részletes üzenet, és a hitelesítés sikertelenségének jelzésére általános hibát használnak, nem pedig egy konkrétabb 401-es hibát.
Néha egy általánosabb állapotkódot könnyebb megvalósítani, amint azt az alábbi tavaszi példánkban láthatjuk. Lehetővé teszi a fejlesztők számára, hogy kivételeket csoportosítsanak, és ne különböztessék meg a visszaadandó állapotkódot. Ha lehetséges, a legkonkrétabb állapotkódot kell használni.
4.2. Facebook
A Twitterhez hasonlóan a Facebook Graph REST API is részletes információkat tartalmaz válaszaiban.
Végezzünk például egy POST kérést a Facebook Graph API-val történő hitelesítéshez:
curl -X GET //graph.facebook.com/oauth/access_token?client_id=foo&client_secret=bar&grant_type=baz
A következő hibát kapjuk:
{"error": {"message": "Hiányzik a redirect_uri paraméter.", "type": "OAuthException", "code": 191, "fbtrace_id": "AWswcVwbcqfgrSgjG80MtqJ"}}
A Twitterhez hasonlóan a Facebook is általános hibát használ, nem pedig egy specifikusabb 400-as hibát - a hiba jelzésére. Az üzenet és a számkód mellett a Facebook tartalmaz még egy típus mező, amely kategorizálja a hibát és a nyomkövetési azonosítót (fbtrace_id), amely belső támogatási azonosítóként működik.
5. Következtetés
Ebben a cikkben megvizsgáltuk a REST API hibakezelésének néhány bevált gyakorlatát, többek között:
- Konkrét állapotkódok megadása
- Több információ beillesztése a reagálási szervekbe
- A kivételek egységes kezelése
Míg a hibakezelés részletei alkalmazásonként változnak, ezek az általános elvek szinte az összes REST API-ra vonatkoznak, és lehetőség szerint be kell tartani őket.
Ez nem csak lehetővé teszi az ügyfelek számára, hogy a hibákat következetesen kezeljék, hanem egyszerűsíti a REST API megvalósításakor létrehozott kódot is.
A cikkben hivatkozott kód elérhető a GitHubon.