Como trabalhar com enumerações

Neste documento, explicamos como usar enumerações (enums) nas bibliotecas de cliente do Cloud para Rust, incluindo o processamento de valores de enum introduzidos após o lançamento da biblioteca.

Contexto

Os serviços doGoogle Cloud usam enumerações para campos que aceitam ou fornecem um conjunto discreto e limitado de valores. Embora os valores permitidos sejam conhecidos a qualquer momento, os serviços podem adicionar novos valores ao longo do tempo.

As bibliotecas de cliente do Cloud para Rust podem enviar e receber valores de tipo enumerado, incluindo valores introduzidos após o lançamento da biblioteca.

Antes de começar

Os exemplos neste documento são executados localmente e não chamam serviços do Google Cloud. Portanto, você não precisa de um projeto ou uma conta do Google Cloud . Os exemplos usam a biblioteca de cliente do Secret Manager, e os mesmos princípios se aplicam a enumerações em qualquer outra biblioteca de cliente.

Dependências

Adicione a biblioteca de cliente do Secret Manager e os crates de suporte ao arquivo Cargo.toml:

cargo add google-cloud-secretmanager-v1 serde_json anyhow

Processar valores conhecidos

Ao trabalhar com valores conhecidos, é possível criar variantes de tipo enumerado diretamente ou convertê-las de representações de números inteiros ou strings:

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

Processar valores desconhecidos

Quando um tipo enumerado recebe um valor de string não reconhecido, .value() retorna None, enquanto .name() e a serialização JSON continuam funcionando como esperado:

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 valores inteiros desconhecidos, a serialização JSON também continua funcionando como esperado, enquanto .value() retorna o número inteiro e .name() retorna 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);

Preparar para upgrades

Os tipos enumerados nas bibliotecas de cliente do Cloud para Rust podem ganhar novas variantes em versões futuras. Para evitar que o aplicativo seja interrompido quando um serviço adicionar novas variantes, a biblioteca marca os tipos enumerados gerados como #[non_exhaustive].

Suponha que o tipo enumerado State seja importado para o escopo:

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

Ao escrever uma expressão match sobre um tipo enumerado alguns exemplos, inclua o padrão de caractere curinga (_) para manter a compatibilidade com versões anteriores quando um serviço adicionar novas 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(())
}

Se você quiser um aviso do linter quando novas variantes aparecerem para analisar e atualizar os braços match, ative o 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(())
}

Você também pode considerar o lint instável non_exhaustive_omitted_patterns.