במאמר הזה מוסבר איך להשתמש בספירות (enums) בספריות הלקוח ב-Cloud ל-Rust, כולל טיפול בערכי enum שנוספו אחרי שהספרייה פורסמה.
רקע
בשירותיGoogle Cloud נעשה שימוש בספירות לשדות שמקבלים או מספקים קבוצה נפרדת ומוגבלת של ערכים. למרות שהערכים המותרים ידועים בכל שלב, שירותים יכולים להוסיף ערכים חדשים עם הזמן.
ספריות הלקוח של Cloud ל-Rust יכולות לשלוח ולקבל ערכי enum, כולל ערכים שהוצגו אחרי שהספרייה פורסמה.
לפני שמתחילים
הדוגמאות במסמך הזה פועלות באופן מקומי ולא קוראות לשירותי Google Cloud, כך שאין צורך בפרויקט או בחשבון ב- Google Cloud . בדוגמאות נעשה שימוש בספריית הלקוח של Secret Manager, ואותם עקרונות חלים על טיפוסי enum בכל ספריית לקוח אחרת.
יחסי תלות
מוסיפים את ספריית הלקוח של Secret Manager ואת ה-crates התומכים לקובץ Cargo.toml:
cargo add google-cloud-secretmanager-v1 serde_json anyhow
טיפול בערכים ידועים
כשעובדים עם ערכים ידועים, אפשר ליצור וריאנטים של enum ישירות או להמיר אותם מייצוגים של מספרים שלמים או מחרוזות:
טיפול בערכים לא ידועים
כש-enum מקבל ערך מחרוזת לא מזוהה, .value() מחזיר את None, ו-.name() והסריאליזציה של JSON ממשיכים לפעול כצפוי:
גם עבור ערכי מספרים שלמים לא ידועים, הסריאליזציה של JSON ממשיכה לפעול כצפוי, כאשר .value() מחזיר את המספר השלם ו-.name() מחזיר את None:
הכנה לשדרוגים
בגרסאות עתידיות של ספריות הלקוח של Cloud ל-Rust, יכול להיות שיתווספו וריאנטים חדשים ל-Enums.
כדי למנוע שיבושים באפליקציה כששירות מוסיף וריאציות חדשות, הספרייה מסמנת את הטיפוסים המאוגדים שנוצרו כ-#[non_exhaustive].
נניח שה-enum של State מיובא להיקף:
כשכותבים ביטוי match על enum לא ממצה, צריך לכלול את תבנית התווים הכלליים לחיפוש (_) כדי לשמור על תאימות לדורות קודמים כשמוסיפים וריאנטים חדשים לשירות:
אם אתם רוצים לקבל אזהרה מ-linter כשמופיעים וריאנטים חדשים כדי שתוכלו לבדוק ולעדכן את זרועות ה-match, הפעילו את ה-lint של Clippy wildcard_enum_match_arm:
אפשר גם להשתמש ב-lint הלא יציב non_exhaustive_omitted_patterns.