Utiliser des énumérations

Ce document explique comment utiliser les énumérations (enums) dans les bibliothèques clientes Cloud pour Rust, y compris comment gérer les valeurs d'énumération introduites après la publication de la bibliothèque.

Arrière-plan

Les servicesGoogle Cloud utilisent des énumérations pour les champs qui acceptent ou fournissent un ensemble discret et limité de valeurs. Bien que les valeurs autorisées soient connues à tout moment, les services peuvent ajouter de nouvelles valeurs au fil du temps.

Les bibliothèques clientes Cloud pour Rust peuvent envoyer et recevoir des valeurs d'énumération, y compris celles introduites après la publication de la bibliothèque.

Avant de commencer

Les exemples de ce document s'exécutent localement et n'appellent pas les services Google Cloud. Vous n'avez donc pas besoin d'un projet ni d'un compte Google Cloud . Les exemples utilisent la bibliothèque cliente Secret Manager, et les mêmes principes s'appliquent aux énumérations dans n'importe quelle autre bibliothèque cliente.

Dépendances

Ajoutez la bibliothèque cliente Secret Manager et les crates compatibles à votre fichier Cargo.toml :

cargo add google-cloud-secretmanager-v1 serde_json anyhow

Gérer les valeurs connues

Lorsque vous travaillez avec des valeurs connues, vous pouvez construire des variantes d'énumération directement ou les convertir à partir de représentations d'entiers ou de chaînes :

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

Gérer les valeurs inconnues

Lorsqu'un enum reçoit une valeur de chaîne non reconnue, .value() renvoie None, tandis que .name() et la sérialisation JSON continuent de fonctionner comme prévu :

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

Pour les valeurs entières inconnues, la sérialisation JSON continue également de fonctionner comme prévu, tandis que .value() renvoie l'entier et .name() renvoie 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);

Préparer les mises à niveau

Les énumérations des bibliothèques clientes Cloud pour Rust peuvent gagner de nouvelles variantes dans les versions futures. Pour éviter de casser votre application lorsqu'un service ajoute de nouvelles variantes, la bibliothèque marque les énumérations générées comme #[non_exhaustive].

Supposons que l'énumération State soit importée dans le champ d'application :

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

Lorsque vous écrivez une expression match sur un énum non exhaustif, incluez le modèle de caractère générique (_) pour maintenir la rétrocompatibilité lorsqu'un service ajoute de nouvelles variantes :

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

Si vous souhaitez qu'un avertissement du linter s'affiche lorsque de nouvelles variantes apparaissent afin de pouvoir examiner et mettre à jour vos bras match, activez le 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(())
}

Vous pouvez également envisager d'utiliser le lint non_exhaustive_omitted_patterns instable.