En este documento, se explica cómo usar enumeraciones (enums) en las bibliotecas cliente de Cloud para Rust, incluido el manejo de valores de enumeración introducidos después del lanzamiento de la biblioteca.
Fondo
Los servicios deGoogle Cloud usan enumeraciones para los campos que aceptan o proporcionan un conjunto discreto y limitado de valores. Aunque los valores permitidos se conocen en cualquier momento, los servicios pueden agregar valores nuevos con el tiempo.
Las bibliotecas cliente de Cloud para Rust pueden enviar y recibir valores de enumeración, incluidos los valores introducidos después del lanzamiento de la biblioteca.
Antes de comenzar
Los ejemplos de este documento se ejecutan de forma local y no llaman a los servicios de Google Cloud, por lo que no necesitas una cuenta ni un proyecto de Google Cloud . En los ejemplos, se usa la biblioteca cliente de Secret Manager, y se aplican los mismos principios a las enumeraciones en cualquier otra biblioteca cliente.
Dependencias
Agrega la biblioteca cliente de Secret Manager y los crates de compatibilidad a
tu archivo Cargo.toml:
cargo add google-cloud-secretmanager-v1 serde_json anyhow
Cómo controlar los valores conocidos
Cuando trabajas con valores conocidos, puedes construir variantes de enumeración directamente o convertirlas a partir de representaciones de números enteros o cadenas:
Controla los valores desconocidos
Cuando una enumeración recibe un valor de cadena no reconocido, .value() devuelve None,
mientras que .name() y la serialización JSON siguen funcionando como se espera:
Para los valores enteros desconocidos, la serialización de JSON también sigue funcionando como
se espera, mientras que .value() devuelve el número entero y .name() devuelve None:
Prepárate para las actualizaciones
Las enumeraciones en las bibliotecas cliente de Cloud para Rust pueden obtener variantes nuevas en versiones futuras.
Para evitar que tu aplicación falle cuando un servicio agrega variantes nuevas, la biblioteca
marca las enumeraciones generadas como #[non_exhaustive].
Supongamos que la enumeración State se importa al alcance:
Cuando escribas una expresión match sobre una enumeración no exhaustiva, incluye el
patrón de comodín (_) para mantener la retrocompatibilidad
cuando un servicio agregue variantes nuevas:
Si quieres que aparezca una advertencia de linter cuando aparezcan variantes nuevas para que puedas revisar y
actualizar tus ramas match, habilita el
lint de Clippy wildcard_enum_match_arm:
También puedes considerar el lint non_exhaustive_omitted_patterns inestable.