返回文章列表

用 Rust 从零实现序列化框架:serde 的核心只有两个 trait

381 字·3 分钟阅读
Rust从零造轮子序列化

#[derive(Serialize, Deserialize)] 大概是 Rust 里最"魔法"的一行代码。加个标注,JSON、YAML、bincode、MessagePack 全都能转。

魔法感来自两点:派生宏在编译期生成了大量代码,以及这套抽象设计得足够好,好到你看不出它是怎么解耦的。

这篇不写派生宏(那是 proc-macro 的活),而是把它剥到只剩两个 trait,看看数据是怎么从一个结构体流到 JSON 字符串的。


先看 serde 的设计目标

设计目标只有一句话:序列化格式和数据结构必须解耦。

具体说:

  • 一个 User 结构体,要能序列化成 JSON、YAML、bincode
  • 一个 JSON 解析器,要能反序列化成任意 T

如果为每种组合写一份代码,就是 M×N 的爆炸。serde 的解法是用中间层:

结构体 <--Serialize--> Serializer <---> 格式实现

Serialize 只管"我有哪些字段、什么类型";Serializer 只管"你怎么把这些数据写出去"。两边互不认识,中间靠 trait 连接。

trait 一:Serialize

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

关键在这个泛型参数 S:它是静态分发的。所以 User::serialize::<JsonSerializer> 和 User::serialize::<BincodeSerializer> 在编译后是两份独立的代码,没有虚函数开销。这就是 serde 快的原因之一。

实现自己的 Serialize:

struct User {
    id: u64,
    name: String,
    tags: Vec<String>,
}
 
impl Serialize for User {
    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        // 声明"我是一个有三个字段的结构体"
        let mut obj = s.serialize_struct("User", 3)?;
        obj.serialize_field("id", &self.id)?;
        obj.serialize_field("name", &self.name)?;
        obj.serialize_field("tags", &self.tags)?;
        obj.end()
    }
}

注意 s.serialize_struct 返回的是一个 SerializeStruct(一个复合序列化器)。这是 serde 设计的精髓:分两步走——先声明容器,再逐个填字段。

为什么要分两步?因为不同格式对"知道结构体有几个字段"这件事的需求不同:

  • JSON:无所谓,写 { 就行
  • bincode:需要预知字段数来分配
  • MessagePack:可以顺序写,也可以带长度

这个两阶段接口同时满足了所有格式。

serialize_struct 的第二个参数(字段数)看起来是冗余的,它其实是给那些"必须预知长度"的二进制格式留的接口。

trait 二:Serializer

Serializer 的接口很长,因为它要覆盖所有 Rust 类型。但结构非常规整:

pub trait Serializer {
    type Ok;
    type Error: std::error::Error;
 
    fn serialize_bool(self, v: bool) -> Result<Self::Ok, Self::Error>;
    fn serialize_i64(self, v: i64) -> Result<Self::Ok, Self::Error>;
    fn serialize_u64(self, v: u64) -> Result<Self::Ok, Self::Error>;
    fn serialize_f64(self, v: f64) -> Result<Self::Ok, Self::Error>;
    fn serialize_str(self, v: &str) -> Result<Self::Ok, Self::Error>;
    fn serialize_none(self) -> Result<Self::Ok, Self::Error>;
    fn serialize_some<T: Serialize + ?Sized>(self, v: &T) -> Result<Self::Ok, Self::Error>;
    fn serialize_seq(self, len: Option<usize>) -> Result<Self::SerializeSeq, Self::Error>;
    fn serialize_map(self, len: Option<usize>) -> Result<Self::SerializeMap, Self::Error>;
    fn serialize_struct(self, name: &str, len: usize) -> Result<Self::SerializeStruct, Self::Error>;
    // ... 还有 tuple、enum、bytes 等
}

这里有个统一的模式:标量直接序列化,复合类型返回一个"子序列化器"。

pub trait SerializeSeq {
    type Ok;
    type Error;
    fn serialize_element<T: Serialize + ?Sized>(&mut self, value: &T) -> Result<(), Self::Error>;
    fn end(self) -> Result<Self::Ok, Self::Error>;
}
 
pub trait SerializeStruct {
    type Ok;
    type Error;
    fn serialize_field<T: Serialize + ?Sized>(&mut self, key: &'static str, value: &T) -> Result<(), Self::Error>;
    fn end(self) -> Result<Self::Ok, Self::Error>;
}

这种"每个类型一个 trait"的写法看起来啰嗦,但它让派生宏只需按类型调用对应方法,不用做类型判断。

实现一个简单的 JSON Serializer

现在自己实现一个。目标:把 User 序列化成 JSON 字符串。

pub struct JsonSerializer {
    out: String,
}
 
pub struct JsonError(String);

标量实现很直接:

impl serde::Serializer for &mut JsonSerializer {
    type Ok = ();
    type Error = JsonError;
    type SerializeSeq = JsonSeq<'a>;   // 省略生命周期细节
    type SerializeStruct = JsonStruct<'a>;
    // ...
 
    fn serialize_u64(self, v: u64) -> Result<(), JsonError> {
        self.out.push_str(&v.to_string());
        Ok(())
    }
 
    fn serialize_str(self, v: &str) -> Result<(), JsonError> {
        self.out.push('"');
        for c in v.chars() {
            match c {
                '"' => self.out.push_str("\\\""),
                '\\' => self.out.push_str("\\\\"),
                '\n' => self.out.push_str("\\n"),
                c if (c as u32) < 0x20 => {
                    self.out.push_str(&format!("\\u{:04x}", c as u32));
                }
                c => self.out.push(c),
            }
        }
        self.out.push('"');
        Ok(())
    }
}

字符串转义必须逐字符处理。 不转义的控制字符会产生非法 JSON,是"看起来能用"的经典陷阱。

结构体序列化器:

pub struct JsonStruct<'a> {
    ser: &'a mut JsonSerializer,
    first: bool,
}
 
impl<'a> serde::ser::SerializeStruct for JsonStruct<'a> {
    type Ok = ();
    type Error = JsonError;
 
    fn serialize_field<T: serde::Serialize + ?Sized>(
        &mut self,
        key: &'static str,
        value: &T,
    ) -> Result<(), JsonError> {
        if !self.first {
            self.ser.out.push(',');
        }
        self.first = false;
 
        // key 永远是合法标识符,但仍要按字符串转义
        self.ser.serialize_str(key)?;
        self.ser.out.push(':');
        value.serialize(&mut *self.ser)?;
        Ok(())
    }
 
    fn end(self) -> Result<(), JsonError> {
        self.ser.out.push('}');
        Ok(())
    }
}

serialize_struct 的入口:

    fn serialize_struct(
        self,
        _name: &'static str,
        _len: usize,
    ) -> Result<JsonStruct<'_>, JsonError> {
        self.out.push('{');
        Ok(JsonStruct { ser: self, first: true })
    }

跑起来:

let user = User { id: 1, name: "king".into(), tags: vec!["rust".into()] };
let mut ser = JsonSerializer { out: String::new() };
user.serialize(&mut ser).unwrap();
println!("{}", ser.out);
// {"id":1,"name":"king","tags":["rust"]}

不到一百行,就复刻了 serde_json 的核心路径。 剩下的都是类型覆盖和性能优化。

反序列化:Visitor 模式

反序列化要难得多,因为方向反了:从"无类型的数据"构造"有类型的结构"。

JSON 里一个数字是 1,它可能是 u8、u64、i32、f64、Duration 的秒数……解析器不知道目标类型。

serde 的解法是 Visitor 模式——让"类型"主动告诉"解析器"它能接受什么。

pub trait Visitor<'de>: Sized {
    type Value;
 
    fn visit_u64<E: Error>(self, v: u64) -> Result<Self::Value, E> {
        Err(E::invalid_type(Unexpected::Unsigned(v), &self))
    }
 
    fn visit_str<E: Error>(self, v: &str) -> Result<Self::Value, E> {
        Err(E::invalid_type(Unexpected::Str(v), &self))
    }
 
    fn visit_seq<A: SeqAccess<'de>>(self, seq: A) -> Result<Self::Value, E> {
        Err(E::invalid_type(Unexpected::Seq, &self))
    }
 
    // ... 每个 JSON 类型一个方法
}

默认实现全是"报错",实现者只覆盖自己关心的类型。比如一个 u64 的 Visitor:

struct U64Visitor;
 
impl<'de> Visitor<'de> for U64Visitor {
    type Value = u64;
 
    fn visit_u64<E: Error>(self, v: u64) -> Result<u64, E> {
        Ok(v)
    }
 
    // 宽松一点:也接受字符串形式的数字 "123"
    fn visit_str<E: Error>(self, v: &str) -> Result<u64, E> {
        v.parse().map_err(E::custom)
    }
}

Deserialize trait 就负责"提供 Visitor":

pub trait Deserialize<'de>: Sized {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>;
}
 
impl<'de> Deserialize<'de> for u64 {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<u64, D::Error> {
        d.deserialize_u64(U64Visitor)
    }
}

注意这个调用方向:先调用 deserialize_u64(进入格式层),格式层准备好数据后,回调 U64Visitor::visit_u64(回到类型层)。

反序列化比序列化难,因为它是"双向对话":类型层说"我能接受 u64",格式层说"这里有个 123,给你",中间还可能发生类型转换。

这个模式的好处是扩展性:想支持一个新的目标类型,只需要写它的 Visitor,不用改任何格式实现。想支持一个新格式,只需要实现 Deserializer 并调用 visitor。

实战:反序列化的路径追踪

用一个例子把整条路径串起来。目标:

#[derive(Deserialize)]
struct Config {
    port: u16,
}

解析 {"port": 8080}:

1. Config::deserialize(JsonDeserializer)
2. -> deserialize_struct("Config", ["port"])
3. JSON 解析器读到 '{',开始遍历 key
4. 匹配到 "port" 字段 -> 调用 u16::deserialize(子 deserializer)
5. -> deserialize_u16(U16Visitor)
6. JSON 解析器读到 8080 -> 调用 U16Visitor::visit_u64(8080)
7. 检查 8080 <= u16::MAX -> 返回 Ok(8080)
8. 组装成 Config { port: 8080 }

整个过程中,JSON 解析器完全不知道 Config 长什么样,它只知道"遍历 map,把值交给 visitor"。

派生宏做了什么

最后回答开头那个问题:#[derive(Serialize)] 生成了什么?

它生成了上文的 impl Serialize,而且针对每个字段:

// 展开后大致是这样
impl Serialize for User {
    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        let mut obj = s.serialize_struct("User", 3)?;
        obj.serialize_field("id", &self.id)?;
        obj.serialize_field("name", &self.name)?;
        obj.serialize_field("tags", &self.tags)?;
        obj.end()
    }
}

没有反射,没有运行期类型查询——派生宏只是在编译期把这段样板代码写出来。 这就是 serde 能做到"零运行时开销"的根本原因。

结论

把 serde 拆开,它其实很简单:

Serialize 描述"我有什么",Serializer 描述"怎么写",中间靠 serialize_struct 这类两阶段接口解耦;反序列化靠 Visitor 模式让类型层和格式层对话。

理解这套设计之后,你会发现自己写序列化不再是"调 API",而是能回答:"为什么加一个新格式不用改结构体?因为解耦点在 trait 上。"