כדי לספק חוויית משתמש עקבית יותר, כדאי לפרש שגיאות ולהגיב להן באופן יזום. לא משנה אם אתם מפתחים תהליכי עבודה אוטומטיים בענן או מתקשרים עם ממשקי API מרוחקים, ספריות הלקוח של Rust מספקות דרכים לטפל בשגיאות בצורה חלקה. במאמר הזה מוסבר איך:
- טיפול בשגיאות: בודקים את סוגי השגיאות ומפצלים את הלוגיקה של האפליקציה לפי קודי הסטטוס של השירות. לדוגמה, יוצרים משאב חסר כשנתקלים בשגיאת
NotFound. - בדיקת פרטי השגיאה: חילוץ פרטי שגיאה עשירים – כמו הפרות של שדות בקשות שגויות או כשלים במכסות – משירותי Google Cloud כדי לפתור בעיות ב-API ולהתאים את ההתנהגות בזמן הריצה.
- פתרון שגיאות קישור: מפרשים ופותרים שגיאות קישור של HTTP בצד הלקוח שנגרמות בגלל שדות בקשה לא חוקיים או חסרים, כדי לוודא שהבקשות מגיעות לשירות בצורה חלקה.
דרישות מוקדמות
כדי להדגים טיפול בשגיאות, במסמך הזה נשתמש בשירות Secret Manager וב-Cloud Natural Language API. כדי להריץ את הדוגמאות, קודם צריך:
- מפעילים את שירות Secret Manager.
- הפעל את Cloud Natural Language API.
- מגדירים אימות.
יחסי תלות
כדי להוסיף את יחסי התלות הנדרשים לקובץ Cargo.toml, משתמשים בפקודה הבאה:
cargo add google-cloud-secretmanager-v1 google-cloud-gax crc32c google-cloud-language-v2
טיפול בשגיאות
ספריות הלקוח של Rust מאפשרות לכם להציג שגיאות ולהגיב להן. לדוגמה, אתם יכולים להשתמש בזיהוי שגיאות כדי להסתעף להתנהגות אחרת. דפוס נפוץ בשירותי ענן הוא להשתמש במשאב כאילו המאגר שלו קיים, וליצור את המאגר רק אם נתקלים בשגיאה. אם הקונטיינר בדרך כלל קיים, הגישה הזו יעילה יותר מאשר בדיקה אם הקונטיינר קיים לפני שליחת הבקשה.
בדוגמה הבאה, הפונקציה תופסת את השגיאה כשמעדכנים סוד ב-Secret Manager, ויוצרת את הסוד אם הוא לא קיים.
מנסים ליצור גרסה חדשה של הסוד:
אם הפעולה
update_attemptמצליחה, מדפיסים את התוצאה המוצלחת ומחזירים:אם
update_attemptנכשל, צריך להבין מה הסיבה לכך. יכולות להיות הרבה סיבות לכך שהבקשה נכשלה, כמו ניתוק בחיבור או שגיאה באסימוני האימות. מדיניות של ניסיונות חוזרים יכולה לטפל ברוב השגיאות האלה. מחפשים שגיאות שהשירות החזיר:מחפשים שגיאה שמתאימה לסוד חסר:
אם נתקלתם בשגיאה "לא נמצא" (
Code::NotFound), נסו ליצור את הסוד:מנסים להוסיף שוב את גרסת הסוד. הפעם, אם משהו נכשל, מוחזרת שגיאה:
דוגמת קוד: פונקציה ראשית (sample)
הקוד המלא של הדוגמה הזו מחולק לשלושה חלקים: פונקציית התזמור הראשית (sample), ואחריה שתי פונקציות העזר שלה (update_attempt ו-create_secret).
הפונקציה sample מנסה להוסיף גרסה חדשה לסוד. היא תופסת את השגיאה שהלקוח מחזיר ובודקת אם מדובר בשגיאת Code::NotFound. אם הסוד לא נמצא, הפונקציה יוצרת את הסוד שהיה חסר בהתחלה ומנסה שוב לבצע את העדכון.
דוגמת קוד: שיטת עזר (update_attempt)
השיטה המסייעת update_attempt מנסה להוסיף גרסה סודית, ומחשבת את סיכום הביקורת (checksum) של CRC32c של נתוני המטען הייעודי (payload):
דוגמת קוד: שיטת עזר (create_secret)
שיטת העזר create_secret יוצרת סוד חסר ומגדירה מדיניות ניסיון חוזר בהתאמה אישית:
בדיקת פרטי השגיאה
בחלק משירותי Google Cloud יש פרטי שגיאה נוספים כשבקשות נכשלות.
כדי לעזור בפתרון בעיות, ספריות הלקוח של Rust כוללות את הפרטים האלה כשמעצבים שגיאות באמצעות std::fmt::Display. אתם יכולים לבדוק את הפרטים האלה ולשנות את אופן הפעולה של האפליקציה בהתאם.
רק שגיאות שהוחזרו על ידי השירות מכילות מידע מפורט. ספריות הלקוח מחזירות טיפוסים בני מנייה (enum) מסוג StatusDetails עם הסוגים השונים של פרטי השגיאות.
פרטי השגיאה בחילוץ
בדוגמה הזו נשלחת בכוונה בקשה שגויה אל Cloud Natural Language API, ונבדקת השגיאה שמתקבלת.
יוצרים לקוח:
שולחים בקשה (בדוגמה הזו חסר שדה מפתח):
מחלצים את השגיאה מהתוצאה באמצעות פונקציות Rust רגילות. סוג השגיאה מדפיס את כל פרטי השגיאה בצורה קריאה לאנשים:
הפלט אמור להיראות כך:
request failed with error Error {
kind: Service {
status_code: Some(
400,
),
headers: Some(
{
"vary": "X-Origin",
"vary": "Referer",
"vary": "Origin,Accept-Encoding",
"content-type": "application/json; charset=UTF-8",
"date": "Sat, 24 May 2025 17:19:49 GMT",
"server": "scaffolding on HTTPServer2",
"x-xss-protection": "0",
"x-frame-options": "SAMEORIGIN",
"x-content-type-options": "nosniff",
"alt-svc": "h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000",
"accept-ranges": "none",
"transfer-encoding": "chunked",
},
),
status: Status {
code: InvalidArgument,
message: "One of content, or gcs_content_uri must be set.",
details: [
BadRequest(
BadRequest {
field_violations: [
FieldViolation {
field: "document.content",
description: "Must have some text content to annotate.",
reason: "",
localized_message: None,
_unknown_fields: {},
},
],
_unknown_fields: {},
},
),
],
},
},
}
בדיקה פרוגרמטית של פרטי השגיאה
לפעמים צריך לבדוק את פרטי השגיאה באופן פרוגרמטי. בדוגמה הזו, הקוד עובר על מבנה הנתונים ומדפיס את השדות הרלוונטיים ביותר.
רק שגיאות שהשירות מחזיר מכילות מידע מפורט, לכן קודם צריך לשלוח שאילתה לגבי השגיאה כדי לבדוק אם היא מכילה את סוג השגיאה הנכון. אם כן, אפשר לפרט מידע כללי על השגיאה:
עוברים על הפרטים:
ספריות הלקוח מחזירות טיפוס מenum של StatusDetails עם הסוגים השונים של פרטי השגיאה. בדוגמה הזו נבדקות רק שגיאות מסוג BadRequest:
השדה BadRequest מכיל רשימה של שדות שמפירים את המדיניות. אפשר לחזור על הפעולה ולהדפיס את הפרטים של כל אחד מהם:
המידע הזה יכול להיות שימושי במהלך הפיתוח. ענפים אחרים של StatusDetails, כמו QuotaFailure, יכולים להיות שימושיים בזמן הריצה כדי לווסת את האפליקציה.
הפלט הצפוי:
הפלט של פרטי השגיאה אמור להיראות כך:
status.code=400, status.message=One of content, or gcs_content_uri must be set., status.status=Some("INVALID_ARGUMENT")
the request field document.content has a problem: "Must have some text content to annotate."
דוגמת קוד: בדיקת פרטי השגיאה
הפונקציה sample שולחת בקשה לא תקינה בכוונה ל-Cloud Natural Language API כדי ליצור שגיאת שירות. לאחר מכן הוא תופס את השגיאה ומחלל באופן פרוגרמטי את StatusDetails כדי לבדוק ולהדפיס הפרות ספציפיות של שדה BadRequest.
פתרון שגיאות קישור
כשמשתמשים ב-HTTP כדי לשלוח בקשות לשירותי Google Cloud , הבקשה משתמשת במזהה משאבים אחיד (URI) כדי לציין משאב. חלק מה-RPCs תואמים לכמה מזהי URI, והתוכן של הבקשה קובע באיזה URI להשתמש.
ספריית הלקוח בודקת את כל כתובות ה-URI האפשריות, ומחזירה שגיאת קישור רק אם אף אחת מהן לא עובדת. בדרך כלל זה קורה כששדה חסר או שהפורמט שלו לא תקין.
אם בבקשה לא תספקו שדות שמכילים פורמט תקין לכל URI אפשרי, יכול להיות שתקבלו שגיאת קישור:
Error: cannot find a matching binding to send the request: at least one of the
conditions must be met: (1) field `name` needs to be set and match the template:
'projects/*/secrets/*' OR (2) field `name` needs to be set and match the
template: 'projects/*/locations/*/secrets/*'
השגיאה בדוגמה הקודמת קרתה כי הדוגמה מנסה לאחזר את פרטי המשאב בלי לספק את השם שלו. באופן ספציפי, השדה name ב-GetSecretRequest הוא שדה חובה, אבל הוא לא מוגדר בדוגמה:
איך לפתור את הבעיה של שגיאות קישור
כדי לתקן את השגיאה, צריך להגדיר את שדה החובה כך שיתאים לאחת מהתבניות שמוצגות בהודעת השגיאה:
'projects/*/secrets/*''projects/*/locations/*/secrets/*'
כל אחת מהתבניות מאפשרת לספריית הלקוח לשלוח בקשה לשרת. לדוגמה, הקוד הבא תואם לתבנית הראשונה:
לחלופין, הקוד הבא תואם לתבנית השנייה:
פירוש התבניות
הודעת השגיאה של שגיאת קישור כוללת מחרוזות תבנית שמציגות ערכים אפשריים לשדות הבקשה. רוב מחרוזות התבניות כוללות את התווים הכלליים לחיפוש * ו-** כדי להתאים לערכי השדות.
תו כללי אחד לחיפוש
התו הכללי לחיפוש * לבדו מייצג מחרוזת לא ריקה ללא /. אפשר לחשוב על זה כעל הביטוי הרגולרי [^/]+.
הנה כמה דוגמאות:
| תבנית | קלט | יש התאמה? |
|---|---|---|
* |
simple-string-123 |
true |
projects/* |
projects/p |
true |
projects/*/locations |
projects/p/locations |
true |
projects/*/locations/* |
projects/p/locations/l |
true |
* |
"" (ריק) |
false |
* |
string/with/slashes |
false |
projects/* |
projects/ (ריק) |
false |
projects/* |
projects/p/ (קו נטוי נוסף) |
false |
projects/* |
projects/p/locations/l |
false |
projects/*/locations |
projects/p |
false |
projects/*/locations |
projects/p/locations/l |
false |
תו כללי כפול לחיפוש
תו הכללי הנפוץ פחות הוא **, שמשמעותו היא כל מחרוזת. המחרוזת יכולה להיות ריקה או להכיל מספר כלשהו של לוכסנים (/). אפשר להתייחס אליה כאל הביטוי הרגולרי .*.
כשתבנית מסתיימת ב-/**, הלוכסן הראשוני הוא אופציונלי.
| תבנית | קלט | יש התאמה? |
|---|---|---|
** |
"" |
true |
** |
simple-string-123 |
true |
** |
string/with/slashes |
true |
projects/*/** |
projects/p |
true |
projects/*/** |
projects/p/locations |
true |
projects/*/** |
projects/p/locations/l |
true |
projects/*/** |
locations/l |
false |
projects/*/** |
projects//locations/l |
false |
בדיקת שגיאות בקישור
אם אתם צריכים לבדוק את השגיאה באופן פרוגרמטי, בדקו אם זו שגיאת קישור והמירו אותה ל-BindingError: