Mit Aufzählungen arbeiten

In diesem Dokument wird erläutert, wie Sie Enumerationen (Enums) in den Cloud-Clientbibliotheken für Rust verwenden, einschließlich der Verarbeitung von Enum-Werten, die nach der Veröffentlichung der Bibliothek eingeführt wurden.

Hintergrund

Google Cloud -Dienste verwenden Aufzählungen für Felder, die eine diskrete, begrenzte Anzahl von Werten akzeptieren oder bereitstellen. Obwohl die zulässigen Werte jederzeit bekannt sind, können Dienste im Laufe der Zeit neue Werte hinzufügen.

Die Cloud-Clientbibliotheken für Rust können Enum-Werte senden und empfangen, einschließlich Werte, die nach der Veröffentlichung der Bibliothek eingeführt wurden.

Hinweis

Die Beispiele in diesem Dokument werden lokal ausgeführt und rufen keine Google Cloud-Dienste auf. Sie benötigen also kein Google Cloud -Projekt oder -Konto. In den Beispielen wird die Secret Manager-Clientbibliothek verwendet. Dieselben Prinzipien gelten für Aufzählungen in jeder anderen Clientbibliothek.

Abhängigkeiten

Fügen Sie die Secret Manager-Clientbibliothek und die unterstützenden Crates der Datei Cargo.toml hinzu:

cargo add google-cloud-secretmanager-v1 serde_json anyhow

Bekannte Werte verarbeiten

Wenn Sie mit bekannten Werten arbeiten, können Sie Enum-Varianten direkt erstellen oder sie aus Ganzzahl- oder Stringdarstellungen konvertieren:

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

Umgang mit unbekannten Werten

Wenn ein Enum einen nicht erkannten Stringwert empfängt, gibt .value() den Wert None zurück, während .name() und die JSON-Serialisierung weiterhin wie erwartet funktionieren:

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

Bei unbekannten Ganzzahlwerten funktioniert die JSON-Serialisierung weiterhin wie erwartet, während .value() die Ganzzahl und .name() den Wert None zurückgibt:

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

Auf Upgrades vorbereiten

Enums in den Cloud-Clientbibliotheken für Rust können in zukünftigen Releases neue Varianten erhalten. Damit Ihre Anwendung nicht beeinträchtigt wird, wenn ein Dienst neue Varianten hinzufügt, werden generierte Enums in der Bibliothek als #[non_exhaustive] markiert.

Angenommen, das Enum State wird in den Bereich importiert:

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

Wenn Sie einen match-Ausdruck für eine unvollständige Enum schreiben, fügen Sie das Platzhaltermuster (_) ein, um die Abwärtskompatibilität zu gewährleisten, wenn ein Dienst neue Varianten hinzufügt:

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

Wenn Sie eine Linter-Warnung erhalten möchten, wenn neue Varianten angezeigt werden, damit Sie Ihre match-Zweige prüfen und aktualisieren können, aktivieren Sie den Clippy-Lint 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(())
}

Sie können auch den instabilen Lint non_exhaustive_omitted_patterns in Betracht ziehen.