Serde 是一个 Rust 编程语言上的框架,可以有效率地让某个结构能被串行化(Serialization)或是被反串行化(Deserialization),而且串行化或反串行化的程序只要撰写一次,就可以被用在多种不同的数据格式(如 JSON、MessagePack、BSON 等),或是自行定义的数据格式上。

什么是串行化?

串行化就是把某个存在于内存中的数据状态保存下来的动作。例如:

struct Point {
    x: f64,
    y: f64,
}

let p1 = Point {
    x: 7.0,
    y: 8.0,
};

以上的 p1 变量所保存的 Point 结构实体,可以被串行化成以下的 JSON 格式的文字来保存到文件、数据库,甚至是用来在不同的应用程序之间传输:

{
    "x": 7.0,
    "y": 8.0
}

而反串行化,顾名思义串行化的反向动作,把某个已经被串行化好的值再还原到内存中。例如以上的 JSON 格式的文字,可以再被反串行化为:

Point {
    x: 7.0,
    y: 8.0,
}

Serde 框架

serde

Serde 框架的套件(crate)名称为 serde,如果要用它提供的进程式宏,就要激活它的 derive 特色。

若要引用它们,可在 Cargo.toml 设置档的 [dependencies] 区块加上:

serde = { version = "*", features = ["derive"] }

宏的使用

串行化

以刚才提到的 Point 结构体来举例,若要将它加上串行化的功能,程序只要写成以下这样就好了:

use serde::Serialize;

#[derive(Serialize)]
struct Point {
    x: f64,
    y: f64,
}

在某个类型上的 derive 属性加上 Serialize 参数,可以让该类型自动去实作 serde::Serialize 特性。有关于这个特性的手动实作方式,由于十分繁琐,本篇文章就不说明了。

类型中要跟着被串行化的数据,其类型也必须要有实作 serde::Serialize 特性才行。Serde 框架已经有对所有 Rust 编程语言的基本数据类型(如 u8、i16、f32 等)、字符串和字符串切片、数组(array)、元组(tuple)、单元(unit,即 ())、Option 枚举(代表有无数据的存在)、Vec、HashMap、BTreeMap、PhantomData 等类型实作了 serde::Serialize 特性。

反串行化

继续用 Point 结构体来举例,若要将它加上反串行化的功能,程序只要写成以下这样就好了:

use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct Point {
    x: f64,
    y: f64,
}

在某个类型上的 derive 属性加上 Deserialize 参数,可以让该类型自动去实作 serde::Deserialize 特性。有关于这个特性的手动实作方式,由于十分繁琐,本篇文章就不说明了。

同样地,类型中要跟着被反串行化的数据,其类型也必须要有实作 serde::Deserialize 特性才行。Serde 框架已经有对其预设有实作 serde::Serialize 特性的类型(见上个小节)实作 serde::Deserialize 特性了。

举个实例看看?

如果您觉得把类型加上 #[derive(Serialize, Deserialize)] 属性后就可以让它能进行串行化和反串行化这件事很抽象的话,可以试着将其串行化成某种您熟悉的数据格式来试试。

以 JSON 为例,在 Cargo.toml 设置档的 [dependencies] 区块再加上:

serde_json = "*"

然后撰写如下的可运行程序:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Point {
    x: f64,
    y: f64,
}

fn main() {
    let p1 = Point {
        x: 7.0, y: 8.0
    };

    let json = serde_json::to_string_pretty(&p1).unwrap();

    println!("{json}");

    let p2: Point = serde_json::from_str(&json).unwrap();

    println!("{p2:#?}");
}

运行结果如下:

{
  "x": 7.0,
  "y": 8.0
}
Point {
    x: 7.0,
    y: 8.0,
}

宏的高级使用

在实作串行化和反串行化的程序时会遇到各式各样的需求,底下会继续说明 Serde 的进程式宏能够做到哪些常需要的功能。

串行化时忽略某个字段,让反串行化时的字段有默认值

替想要在串行化时忽略的字段加上 #[serde(skip_serializing)] 属性,该字段就不会被串行化。

例如:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Point {
    x: f64,
    #[serde(skip_serializing)]
    y: f64,
}

fn main() {
    let p1 = Point {
        x: 7.0, y: 8.0
    };

    let json = serde_json::to_string_pretty(&p1).unwrap();

    println!("{json}");

    // let p2: Point = serde_json::from_str(&json).unwrap();

    // println!("{p2:#?}");
}

运行结果如下:

{
  "x": 7.0
}

注意这个程序,我们并没有去反串行化 JSON 格式的文字,因为 JSON 格式的文字中并不存在 y 字段,所以会反串行化失败!为了解决这个问题,我们也可以替 y 字段的 serde 属性加上 default 参数,使其在反串行化时,如果来源数据中并没有 y 字段,就去使用 y 字段的 Default 特性来产生默认值。

例如:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Point {
    x: f64,
    #[serde(skip_serializing, default)]
    y: f64,
}

fn main() {
    let p1 = Point {
        x: 7.0, y: 8.0
    };

    let json = serde_json::to_string_pretty(&p1).unwrap();

    println!("{json}");

    let p2: Point = serde_json::from_str(&json).unwrap();

    println!("{p2:#?}");
}

运行结果如下:

{
  "x": 7.0
}
Point {
    x: 7.0,
    y: 0.0,
}

如果想用某个指定函数来产生默认值,可以将 default 参数改成 default = "path",其中的 path 是指要调用的函数的路径。

例如:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Point {
    x: f64,
    #[serde(skip_serializing, default = "default_y")]
    y: f64,
}

fn default_y() -> f64 {
    5.0
}

fn main() {
    let p1 = Point {
        x: 7.0, y: 8.0
    };

    let json = serde_json::to_string_pretty(&p1).unwrap();

    println!("{json}");

    let p2: Point = serde_json::from_str(&json).unwrap();

    println!("{p2:#?}");
}

运行结果如下:

{
  "x": 7.0
}
Point {
    x: 7.0,
    y: 5.0,
}
串行化时按照条件忽略某个字段

替想要在串行化时忽略的字段加上 #[serde(skip_serializing)] 属性,该字段就不会被串行化。但是若我们只是想要让其在某个条件时不被串行化的话,就要使用 skip_serializing_if = "path" 参数,而不是 skip_serializing,其中的 path 是指要调用的函数的路径,这个函数必须要回传一个 bool 值,来决定是否不要将其串行化。

例如:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Point {
    x: f64,
    #[serde(skip_serializing_if = "ignore_y", default = "default_y")]
    y: f64,
}

fn default_y() -> f64 {
    5.0
}

fn ignore_y(y: &f64) -> bool {
    *y == 8.0
}

fn main() {
    let p1 = Point {
        x: 7.0, y: 8.0
    };

    let json = serde_json::to_string_pretty(&p1).unwrap();

    println!("{json}");

    let p2: Point = serde_json::from_str(&json).unwrap();

    println!("{p2:#?}");
}

运行结果如下:

{
  "x": 7.0
}
Point {
    x: 7.0,
    y: 5.0,
}

这个功能通常会用在字段的类型是 Option 枚举或是集合时。

像是:

#[derive(Serialize, Deserialize)]
struct Student {
    id: String,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    toeic_score: Option<u16>,
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    awards: Vec<String>,
}
反串行化时忽略某个字段

替想要在反串行化时忽略的字段加上 #[serde(skip_deserializing)] 属性,该字段就不会被反串行化。

例如:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Point {
    x: f64,
    #[serde(skip_deserializing, default)]
    y: f64,
}

fn main() {
    let p1 = Point {
        x: 7.0, y: 8.0
    };

    let json = serde_json::to_string_pretty(&p1).unwrap();

    println!("{json}");

    let p2: Point = serde_json::from_str(&json).unwrap();

    println!("{p2:#?}");
}

运行结果如下:

{
  "x": 7.0,
  "y": 8.0
}
Point {
    x: 7.0,
    y: 0.0,
}
串行化和反串行化时忽略某个字段

替想要在串行化和反串行化时忽略的字段加上 #[serde(skip)] 属性,该字段就不会被串行化和反串行化。这功能等同于使用 #[serde(skip_serializing, skip_deserializing)] 属性。

例如:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Point {
    x: f64,
    #[serde(skip, default)]
    y: f64,
}

fn main() {
    let p1 = Point {
        x: 7.0, y: 8.0
    };

    let json = serde_json::to_string_pretty(&p1).unwrap();

    println!("{json}");

    let p2: Point = serde_json::from_str(&json).unwrap();

    println!("{p2:#?}");
}

运行结果如下:

{
  "x": 7.0
}
Point {
    x: 7.0,
    y: 0.0,
}
更改串行化出来的字段名称

替字段加上 #[serde(rename = "new_name")] 属性,该字段串行化出来的字段名称就会被更改。

例如:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Point {
    #[serde(rename = "X")]
    x: f64,
    #[serde(rename = "Y")]
    y: f64,
}

fn main() {
    let p1 = Point {
        x: 7.0, y: 8.0
    };

    let json = serde_json::to_string_pretty(&p1).unwrap();

    println!("{json}");

    let p2: Point = serde_json::from_str(&json).unwrap();

    println!("{p2:#?}");
}

运行结果如下:

{
  "X": 7.0,
  "Y": 8.0
}
Point {
    x: 7.0,
    y: 8.0,
}

虽然比较不常用,但如果想要分别设置串行化时输出的字段名称,和反串行化时输入的字段名称,要改写成 #[serde(rename(serialize = "ser_name", deserialize = "de_name"))]。

例如:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Point {
    #[serde(rename(serialize = "X", deserialize = "a"))]
    x: f64,
    #[serde(rename(serialize = "Y", deserialize = "b"))]
    y: f64,
}

fn main() {
    let p1 = Point {
        x: 7.0, y: 8.0
    };

    let json = serde_json::to_string_pretty(&p1).unwrap();

    println!("{json}");

    let p2: Point = serde_json::from_str("{\"a\": 7.0, \"b\": 8.0}").unwrap();

    println!("{p2:#?}");
}

运行结果如下:

{
  "X": 7.0,
  "Y": 8.0
}
Point {
    x: 7.0,
    y: 8.0,
}

如果我们想要统一修改输入、输出的字段名称的格式,比如全部小写、全部大写、驼峰式等等,可以替整个类型加上 #[serde(rename_all = "rename_method")] 属性,其中的 rename_method 允许的值有以下几种:

  • lowercase:小写。
  • UPPERCASE:大写。
  • PascalCase:第一个字母为大写的驼峰式命名。这种是 Rust 的类型名称建议使用的命名方式。
  • camelCase:第一个字母为小写的驼峰式命名。
  • snake_case:小蛇式命名,用底线 _ 连接小写单字。这种是 Rust 的字段名称建议使用的命名方式。
  • SCREAMING_SNAKE_CASE:大蛇式命名,用底线 _ 连接大写单字。这种是 Rust 的常数或是静态变量名称建议使用的命名方式。
  • kebab-case:小串烤肉式命名,用减号 - 连接小写单字。
  • SCREAMING-KEBAB-CASE:大串烤肉式命名,用减号 - 连接大写单字。

例如:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
#[serde(rename_all = "UPPERCASE")]
struct Point {
    x: f64,
    y: f64,
}

fn main() {
    let p1 = Point {
        x: 7.0, y: 8.0
    };

    let json = serde_json::to_string_pretty(&p1).unwrap();

    println!("{json}");

    let p2: Point = serde_json::from_str(&json).unwrap();

    println!("{p2:#?}");
}

运行结果如下:

{
  "X": 7.0,
  "Y": 8.0
}
Point {
    x: 7.0,
    y: 8.0,
}

同样地,虽然比较不常用,但如果想要分别统一设置串行化时输出的字段名称,和反串行化时输入的字段名称,要改写成 #[serde(rename_all(serialize = "ser_rename_method", deserialize = "de_rename_method"))]。

例如:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
#[serde(rename_all(serialize = "UPPERCASE"))]
struct Point {
    x: f64,
    y: f64,
}

fn main() {
    let p1 = Point {
        x: 7.0, y: 8.0
    };

    let json = serde_json::to_string_pretty(&p1).unwrap();

    println!("{json}");

    let p2: Point = serde_json::from_str("{\"x\": 7.0, \"y\": 8.0}").unwrap();

    println!("{p2:#?}");
}

运行结果如下:

{
  "X": 7.0,
  "Y": 8.0
}
Point {
    x: 7.0,
    y: 8.0,
}
反串行化时允许使用多个不一样的字段名称

替字段加上一个或多个 #[serde(alias = "new_alias_name")] 属性,在反串行化时就可以用多种不同的字段名称来对应到同一个字段。

例如:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Point {
    #[serde(alias = "a")]
    x: f64,
    #[serde(alias = "b")]
    y: f64,
}

fn main() {
    let p1 = Point {
        x: 7.0, y: 8.0
    };

    let json = serde_json::to_string_pretty(&p1).unwrap();

    println!("{json}");

    let p2: Point = serde_json::from_str("{\"a\": 7.0, \"b\": 8.0}").unwrap();

    println!("{p2:#?}");
}

运行结果如下:

{
  "x": 7.0,
  "y": 8.0
}
Point {
    x: 7.0,
    y: 8.0,
}
反串行化时拒绝不认识的字段

Serde 框架在预设情况下进行反串行化时,如果数据源有比目标的数据类型还要有更多的数据字段,Serde 框架会接受这样的来源。

例如:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Point {
    x: f64,
    y: f64,
}

fn main() {
    let p1 = Point {
        x: 7.0, y: 8.0
    };

    let json = serde_json::to_string_pretty(&p1).unwrap();

    println!("{json}");

    let p2: Point = serde_json::from_str("{\"x\": 7.0, \"y\": 8.0, \"z\": 9.0}").unwrap();

    println!("{p2:#?}");
}

运行结果如下:

{
  "x": 7.0,
  "y": 8.0
}
Point {
    x: 7.0,
    y: 8.0,
}

如果想要让反串行化的数据源的字段不比目标的数据类型还多的话,就要在该类型上加上 #[serde(deny_unknown_fields)] 属性。

例如:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
struct Point {
    x: f64,
    y: f64,
}

fn main() {
    let p1 = Point {
        x: 7.0, y: 8.0
    };

    let json = serde_json::to_string_pretty(&p1).unwrap();

    println!("{json}");

    let p2: Point = serde_json::from_str("{\"x\": 7.0, \"y\": 8.0, \"z\": 9.0}").unwrap();

    println!("{p2:#?}");
}

以上程序运行的时候会发生 panic,因为在反串行化时,来源的数据多了一个 z 字段。

平板化(flatten)字段

当字段的类型是别的结构体或是 HashMap、BTreeMap 等多字段结构的数据时,若想将它们的字段直接加进目前这层结构体之下来进行串行化与反串行化,就要在该字段上加上 #[serde(flatten)] 属性。

例如:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Point {
    x: f64,
    y: f64,
}

#[derive(Debug, Serialize, Deserialize)]
struct Size {
    width:  f64,
    height: f64,
}

#[derive(Debug, Serialize, Deserialize)]
struct Region {
    #[serde(flatten)]
    point: Point,
    #[serde(flatten)]
    size:  Size,
}

fn main() {
    let r1 = Region {
        point: Point {
            x: 7.0, y: 8.0
        },
        size:  Size {
            width: 100.0, height: 70.0
        },
    };

    let json = serde_json::to_string_pretty(&r1).unwrap();

    println!("{json}");

    let r2: Region = serde_json::from_str(&json).unwrap();

    println!("{r2:#?}");
}

运行结果如下:

{
  "x": 7.0,
  "y": 8.0,
  "width": 100.0,
  "height": 70.0
}
Region {
    point: Point {
        x: 7.0,
        y: 8.0,
    },
    size: Size {
        width: 100.0,
        height: 70.0,
    },
}
借用(borrowing)拥有权

有些类型,如 Cow 等可以保存一个实体,或者保存一个参考。预设进行反串行化处理时,会将反串行化的来源数据拷贝出新的实体来保存。

例如:

use std::borrow::Cow;

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Name<'a> {
    first_name: Cow<'a, str>,
    last_name:  Cow<'a, str>,
}

fn main() {
    let n1 = Name {
        first_name: Cow::Borrowed("Magic"), last_name: Cow::Borrowed("Len")
    };

    let json = serde_json::to_string_pretty(&n1).unwrap();

    println!("{json}");

    let n2: Name = serde_json::from_str(&json).unwrap();

    drop(json);

    println!("{n2:#?}");
}

注意以上程序第 22 行,我们将 json 变量所保存的字符串实体的拥有权拿走了,但是这个程序仍然可以成功编译并且被正常运行。这是因为预设在反串行化时,Cow 枚举的变体会是 Owned,因此反串行化来源数据会被另外拷贝一份来保存。

如果要避免拷贝,可以替这类类型的字段加上 #[serde(borrow)] 属性。

例如:

use std::borrow::Cow;

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Name<'a> {
    #[serde(borrow)]
    first_name: Cow<'a, str>,
    #[serde(borrow)]
    last_name:  Cow<'a, str>,
}

fn main() {
    let n1 = Name {
        first_name: Cow::Borrowed("Magic"), last_name: Cow::Borrowed("Len")
    };

    let json = serde_json::to_string_pretty(&n1).unwrap();

    println!("{json}");

    let n2: Name = serde_json::from_str(&json).unwrap();

    // drop(json);

    println!("Borrowed? {}", matches!(n2.first_name, Cow::Borrowed(_)));

    println!("{n2:#?}");
}

运行结果如下:

{
  "first_name": "Magic",
  "last_name": "Len"
}
Borrowed? true
Name {
    first_name: "Magic",
    last_name: "Len",
}

另外,#[serde(borrow)] 属性有个地方要注意的是,当要反串行化的字段的类型内有使用 #[serde(borrow)] 属性时,这个字段也必须要加上 #[serde(borrow)] 属性才能够正常编译。

例如:

use std::borrow::Cow;

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Name<'a, 'b> {
    #[serde(borrow)]
    first_name: Cow<'a, str>,
    last_name:  Cow<'b, str>,
}

#[derive(Debug, Serialize, Deserialize)]
struct Person<'a, 'b, 'c> {
    #[serde(borrow)]
    name:      Name<'a, 'b>,
    nick_name: Cow<'c, str>,
}

fn main() {
    let p1 = Person {
        name:      Name {
            first_name: Cow::Borrowed("Magic"), last_name: Cow::Borrowed("Len")
        },
        nick_name: Cow::Borrowed("Magic Len"),
    };

    let json = serde_json::to_string_pretty(&p1).unwrap();

    println!("{json}");

    let p2: Person = serde_json::from_str(&json).unwrap();

    println!("Is first_name borrowed? {}", matches!(p2.name.first_name, Cow::Borrowed(_)));

    println!("Is last_name borrowed? {}", matches!(p2.name.last_name, Cow::Borrowed(_)));

    println!("Is nick_name borrowed? {}", matches!(p2.nick_name, Cow::Borrowed(_)));

    println!("{p2:#?}");
}

运行结果如下:

{
  "name": {
    "first_name": "Magic",
    "last_name": "Len"
  },
  "nick_name": "Magic Len"
}
Is first_name borrowed? true
Is last_name borrowed? false
Is nick_name borrowed? false
Person {
    name: Name {
        first_name: "Magic",
        last_name: "Len",
    },
    nick_name: "Magic Len",
}

不过以上程序还有个比较好的写法,因为 Name 结构体的 last_name 字段实际上并不会去进行借用,但是如果直接在 Person 的 name 字段上加上 #[serde(borrow)] 属性,'b 的生命周期也会跟着被绑定上去。为了避免这个状况造成问题,最好手动指定泛型生命周期参数给 borrow 参数。

如下:

use std::borrow::Cow;

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Name<'a, 'b> {
    #[serde(borrow)]
    first_name: Cow<'a, str>,
    last_name:  Cow<'b, str>,
}

#[derive(Debug, Serialize, Deserialize)]
struct Person<'a, 'b, 'c> {
    #[serde(borrow = "'a")]
    name:      Name<'a, 'b>,
    nick_name: Cow<'c, str>,
}

fn main() {
    let p1 = Person {
        name:      Name {
            first_name: Cow::Borrowed("Magic"), last_name: Cow::Borrowed("Len")
        },
        nick_name: Cow::Borrowed("Magic Len"),
    };

    let json = serde_json::to_string_pretty(&p1).unwrap();

    println!("{json}");

    let p2: Person = serde_json::from_str(&json).unwrap();

    println!("Is first_name borrowed? {}", matches!(p2.name.first_name, Cow::Borrowed(_)));

    println!("Is last_name borrowed? {}", matches!(p2.name.last_name, Cow::Borrowed(_)));

    println!("Is nick_name borrowed? {}", matches!(p2.nick_name, Cow::Borrowed(_)));

    println!("{p2:#?}");
}
From 和 Into 特性

From 和 Into 是 Rust 编程语言内置的两个常用特性,可以快速地将一个类型的实体转成另一个类型的实体。如果一个有加上 Serialize 属性或是 Deserialize 属性的类型,有实作 From<FromType> 和 Into<IntoType> 特性,我们可以替其加上 #[serde(from = "FromType")] 或 #[serde(into = "IntoType")] 属性来间接去使用 FromType 或是 IntoType 实作的串行化或是反串行化的方式。

例如:

use std::borrow::Cow;

use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
struct Name<'a, 'b> {
    first_name: Cow<'a, str>,
    last_name:  Cow<'b, str>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(into = "Name")]
struct Person<'a, 'b, 'c> {
    name:      Name<'a, 'b>,
    nick_name: Cow<'c, str>,
}

impl<'a, 'b, 'c> From<Person<'a, 'b, 'c>> for Name<'a, 'b> {
    fn from(val: Person<'a, 'b, 'c>) -> Self {
        val.name
    }
}

fn main() {
    let p = Person {
        name:      Name {
            first_name: Cow::Borrowed("Magic"), last_name: Cow::Borrowed("Len")
        },
        nick_name: Cow::Borrowed("Magic Len"),
    };

    let json = serde_json::to_string_pretty(&p).unwrap();

    println!("{json}");

    let n: Name = serde_json::from_str(&json).unwrap();

    println!("{n:#?}");
}

运行结果如下:

{
  "first_name": "Magic",
  "last_name": "Len"
}
Name {
    first_name: "Magic",
    last_name: "Len",
}

类单元结构体(unit-like struct)和枚举

上面都是用一般结构体来做串行化与反串行化的动作,那如果是类单元结构体或是枚举呢?

类单元结构体的例子如下:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct UnitStruct;

fn main() {
    let json = serde_json::to_string_pretty(&UnitStruct).unwrap();

    println!("{json}");

    let n: UnitStruct = serde_json::from_str(&json).unwrap();

    println!("{n:#?}");
}

运行结果如下:

null
UnitStruct

所以类单元结构体其实就等于没有数据的意思?并不是,以上例子只是表示在 JSON 格式中,它代表 null 值而已。类单元结构体在 Serde 框架中还是有其被应用的地方,通常是用来直接以类单元结构体的名称来表示某个名称。

而枚举会有比较多需要说明的东西,例子如下:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
enum Week {
    Monday,
    Tuesday,
    Wednesday,
    Thursday,
    Friday,
    Saturday,
    Sunday,
}

fn main() {
    let json = serde_json::to_string_pretty(&Week::Friday).unwrap();

    println!("{json}");

    let w: Week = serde_json::from_str(&json).unwrap();

    println!("{w:#?}");
}

运行结果如下:

"Friday"
Friday

枚举的单元变体(Unit Variant),在 Serde 框架中通常会直接以变体的名称来表示某个名称。如果我们要将变体名称存到某个字段的话,可以替枚举加上 #[serde(tag = "field")] 属性。

例如:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
#[serde(tag = "WeekDay")]
enum Week {
    Monday,
    Tuesday,
    Wednesday,
    Thursday,
    Friday,
    Saturday,
    Sunday,
}

fn main() {
    let json = serde_json::to_string_pretty(&Week::Friday).unwrap();

    println!("{json}");

    let w: Week = serde_json::from_str(&json).unwrap();

    println!("{w:#?}");
}

运行结果如下:

{
  "WeekDay": "Friday"
}
Friday

接着来看看枚举的变体非单元变体时的情况。

例如:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
enum IP {
    IPv4(String),
    IPv6(String),
}

fn main() {
    let json = serde_json::to_string_pretty(&IP::IPv4("110.26.73.83".to_string())).unwrap();

    println!("{json}");

    let ip: IP = serde_json::from_str(&json).unwrap();

    println!("{ip:#?}");
}

运行结果如下:

{
  "IPv4": "110.26.73.83"
}
IPv4(
    "110.26.73.83",
)

此时的变体名称就会变成字段名称,如果不想要让枚举用变体名称当字段名称,可以替枚举加上 #[serde(untagged)] 属性。

例如:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
#[serde(untagged)]
enum IP {
    IPv4(String),
    IPv6(String),
}

fn main() {
    let json = serde_json::to_string_pretty(&IP::IPv6("::ffff:110.26.73.83".to_string())).unwrap();

    println!("{json}");

    let ip: IP = serde_json::from_str(&json).unwrap();

    println!("{ip:#?}");
}

运行结果如下:

"::ffff:110.26.73.83"
IPv4(
    "::ffff:110.26.73.83",
)

使用这个 #[serde(untagged)] 属性时要特别注意在反串行化时变体的匹配,Serde 框架会选择使用最先匹配成功的变体。像是上面这个例子,虽然我们使用 IPv6 变体来做串行化,但反串行化出来的变体为 IPv4。

我们也可以把枚举的变体名称和变体的结构分两个字段来保存,只要替枚举加上 #[serde(tag = "variant_name_field", content = "variant_field")] 属性。

例如:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
#[serde(tag = "type", content = "ip")]
enum IP {
    IPv4(String),
    IPv6(String),
}

fn main() {
    let json = serde_json::to_string_pretty(&IP::IPv6("::ffff:110.26.73.83".to_string())).unwrap();

    println!("{json}");

    let ip: IP = serde_json::from_str(&json).unwrap();

    println!("{ip:#?}");
}

运行结果如下:

{
  "type": "IPv6",
  "ip": "::ffff:110.26.73.83"
}
IPv6(
    "::ffff:110.26.73.83",
)