Utilizzo delle enumerazioni

Questo documento spiega come utilizzare le enumerazioni (enum) nelle librerie client Cloud per Rust, inclusa la gestione dei valori enum introdotti dopo la release della libreria.

Sfondo

I serviziGoogle Cloud utilizzano le enumerazioni per i campi che accettano o forniscono un insieme discreto e limitato di valori. Sebbene i valori consentiti siano noti in qualsiasi momento, i servizi possono aggiungere nuovi valori nel tempo.

Le librerie client di Cloud per Rust possono inviare e ricevere valori enum, inclusi i valori introdotti dopo il rilascio della libreria.

Prima di iniziare

Gli esempi in questo documento vengono eseguiti localmente e non chiamano i servizi Google Cloud, quindi non hai bisogno di un progetto o un account Google Cloud . Gli esempi utilizzano la libreria client di Secret Manager e gli stessi principi si applicano alle enumerazioni in qualsiasi altra libreria client.

Dipendenze

Aggiungi la libreria client di Secret Manager e i crate di supporto al file Cargo.toml:

cargo add google-cloud-secretmanager-v1 serde_json anyhow

Gestisci i valori noti

Quando lavori con valori noti, puoi creare direttamente varianti di enum o convertirle da rappresentazioni di numeri interi o stringhe:

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)?);

Gestisci i valori sconosciuti

Quando un enum riceve un valore di stringa non riconosciuto, .value() restituisce None, mentre .name() e la serializzazione JSON continuano a funzionare come previsto:

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);

Per i valori interi sconosciuti, anche la serializzazione JSON continua a funzionare come previsto, mentre .value() restituisce l'intero e .name() restituisce 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);

Preparati agli upgrade

Gli enum nelle librerie client di Cloud per Rust possono acquisire nuove varianti nelle release future. Per evitare di interrompere l'applicazione quando un servizio aggiunge nuove varianti, la libreria contrassegna gli enum generati come #[non_exhaustive].

Supponiamo che l'enum State sia importato nell'ambito:

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

Quando scrivi un'espressione match su un enum non esaustivo, includi il pattern con caratteri jolly (_) per mantenere la compatibilità con le versioni precedenti quando un servizio aggiunge nuove varianti:

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(())
}

Se vuoi ricevere un avviso del linter quando vengono visualizzate nuove varianti, in modo da poter esaminare e aggiornare i rami match, attiva il 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(())
}

Puoi anche prendere in considerazione il lint instabile non_exhaustive_omitted_patterns.