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:

  1. típus - URI azonosító, amely kategorizálja a hibát
  2. cím - Rövid, ember által olvasható üzenet a hibáról
  3. állapot - A HTTP válaszkód (opcionális)
  4. Részlet - A hiba ember által olvasható magyarázata
  5. 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.