streamalism.org

1. הקדמה

REST היא ארכיטקטורה חסרת מדינה בה לקוחות יכולים לגשת למשאבים ולנהל אותם בשרת. באופן כללי, שירותי REST משתמשים ב- HTTP כדי לפרסם קבוצת משאבים שהם מנהלים ומספקים ממשק API המאפשר ללקוחות להשיג או לשנות את מצב המשאבים הללו.

במדריך זה נלמד על כמה מהשיטות המומלצות לטיפול בשגיאות REST API, כולל גישות שימושיות לספק למשתמשים מידע רלוונטי, דוגמאות מאתרים רחבי היקף, ויישום קונקרטי באמצעות יישום Spring REST לדוגמא.

2. קודי מצב HTTP

כאשר לקוח מגיש בקשה לשרת HTTP - והשרת מקבל את הבקשה בהצלחה - על השרת להודיע ​​ללקוח אם הבקשה טופלה בהצלחה או לא. HTTP משיג זאת באמצעות חמש קטגוריות של קודי סטטוס:

• 100 רמות (מידע) - השרת מאשר בקשה
• 200 רמות (הצלחה) - השרת השלים את הבקשה כצפוי
• 300 רמות (הפניה מחדש) - הלקוח צריך לבצע פעולות נוספות כדי להשלים את הבקשה
• 400 רמות (שגיאת לקוח) - הלקוח שלח בקשה לא חוקית
• 500 ברמה (שגיאת שרת) - השרת נכשל במילוי בקשה חוקית עקב שגיאה בשרת

בהתבסס על קוד התגובה, לקוח יכול לשער את התוצאה של בקשה מסוימת.

3. טיפול בשגיאות

השלב הראשון בטיפול בשגיאות הוא לספק ללקוח קוד מצב תקין. בנוסף, ייתכן שנצטרך לספק מידע נוסף בגוף התגובה.

3.1. תגובות בסיסיות

הדרך הפשוטה ביותר לטפל בשגיאות היא לעשות זאת להגיב באמצעות קוד סטטוס מתאים.

כמה קודי תגובה נפוצים כוללים:

• 400 בקשה לא טובה - הלקוח שלח בקשה לא חוקית - כגון חסר גוף בקשה או פרמטר נדרש
• 401 לא מורשה - הלקוח נכשל באימות מול השרת
• 403 אסור - לקוח מאומת אך אין לו הרשאה לגשת למשאב המבוקש
• 404 לא נמצא - המשאב המבוקש אינו קיים
• 412 תנאי מוקדם נכשל - תנאי אחד או יותר בשדות כותרת הבקשה הוערכו כ- false
• 500 שגיאת שרת פנימית - אירעה שגיאה כללית בשרת
• שירות 503 לא זמין - השירות המבוקש אינו זמין

אמנם בסיסי, אך קודים אלה מאפשרים ללקוח להבין את אופייה הרחב של השגיאה שהתרחשה. לדוגמא, אנו יודעים אם נקבל שגיאת 403 שאין לנו הרשאות גישה למשאב שביקשנו.

במקרים רבים, עם זאת, עלינו לספק פרטים משלימים בתגובותינו.

500 שגיאות מאותתות על בעיות או חריגים מסוימים בשרת בזמן הטיפול בבקשה. באופן כללי, שגיאה פנימית זו אינה עניינו של הלקוח שלנו.

לפיכך, כדי למזער תגובות מסוג זה ללקוח, עלינו לנסות בשקידה לטפל או לתפוס שגיאות פנימיות ולהגיב באמצעות קודי סטטוס מתאימים אחרים במידת האפשר. לדוגמא, אם חריג מתרחש מכיוון שמשאב מבוקש אינו קיים, עלינו לחשוף זאת כשגיאה 404 ולא כ 500.

זה לא אומר שלעולם אין להחזיר 500, אלא שיש להשתמש בתנאים בלתי צפויים - כמו הפסקת שירות - שמונעים מהשרת לבצע את הבקשה.

3.2. תגובות ברירת מחדל לשגיאות אביב

עקרונות אלה נמצאים כל כך בכל מקום, עד שספרינג קידם אותם במנגנון ברירת המחדל לטיפול בשגיאות.

כדי להדגים, נניח שיש לנו יישום פשוט של Spring REST שמנהל ספרים, עם נקודת קצה לאחזור ספר לפי תעודת הזהות שלו:

תלתל -X GET -H "קבל: יישום / json" // localhost: 8082 / אביב-מנוחה / API / ספר / 1

אם אין ספר עם תעודת הזהות 1, אנו מצפים שהבקר שלנו יזרוק א BookNotFoundException. ביצוע GET בנקודת קצה זו, אנו רואים כי חריג זה נזרק וגוף התגובה הוא:

{"חותמת זמן": "2019-09-16T22: 14: 45.624 + 0000", "status": 500, "error": "שגיאת שרת פנימית", "message": "אין הודעה זמינה", "path": " / api / book / 1 "}

שים לב שמטפל שגיאות ברירת מחדל זה כולל חותמת זמן של מתי התרחשה השגיאה, קוד מצב HTTP, כותרת (ה- שְׁגִיאָה שדה), הודעה (שהיא כברירת מחדל ריקה) ונתיב כתובת האתר שבו אירעה השגיאה.

שדות אלה מספקים ללקוח או מפתח מידע שיעזור לפתור את הבעיה ומהווים גם כמה מהשדות המרכיבים מנגנוני טיפול בשגיאות סטנדרטיים.

בנוסף, שים לב ש- Spring מחזיר אוטומטית קוד מצב HTTP של 500 כאשר שלנו BookNotFoundException נזרק. אף על פי שחלק מממשקי ה- API יחזירו קוד סטטוס 500 או כללי אחרים, כפי שנראה עם ממשקי ה- API של פייסבוק וטוויטר - לכל השגיאות לשם הפשטות, עדיף להשתמש בקוד השגיאה הספציפי ביותר במידת האפשר.

בדוגמה שלנו, אנו יכולים להוסיף a @ControllerAdvice כך שכאשר א BookNotFoundException נזרק, ה- API שלנו מחזיר מעמד של 404 לציון לא נמצא במקום 500 שגיאת שרת פנימית.

3.3. תגובות מפורטות יותר

כפי שניתן לראות בדוגמא האביב שלעיל, לפעמים קוד סטטוס אינו מספיק כדי להציג את פרטי השגיאה. במידת הצורך נוכל להשתמש בגוף התגובה בכדי לספק ללקוח מידע נוסף. כאשר אנו מספקים תגובות מפורטות, עלינו לכלול:

• שגיאה - מזהה ייחודי לשגיאה
• מסר - הודעה קצרה לקריאה אנושית
• פרט - הסבר ארוך יותר על השגיאה

לדוגמה, אם לקוח שולח בקשה עם אישורים שגויים, אנו יכולים לשלוח תגובה 401 עם גוף של:

{"error": "auth-0001", "message": "שם משתמש וסיסמה שגויים", "detail": "ודא ששם המשתמש והסיסמה הכלולים בבקשה נכונים"}

ה שְׁגִיאָה השדה לא אמור להתאים לקוד התגובה. במקום זאת, זה צריך להיות קוד שגיאה הייחודי ליישום שלנו. באופן כללי, אין מוסכמה עבור שְׁגִיאָה שדה, צפה שהוא יהיה ייחודי.

בדרך כלל, שדה זה מכיל רק אלפא-נומריות ותווים מקשרים, כגון מקפים או קו תחתון. לדוגמה, 0001, auth-0001, ו מעבר שגוי למשתמש הם דוגמאות קנוניות לקודי שגיאה.

ה הוֹדָעָה חלק מהגוף נחשב לרוב לייצוג בממשקי משתמש. לכן עלינו לתרגם כותרת זו אם אנו תומכים בינלאומיות. לכן, אם לקוח שולח בקשה עם קבל שפה כותרת המתאימה לצרפתית, כותרת יש לתרגם את הערך לצרפתית.

ה פרט החלק מיועד לשימוש על ידי מפתחי לקוחות ולא על ידי משתמש הקצהולכן התרגום אינו הכרחי.

בנוסף, נוכל גם לספק כתובת אתר - כגון עֶזרָה שדה - שלקוחות יכולים לעקוב אחריהם כדי לגלות מידע נוסף:

{"error": "auth-0001", "message": "שם משתמש וסיסמה שגויים", "פרט": "ודא ששם המשתמש והסיסמה הכלולים בבקשה נכונים", "help": "// דוגמה. com / help / error / auth-0001 "}

לִפְעָמִים, אולי נרצה לדווח על יותר משגיאה אחת לבקשה. במקרה זה, עלינו להחזיר את השגיאות ברשימה:

{"errors": [{"error": "auth-0001", "message": "שם משתמש וסיסמה שגויים", "פרט": "ודא ששם המשתמש והסיסמה הכלולים בבקשה נכונים", "עזרה" : "//example.com/help/error/auth-0001"}, ...]}

וכאשר מתרחשת שגיאה אחת, אנו מגיבים עם רשימה המכילה אלמנט אחד. שים לב כי תגובה עם מספר שגיאות עשויה להיות מורכבת מדי ליישומים פשוטים. במקרים רבים, די בתגובה עם השגיאה הראשונה או המשמעותית ביותר.

3.4. גופי תגובה סטנדרטיים

בעוד שרוב ממשקי ה- API של REST עוקבים אחר מוסכמות דומות, הפרטים בדרך כלל משתנים, כולל שמות השדות והמידע הכלול בגוף התגובה. הבדלים אלה מקשים על ספריות ומסגרות לטפל באופן אחיד בשגיאות.

במאמץ לתקנן טיפול בשגיאות REST API, ה- IETF המציא את RFC 7807, שיוצר סכימה כללית לטיפול בשגיאות.

סכמה זו מורכבת מחמישה חלקים:

1. סוּג - מזהה URI שמסווג את השגיאה
2. כותרת - הודעה קצרה וקריאה על האדם על השגיאה
3. סטָטוּס - קוד תגובת HTTP (אופציונלי)
4. פרט - הסבר הקריא אנושי לטעות
5. למשל - URI המזהה את המופע הספציפי של השגיאה

במקום להשתמש בגוף תגובת השגיאה המותאם אישית שלנו, אנו יכולים להמיר את גופנו ל:

{"type": "/ errors / incorrect-user-pass", "title": "שם משתמש או סיסמה שגויים.", "status": 401, "detail": "האימות נכשל בגלל שם משתמש או סיסמה שגויים.", "מופע": "/ login / log / abc123"}

שים לב שה- סוּג שדה מסווג את סוג השגיאה, בעוד למשל מזהה התרחשות ספציפית של השגיאה באופן דומה למחלקות ואובייקטים, בהתאמה.

באמצעות URI, לקוחות יכולים ללכת בדרכים אלה כדי למצוא מידע נוסף על השגיאה באותו אופן שניתן להשתמש בקישורי HATEOAS לניווט ב- API של REST.

הקפדה על RFC 7807 היא אופציונלית, אך זה יתרון אם רוצים אחידות.

4. דוגמאות

הפרקטיקות שלעיל נפוצות בכל ממשקי API של REST הפופולריים ביותר. אמנם השמות הספציפיים של שדות או פורמטים עשויים להשתנות בין אתרים, הדפוסים הכלליים הם כמעט אוניברסליים.

4.1. טוויטר

לדוגמה, בואו נשלח בקשת GET מבלי לספק את נתוני האימות הנדרשים:

תלתל -X GET //api.twitter.com/1.1/statuses/update.json?include_entities=true

ממשק ה- API של Twitter מגיב עם שגיאה בגוף הבא:

{"שגיאות": [{"קוד": 215, "הודעה": "נתוני אימות רעים." }]}

תגובה זו כוללת רשימה המכילה שגיאה אחת, עם קוד השגיאה וההודעה שלה. במקרה של טוויטר, אין שום הודעה מפורטת ושגיאה כללית - ולא שגיאה 401 ספציפית יותר - משמשת לציון אימות נכשל.

לפעמים קל יותר ליישם קוד סטטוס כללי יותר, כפי שנראה בדוגמת האביב שלנו למטה. זה מאפשר למפתחים לתפוס קבוצות של חריגים ולא להבדיל את קוד הסטטוס שיש להחזיר. אבל במידת האפשר יש להשתמש בקוד הסטטוס הספציפי ביותר.

4.2. פייסבוק

בדומה לטוויטר, גם ה- API של הגרף REST של פייסבוק כולל מידע מפורט בתגובותיו.

לדוגמא, בוא נבצע בקשת POST לאימות באמצעות ממשק ה- API של Facebook Graph:

תלתל -X GET //graph.facebook.com/oauth/access_token?client_id=foo&client_secret=bar&grant_type=baz

אנו מקבלים את השגיאה הבאה:

{"error": {"message": "חסר פרמטר redirect_uri.", "type": "OAuthException", "code": 191, "fbtrace_id": "AWswcVwbcqfgrSgjG80MtqJ"}}

כמו טוויטר, גם פייסבוק משתמשת בשגיאה כללית - ולא בשגיאה ספציפית יותר ברמה של 400 - כדי לציין כישלון. בנוסף להודעה ולקוד מספרי, פייסבוק כוללת גם א סוּג שדה שמסווג את השגיאה ומזהה עקבות (fbtrace_id) המשמש כמזהה תמיכה פנימי.

5. מסקנה

במאמר זה, בחנו כמה מהשיטות המומלצות לטיפול בשגיאות REST API, כולל:

• מתן קודי סטטוס ספציפיים
• כולל מידע נוסף בגופי התגובה
• טיפול בחריגים באופן אחיד

אמנם פרטי הטיפול בשגיאות ישתנו בהתאם ליישום, עקרונות כלליים אלה חלים כמעט על כל ממשקי ה- API של REST ויש לעמוד בהם במידת האפשר.

לא רק שזה מאפשר ללקוחות לטפל בשגיאות בצורה עקבית, אלא זה גם מפשט את הקוד שאנחנו יוצרים בעת יישום REST API.

הקוד שמופיע במאמר זה זמין באתר GitHub.