Trabaja con enumeraciones

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:

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

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:

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

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:

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

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:

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

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:

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 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:

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

También puedes considerar el lint non_exhaustive_omitted_patterns inestable.