serde 几乎是目前 Rust 生态中最常用的序列化与反序列化库了.

Golang 实现

作为一个 Golang 程序员来说, 免不了要对比一下.

Golang 官方库直接实现了 json 的序列化和反序列化.

对于序列化和反序列化, Go 都是用一个简单的接口interface表示:

// https://pkg.go.dev/encoding/json#Marshaler
type Marshaler interface {
	MarshalJSON() ([]byte, error)
}

// https://pkg.go.dev/encoding/json#Unmarshaler
type Unmarshaler interface {
	UnmarshalJSON([]byte) error
}

注意这个接口只是针对 JSON 的, 接口名后缀JSON 是有意义的. 因为对于同一个数据类型, 它可能需要实现很多种格式的序列化, 比如 yaml, toml 等. 如果按这个命名来, 它可能是: MarshalYaml, MarshalToml

看上去很简单是吧? 嗯, 是挺简单的. 但是其实这里是有坑的, 或者说, 实现的时候一定要注意一些细节.

Marshaler 的实现一定要用普通的receiver, (即不要只实现 pointer receiver的), 因为pointer only 会导致如果是非指针形式的时候, 在序列化的时候无法调用到我们自己实现的方法.

Unmarshaler 的实现一定要用 pointer receiver, 因为是解析数据到自身, 因此一定要修改自身, 不可修改是没有意义的.

举个例子, 假设我们想要JSON序列化一个自定义的int类型(主要用于作为enum的功能来用)为某些特定的string(主要用于JSON结构化日志的时候, 阅读更友好):

type HideType int

const (
	HideTypeNone     HideType = 0
	HideTypeLocation HideType = 1 << 0
	HideTypeAge      HideType = 1 << 1
	HideTypeSex      HideType = 1 << 2
	HideTypeNation   HideType = 1 << 3
)

var _hideTypeValuesMap = map[HideType]string{
	HideTypeNone:     "none",
	HideTypeLocation: "location",
	HideTypeAge:      "age",
	HideTypeSex:      "sex",
	HideTypeNation:   "nation",
}

var _hideTypeValueToType = map[string]HideType{
	"none":     HideTypeNone,
	"location": HideTypeLocation,
	"age":      HideTypeAge,
	"sex":      HideTypeSex,
	"nation":   HideTypeNation,
}

func (ht HideType) String() string {
	if val, ok := _hideTypeValuesMap[ht]; ok {
		return val
	}
	return "unknown"
}

// MarshalJSON impl Marshaler interface https://pkg.go.dev/encoding/json#Marshaler
func (ht HideType) MarshalJSON() ([]byte, error) {
	return []byte(fmt.Sprintf(`"%v"`, ht.String())), nil
}

// UnmarshalJSON impl Unmarshaler interface
// https://pkg.go.dev/encoding/json#Unmarshaler
func (ht *HideType) UnmarshalJSON(rawJSON []byte) error {
	htStr := bytes.Trim(rawJSON, `"`)
	if htInt, ok := _hideTypeValueToType[string(htStr)]; ok {
		*ht = htInt
		return nil
	}
	return fmt.Errorf("parse into HideType failed, unknown HideType: %v", htStr)
}

没错, 整个实现非常简单, 对于 MarshalJSON() 我们只需要返回我们想要返回的 JSON string 即可. 注意这里一定要返回合法的JSON string类型. 这里使用了 "%v", 而没有使用 %q, 主要是因为在我们的使用场景(类似enum)下100%确定不会有需要再次转义, 如果不确定的场景, 最好还是要用 %q.

UnmarshalJSON 我们由于确定输入是合法并且格式一定是特定的, 因此处理上也非常简单.不需要考虑过多.

Rust 实现

当然, serde 本身就可以处理这种序列化, 我们只需要加上#[derive(Serialize, Deserialize, Debug)] 即可. 这里特意用的自定义方式实现, 主要是从学习的角度.

序列化实现比较简单, Rust 里面我们只需要实现 Serialize trait 即可:

pub trait Serialize {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer;
}

反序列化相对来说麻烦一些. 不像 Go 里面简单粗暴, 实现细节交给用户来处理, serde 里面需要按照 serde data model 来交换数据.

单从 Deserialize trait 来看, 好像反序列化也差不多. 但是实际上它还需要一个 Vistor trait

pub trait Deserialize<'de>: Sized {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>;
}

从语法上来说, Visitor trait 只有一个 expecting 方法是必须实现的, 但是实际使用中我们要根据具体的JSON 数据类型选择实现其它方法. 比如在我们这个例子中, 我们可以明确的确定, 我们收到的 JSON 数据是一个字符串类型的, 因此只需要visit_str, 注意 visit_str 比起 Golang 里面要用户手动解析 JSON 数据, serde 里面已经默认把数据给我们解析出来了, 所以, 当输入是 "foo" 的时候, 在 serde 里面我们visit_str得到的是 foo, 而在 Go 里面我们由于得到的是 "foo", 因此还要自行处理外面的引号.

最后, 我们要将这个实现了 Visitor trait 的类型, 绑定到我们要反序列化的类型的Deserialize trait 上面: deserializer.deserialize_str(HideTypeVisitor)

pub trait Visitor<'de>: Sized {
    /// The value produced by this visitor.
    type Value;

    /// Format a message stating what data this Visitor expects to receive.

    fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result;
    /// ...
}
use std::collections::HashMap;
use std::fmt;
use serde::{Serialize, Deserialize, Serializer, Deserializer};

use serde::de::{Error, Unexpected, Visitor};

use once_cell::sync::Lazy;

[derive(Copy, Clone, PartialEq, Eq, Hash, Debug)]
enum HideType {
    HideTypeNone = 0,
    HideTypeLocation = 1 << 0,
    HideTypeAge = 1 << 1,
    HideTypeSex = 1 << 2,
    HideTypeNation = 1 << 3,
}

static FILTER_TYPE_TO_NAME: [(HideType, &str); 5] = [
    (HideType::HideTypeNone, "none"),
    (HideType::HideTypeLocation, "location"),
    (HideType::HideTypeAge, "age"),
    (HideType::HideTypeSex, "sex"),
    (HideType::HideTypeNation, "nation"),
];

static TYPE_STR_MAP: Lazy<HashMap<HideType, &str>> = Lazy::new(|| {
    let mut m = HashMap::new();
    for (k, v) in FILTER_TYPE_TO_NAME.iter() {
        m.insert(*k, *v);
    }
    m
});

static STR_TYPE_MAP: Lazy<HashMap<&str, HideType>> = Lazy::new(|| {
    let mut m = HashMap::new();
    for (k, v) in FILTER_TYPE_TO_NAME.iter() {
        m.insert(*v, *k);
    }
    m
});

impl Serialize for HideType {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
        where
            S: Serializer,
    {
        return TYPE_STR_MAP.get(self).unwrap().serialize(serializer);
    }
}

struct HideTypeVisitor;

impl<'de> Visitor<'de> for HideTypeVisitor {
    type Value = HideType;

    fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
        formatter.write_str(r#"a string in one of: none, location, age, sex, nation"#)
    }

    fn visit_str<E>(self, v: &str) -> Result<Self::Value, E>
        where
            E: Error,
    {
        match STR_TYPE_MAP.get(v) {
            Some(t) => Ok(*t),
            None => Err(E::invalid_value(Unexpected::Str(v), &self)),
        }
    }
}

impl<'de> Deserialize<'de> for HideType {
    fn deserialize<D>(deserializer: D) -> Result<HideType, D::Error>
        where
            D: Deserializer<'de>,
    {
        deserializer.deserialize_str(HideTypeVisitor)
    }
}

当然, 这里也并不一定要用到 hashmap, 直接用 match 处理从类型到 string的转换也是可以的. 不过通过 hashmap 的方式会比较自然, 并且我们不再需要手动去维护一个正向和反向的 map 了.

总体来说, Golang 里面实现自定义序列化和反序列化, 比较直接和简单粗暴. 整个接口的定义也非常简单. 而 Rust 里的 serde 则有很多功能和功能. 首先你一定要了解的是 serde data model. 相比于 Golang 里面直接用 Go 的类型, 并且其默认实现直接将 Go 的类型, 比如 []byte 绑定到其实现上 ([]byte类型的数据在序列化后会被Golang转换成base64的表现形式). serde 里面是通过 serde data model 来实现数据映射的. 而 serde 本身是一个框架, 并不负责实现, 其实现由扩展提供, 如 serde_json, serde_yaml 等. 所以 serde 的好处是, trait 是统一的, 而 Go 里面则是各实现各的, 比如官方实现了 JSON, 第三方实现了 YAML 等.

比如 yaml:

UnmarshalYAML(value *Node) error

官方 JSON:

UnmarshalJSON([]byte) error

可以看到, 虽然命名和参数样子差不多, 但是实际上还是不一样, 当然, 官方也并没有任何规范说明要一样. 实际上也不能做成一样, 假设 json 和 yaml 的 Unmarshaler interface 都定义为 Unmarshal([]byte) error, 由于 Go 的 interface 是鸭子类型, 这会导致错误的断言.

另外一点就是, 由于 serde 是一个框架, 而我们的自定义序列化也是映射到框架的数据模型, 因此是跟语言(json, yaml, toml 等)无关的. 可以做到一次定义, 到处运行. 而 Golang 的自定义序列化一定是针对某个类型的(比如 JSON), 上面的示例, 如果换成 yaml, 还得重新实现一次, 而 serde 则不存在这个问题.

2022-07-27 补充:

还有一点就是序列化字段重命名, golang 是通过给 struct 打 tag 的方式, 不同的语言需要不同的tag, 如何解析这个 tag 是序列化mod所负责的工作, 比如 json 用的是 `json`, yaml 用的是 `yaml`, 而数据库相关的 gorm 用的是 `gorm`, 因此从这一点来说, golang 的 struct tag 并不是专门用于序列化. 还可以用在其它地方.

而 Rust 的字段重命名是在框架层面的, 也就是说, 指定了rename后, 无论是 json 还是 yaml 都会按照这个来, 优点是不必要重复地添加很多 tag. (对比: golang 一个 struct 要同时加上 json, yaml, toml 甚至 bson 的 tag, 就显得很没有可读性, 但是如果你不加, 有些字段可能序列化出来不是你要的结果, 比如 ID 在 mongodb 里面要用 `_id` )

Refs

https://pkg.go.dev/encoding/json#Marshaler

https://pkg.go.dev/encoding/json#Unmarshaler

https://serde.rs/data-model.html

https://serde.rs/impl-serialize.html

https://serde.rs/impl-deserialize.html