Bekerja dengan enum

Dokumen ini menjelaskan cara menggunakan enumerasi (enum) di Library Klien Cloud untuk Rust, termasuk menangani nilai enum yang diperkenalkan setelah rilis library.

Latar belakang

LayananGoogle Cloud menggunakan enumerasi untuk kolom yang menerima atau menyediakan sekumpulan nilai yang terpisah dan terbatas. Meskipun nilai yang diizinkan diketahui kapan saja, layanan dapat menambahkan nilai baru seiring waktu.

Library Klien Cloud untuk Rust dapat mengirim dan menerima nilai enum, termasuk nilai yang diperkenalkan setelah library dirilis.

Sebelum memulai

Contoh dalam dokumen ini berjalan secara lokal dan tidak memanggil layanan Google Cloud, sehingga Anda tidak memerlukan project atau akun Google Cloud . Contoh ini menggunakan library klien Secret Manager, dan prinsip yang sama berlaku untuk enumerasi di library klien lainnya.

Dependensi

Tambahkan library klien Secret Manager dan crate pendukung ke file Cargo.toml Anda:

cargo add google-cloud-secretmanager-v1 serde_json anyhow

Menangani nilai yang diketahui

Saat menggunakan nilai yang diketahui, Anda dapat membuat varian enum secara langsung atau mengonversinya dari representasi bilangan bulat atau string:

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

Menangani nilai yang tidak diketahui

Saat enum menerima nilai string yang tidak dikenali, .value() akan menampilkan None, sementara .name() dan serialisasi JSON akan terus berfungsi seperti yang diharapkan:

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

Untuk nilai bilangan bulat yang tidak diketahui, serialisasi JSON juga terus berfungsi seperti yang diharapkan, sementara .value() menampilkan bilangan bulat dan .name() menampilkan 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);

Bersiap untuk upgrade

Enum di Library Klien Cloud untuk Rust dapat memperoleh varian baru dalam rilis mendatang. Agar tidak merusak aplikasi Anda saat layanan menambahkan varian baru, library menandai enum yang dihasilkan sebagai #[non_exhaustive].

Asumsikan enum State diimpor ke dalam cakupan:

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

Saat menulis ekspresi match pada enum yang tidak lengkap, sertakan pola karakter pengganti (_) untuk mempertahankan kompatibilitas mundur saat layanan menambahkan varian baru:

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

Jika Anda menginginkan peringatan linter saat varian baru muncul sehingga Anda dapat meninjau dan memperbarui arm match, aktifkan 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(())
}

Anda juga dapat mempertimbangkan lint non_exhaustive_omitted_patterns yang tidak stabil.