Enum 작업

이 문서에서는 라이브러리 출시 후 도입된 enum 값 처리를 포함하여 Rust용 Cloud 클라이언트 라이브러리에서 열거형(enum)을 사용하는 방법을 설명합니다.

배경

Google Cloud 서비스는 불연속적이고 제한된 값 집합을 허용하거나 제공하는 필드에 열거형을 사용합니다. 허용되는 값은 언제든지 알 수 있지만 서비스는 시간이 지남에 따라 새 값을 추가할 수 있습니다.

Rust용 Cloud 클라이언트 라이브러리는 라이브러리가 출시된 후 도입된 값을 포함하여 enum 값을 전송하고 수신할 수 있습니다.

시작하기 전에

이 문서의 예시는 로컬에서 실행되며 Google Cloud서비스를 호출하지 않으므로 Google Cloud 프로젝트나 계정이 필요하지 않습니다. 이 예시에서는 Secret Manager 클라이언트 라이브러리를 사용하며, 다른 클라이언트 라이브러리의 열거형에도 동일한 원칙이 적용됩니다.

종속 항목

Secret Manager 클라이언트 라이브러리 및 지원 크레이트를 Cargo.toml 파일에 추가합니다.

cargo add google-cloud-secretmanager-v1 serde_json anyhow

알려진 값 처리

알려진 값으로 작업할 때는 enum 변형을 직접 구성하거나 정수 또는 문자열 표현에서 변환할 수 있습니다.

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

알 수 없는 값 처리

enum이 인식할 수 없는 문자열 값을 수신하면 .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 클라이언트 라이브러리의 enum은 향후 출시에서 새로운 변형을 얻을 수 있습니다. 서비스에서 새 변이를 추가할 때 애플리케이션이 중단되지 않도록 라이브러리는 생성된 enum을 #[non_exhaustive]로 표시합니다.

State enum을 범위로 가져온다고 가정합니다.

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

일부 enum에 대해 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(())
}

새 변형이 표시될 때 린터 경고를 표시하여 match 분기를 검토하고 업데이트하려면 wildcard_enum_match_arm Clippy 린트를 사용 설정합니다.

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 린트도 고려할 수 있습니다.