עבודה עם enums

במאמר הזה מוסבר איך להשתמש בספירות (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 ישירות או להמיר אותם מייצוגים של מספרים שלמים או מחרוזות:

use google_cloud_secretmanager_v1::model::secret_version::State;
let enabled = State::Enabled;
println!("State::Enabled = {enabled}");
assert_eq!(enabled.value(), Some(1));
assert_eq!(enabled.name(), Some("ENABLED"));

let state = State::from(1);
println!("state = {state}");
assert_eq!(state.value(), Some(1));
assert_eq!(state.name(), Some("ENABLED"));

let state = State::from("ENABLED");
println!("state = {state}");
assert_eq!(state.value(), Some(1));
assert_eq!(state.name(), Some("ENABLED"));
println!("json = {}", serde_json::to_value(&state)?);

טיפול בערכים לא ידועים

כש-enum מקבל ערך מחרוזת לא מזוהה, .value() מחזיר את None, ו-.name() והסריאליזציה של JSON ממשיכים לפעול כצפוי:

use google_cloud_secretmanager_v1::model::secret_version::State;
use serde_json::json;
let state = State::from("STATE_NAME_FROM_THE_FUTURE");
println!("state = {state}");
assert_eq!(state.value(), None);
assert_eq!(state.name(), Some("STATE_NAME_FROM_THE_FUTURE"));
println!("json = {}", serde_json::to_value(&state)?);
let u = serde_json::from_value::<State>(json!("STATE_NAME_FROM_THE_FUTURE"))?;
assert_eq!(state, u);

גם עבור ערכי מספרים שלמים לא ידועים, הסריאליזציה של JSON ממשיכה לפעול כצפוי, כאשר .value() מחזיר את המספר השלם ו-.name() מחזיר את None:

use google_cloud_secretmanager_v1::model::secret_version::State;
use serde_json::json;
const MAGIC_INT_FROM_THE_FUTURE: i32 = 17;
let state = State::from(MAGIC_INT_FROM_THE_FUTURE);
println!("state = {state}");
assert_eq!(state.value(), Some(17));
assert_eq!(state.name(), None);
println!("json = {}", serde_json::to_value(&state)?);
let s2 = serde_json::from_value::<State>(json!(17))?;
assert_eq!(state, s2);

הכנה לשדרוגים

בגרסאות עתידיות של ספריות הלקוח של Cloud ל-Rust, יכול להיות שיתווספו וריאנטים חדשים ל-Enums. כדי למנוע שיבושים באפליקציה כששירות מוסיף וריאציות חדשות, הספרייה מסמנת את הטיפוסים המאוגדים שנוצרו כ-#[non_exhaustive].

נניח שה-enum של State מיובא להיקף:

use google_cloud_secretmanager_v1::model::secret_version::State;

כשכותבים ביטוי match על enum לא ממצה, צריך לכלול את תבנית התווים הכלליים לחיפוש (_) כדי לשמור על תאימות לדורות קודמים כשמוסיפים וריאנטים חדשים לשירות:

fn match_with_wildcard(state: State) -> anyhow::Result<()> {
    use anyhow::Error;
    match state {
        State::Unspecified => {
            return Err(Error::msg("the documentation says this is never used"));
        }
        State::Enabled => println!("the secret is enabled and can be accessed"),
        State::Disabled => {
            println!("the secret version is not accessible until it is enabled")
        }
        State::Destroyed => {
            println!("the secret is destroyed, the data is no longer accessible")
        }
        State::UnknownValue(u) => {
            println!("unknown State variant ({u:?}) time to update the library")
        }
        _ => return Err(Error::msg("unexpected value, update this code")),
    };
    Ok(())
}

אם אתם רוצים לקבל אזהרה מ-linter כשמופיעים וריאנטים חדשים כדי שתוכלו לבדוק ולעדכן את זרועות ה-match, הפעילו את ה-lint של Clippy wildcard_enum_match_arm:

fn match_with_warnings(state: State) -> anyhow::Result<()> {
    use anyhow::Error;
    #[warn(clippy::wildcard_enum_match_arm)]
    match state {
        State::Unspecified => {
            return Err(Error::msg("the documentation says this is never used"));
        }
        State::Enabled => println!("the secret is enabled and can be accessed"),
        State::Disabled => {
            println!("the secret version is not accessible until it is enabled")
        }
        State::Destroyed => {
            println!("the secret is destroyed, the data is no longer accessible")
        }
        State::UnknownValue(u) => {
            println!("unknown State variant ({u:?}) time to update the library")
        }
        _ => {
            // *If* your CI includes treating clippy warnings as errors,
            // consider using `unreachable!()`.
            return Err(Error::msg("unexpected value, update this code"));
        }
    };
    Ok(())
}

אפשר גם להשתמש ב-lint הלא יציב non_exhaustive_omitted_patterns.