Questo documento spiega come utilizzare le enumerazioni (enum) nelle librerie client Cloud per Rust, inclusa la gestione dei valori enum introdotti dopo la release della libreria.
Sfondo
I serviziGoogle Cloud utilizzano le enumerazioni per i campi che accettano o forniscono un insieme discreto e limitato di valori. Sebbene i valori consentiti siano noti in qualsiasi momento, i servizi possono aggiungere nuovi valori nel tempo.
Le librerie client di Cloud per Rust possono inviare e ricevere valori enum, inclusi i valori introdotti dopo il rilascio della libreria.
Prima di iniziare
Gli esempi in questo documento vengono eseguiti localmente e non chiamano i servizi Google Cloud, quindi non hai bisogno di un progetto o un account Google Cloud . Gli esempi utilizzano la libreria client di Secret Manager e gli stessi principi si applicano alle enumerazioni in qualsiasi altra libreria client.
Dipendenze
Aggiungi la libreria client di Secret Manager e i crate di supporto al file Cargo.toml:
cargo add google-cloud-secretmanager-v1 serde_json anyhow
Gestisci i valori noti
Quando lavori con valori noti, puoi creare direttamente varianti di enum o convertirle da rappresentazioni di numeri interi o stringhe:
Gestisci i valori sconosciuti
Quando un enum riceve un valore di stringa non riconosciuto, .value() restituisce None,
mentre .name() e la serializzazione JSON continuano a funzionare come previsto:
Per i valori interi sconosciuti, anche la serializzazione JSON continua a funzionare come previsto, mentre .value() restituisce l'intero e .name() restituisce None:
Preparati agli upgrade
Gli enum nelle librerie client di Cloud per Rust possono acquisire nuove varianti nelle release future.
Per evitare di interrompere l'applicazione quando un servizio aggiunge nuove varianti, la libreria contrassegna gli enum generati come #[non_exhaustive].
Supponiamo che l'enum State sia importato nell'ambito:
Quando scrivi un'espressione match su un enum non esaustivo, includi il
pattern con caratteri jolly (_) per mantenere la compatibilità con le versioni precedenti
quando un servizio aggiunge nuove varianti:
Se vuoi ricevere un avviso del linter quando vengono visualizzate nuove varianti, in modo da poter esaminare e aggiornare i rami match, attiva il lint Clippy wildcard_enum_match_arm:
Puoi anche prendere in considerazione il lint instabile
non_exhaustive_omitted_patterns.