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 :
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 :
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 :
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 :
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 :
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 :
Vous pouvez également envisager d'utiliser le lint non_exhaustive_omitted_patterns instable.