列挙型を操作する

このドキュメントでは、Rust 用 Cloud クライアント ライブラリで列挙型(enum)を使用する方法について説明します。これには、ライブラリのリリース後に導入された列挙型の値の処理も含まれます。

背景

Google Cloud サービスでは、個別の限定された値セットを受け入れるか、提供するフィールドに列挙型を使用します。許可される値はいつでも確認できますが、サービスは時間の経過とともに新しい値を追加できます。

Rust 用の Cloud クライアント ライブラリは、ライブラリのリリース後に導入された値を含む列挙値を送受信できます。

始める前に

このドキュメントの例はローカルで実行され、 Google Cloudサービスを呼び出さないため、 Google Cloud プロジェクトやアカウントは必要ありません。この例では Secret Manager クライアント ライブラリを使用していますが、同じ原則が他のクライアント ライブラリの列挙型にも適用されます。

依存関係

Secret Manager クライアント ライブラリとサポート クレートを Cargo.toml ファイルに追加します。

cargo add google-cloud-secretmanager-v1 serde_json anyhow

既知の値を処理する

既知の値を扱う場合は、列挙型バリアントを直接作成するか、整数または文字列の表現から変換できます。

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

不明な値を処理する

列挙型が認識されない文字列値を受け取ると、.value() は None を返しますが、.name() と JSON シリアル化は引き続き想定どおりに機能します。

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

不明な整数値の場合、JSON シリアル化も想定どおりに機能し、.value() は整数を返し、.name() は 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);

アップグレードの準備

Rust 用 Cloud クライアント ライブラリの列挙型は、今後のリリースで新しいバリアントが追加される可能性があります。サービスが新しいバリアントを追加したときにアプリケーションが破損しないように、ライブラリは生成された列挙型を #[non_exhaustive] としてマークします。

State 列挙型がスコープにインポートされているとします。

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

すべてを網羅していない列挙型に対して match 式を記述する場合は、ワイルドカード パターン(_)を含めて、サービスが新しいバリアントを追加したときに下位互換性を維持します。

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

新しいバリアントが表示されたときに linter 警告を表示して、match アームを確認して更新できるようにするには、wildcard_enum_match_arm Clippy lint を有効にします。

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

不安定な non_exhaustive_omitted_patterns lint を検討することもできます。