在 Rust 中使用 Serde 的詳細指南
在處理 HTTP 請求時,我們總是需要在一種數據結構 (可以是 enum、struct 等) 和一種可以存儲或傳輸並稍後重建的格式 (例如 JSON) 之間來回轉換。
Serde 是一個庫 (crate),用於高效、通用地序列化和反序列化 Rust 數據結構。在本文中,將詳細介紹如何使用 Serde 對數據結構進行序列化和反序列化操作。
讓我們從一個簡單的結構體 Student 開始,它的定義如下所示,並進行初始化。
use serde::{Serialize, Deserialize};
#[derive(Debug, Clone, Serialize, Deserialize)]
struct Student {
pub name: String,
pub student_id: String,
}
let student = Student{name:"tom".to_owned(), student_id:"J19990".to_owned()};
約定
對於上面的示例,如果我們使用 serde_json::to_string(&student) 將其轉換爲 JSON 字符串,那麼輸出將如下所示。
{
"name": "tom",
"student_id": "J19990"
}
看起來太棒了!然而,這依賴於發送 HTTP 請求的內容,很有可能會與 Rust 中的數據結構有不同的大小寫約定。
基本上有兩種方法可以進行約定:可以重命名字段;也可以對整個結構應用大小寫約定。
例如,我們實際上希望使用 studentId 而不是 student_id 作爲字段名。
方法 1:使用 #[serde(re) 重命名單個字段。
struct Student {
pub name: String,
#[serde(re)
pub student_id: String,
}
方法 2:使用 #[serde(rename_all="camelCase") 將大小寫約定駝峯形式,應用於整個結構體。
#[serde(rename_all = "camelCase")]
struct Student {
pub name: String,
pub student_id: String,
}
任何一種方法都會給出以下輸出:
{
"name": "tom",
"studentId": "J19990"
}
除了 camelCase 之外,還可以應用其他的約定。取值爲 “lowercase, UPPERCASE, PascalCase, camelCase, snake_case, SCREAMING_SNAKE_CASE, kebab-case, SCREAMING-KEBAB-CASE”。
Skip
Skip 可用於不希望序列化或反序列化的字段。下面是一個簡單的例子。讓我們給 Student 添加 birth_year 和 age。
struct Student {
pub name: String,
pub student_id: String,
pub birth_year: u32,
pub age: u32,
}
我們可能希望動態更新年齡,因此需要對學生 birth_year 的引用。但是,當我們發送請求時,應該只顯示 age 字段,這可以使用#[serde(skip)] 來解決。
struct Student {
pub name: String,
pub student_id: String,
#[serde(skip)]
pub birth_year: u32,
pub age: u32,
}
通過這樣做,我們的 JSON 對象將變成:
{
"name": "tom",
"studentId": "J19990",
"age": 123
}
Skip If
最常見的兩種使用方法是作用於 Option 字段和空的 vector 字段。
Option
假設我們有一個 middle_name: Option 字段,如果我們想在學生沒有這個字段的情況下跳過這個字段,我們可以這樣做。
struct Student {
pub name: String,
pub student_id: String,
#[serde(skip_serializing_if="Option::is_none")]
pub middle_name: Option<String>
}
這將爲帶有或不帶有中間名的學生生成如下 JSON:
// 沒有中間名
{
"name": "tom",
"studentId": "J19990",
}
// 有中間名
{
"name": "tom",
"studentId": "J19990",
"middleName": "middle"
}
Vector
例如,我們爲 student 結構體提供了 pets: Vec 字段。由於學生不必擁有寵物,它可以是一個空向量。
要跳過對空向量的序列化,可以向字段添加以下屬性。
#[serde(skip_serializing_if="Vec::is_empty")]
pub pets: Vec<String>,
有屬性和沒有屬性之間的輸出差異如下所示。
// 沒有屬性
{
"name": "tom",
"studentId": "J19990",
"pets": []
}
// 有屬性
{
"name": "tom",
"studentId": "J19990"
}
Flatten
讓我們創建一個名爲 SideInfo 的新結構體,並將 Student 結構體更改爲以下內容。
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
struct Student {
pub name: String,
pub student_id: String,
#[serde(skip_serializing_if="Option::is_none")]
pub side_info: Option<SideInfo>
}
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(rename_all = "camelCase")]
struct SideInfo {
#[serde(skip_serializing_if="Option::is_none")]
pub pets: Option<Vec<String>>,
#[serde(skip_serializing_if="Option::is_none")]
pub address: Option<String>,
}
讓我們創建一個新的 Student
let student = Student{name:"dan".to_owned(), student_id: "1".to_owned(), side_info:Some(SideInfo{address:Some("47 street".to_owned()), ..Default::default()})};
並輸出它的 JSON 字符串:
{
"name": "dan",
"studentId": "1",
"sideInfo": {
"address": "47 street"
}
}
如你所見,地址字段嵌套在 sideInfo 中。我們可以通過將屬性 flatten 添加到 Student 結構體中的 sideInfo 字段上,來消除嵌套。
#[serde(skip_serializing_if="Option::is_none", flatten)]
pub side_info: Option<SideInfo>
就會變成:
{
"name": "dan",
"studentId": "1",
"address": "47 street"
}
枚舉上的標籤與非標籤
假設我們有一個 StudentList enum,如下所示:
enum StudentList {
Student1(Student),
Student2(Student)
}
定義學生名單
let student1 = Student{name:"tom".to_owned(), student_id:"J19990".to_owned(), pets: vec![], middle_name:Some("middle".to_owned())};
let student2 = Student{name:"dan".to_owned(), student_id:"J19990".to_owned(), pets: vec![], middle_name:Some("middle".to_owned())};
let student_list = vec![StudentList::Student1(student1), StudentList::Student2(student2)];
如果我們像現在一樣打印出 JSON,它將如下所示,它是有標籤的,是 serde 的默認行爲。
[
{
"Student1": {
"name": "tom",
"studentId": "J19990",
"pets": [],
"middleName": "middle"
}
},
{
"Student2": {
"name": "dan",
"studentId": "J19990",
"pets": [],
"middleName": "middle"
}
}
]
如果你希望所有標籤都具有相同的名稱,例如 Student,該怎麼辦呢?你可能認爲可以使用 rename_all 來實現這一點,但實際上並非如此,應該手動重命名枚舉中的每個變體。
#[derive(Debug, Clone, Serialize, Deserialize)]
enum StudentList {
#[serde(re)]
Student1(Student),
#[serde(re)]
Student2(Student)
}
輸出如下:
[
{
"Student": {
"name": "tom",
"studentId": "J19990",
"pets": [],
"middleName": "middle"
}
},
{
"Student": {
"name": "dan",
"studentId": "J19990",
"pets": [],
"middleName": "middle"
}
}
]
不加標籤
如果我們只想要一個簡單的學生數組,而不顯示枚舉變量名稱,該怎麼辦?我們可以通過向枚舉中添加 #[serde(untagged)] 屬性來實現這一點。通過這樣做,我們的輸出將變成:
[
{
"name": "tom",
"studentId": "J19990",
"pets": [],
"middleName": "middle"
},
{
"name": "dan",
"studentId": "J19990",
"pets": [],
"middleName": "middle"
}
]
內部標籤
枚舉的另一種表示形式是內部標籤,讓我們創建一個包含不同學生類型的新枚舉,我們將有班長、副班長和普通學生。
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all="camelCase")]
enum StudentType {
Regular(Student),
Leader(Student),
SubLeader(Student)
}
指定 serde(tag = "type") 將允許我們在內容中使用標籤來識別我們正在處理的變體,如下所示:
[
{
"type": "leader",
"name": "tom",
"studentId": "J19990",
"pets": [],
"middleName": "middle"
},
{
"type": "regular",
"name": "dan",
"studentId": "J19990",
"pets": [],
"middleName": "middle"
}
]
相鄰標籤
表示標籤和內容作爲同一對象中的兩個字段彼此相鄰。將枚舉的屬性修改如下:
#[serde(tag = "type", content = "student", rename_all="camelCase")]
json 數據變成:
[
{
"type": "leader",
"student": {
"name": "tom",
"studentId": "J19990",
"pets": [],
"middleName": "middle"
}
},
{
"type": "regular",
"student": {
"name": "dan",
"studentId": "J19990",
"pets": [],
"middleName": "middle"
}
}
]
可以用 Serde 做很多很多事情。如果你感興趣,可以去官方網站了解更多使用方法!
本文由 Readfog 進行 AMP 轉碼,版權歸原作者所有。
來源:https://mp.weixin.qq.com/s/w2ZYgZpbRi4NgatULB8Qxg