用 Rust 从零实现序列化框架:serde 的核心只有两个 trait
#[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 上。"