Overview

serde是为rust数据结构高效的序列化和反序列化的框架,其他的大部分语言使用运行时的反射技术来序列化数据,Serde是建立在Rust高效的trait生态系统,一个实现trait Serialize和trait Deserialize的数据结构知道如何序列化和反序列化它自己(或者使用serde的derive属性在编译时自动生成实现),这避免了任何反射的开销和任何运行时类型推断的信息,实际上,在大多数场景下数据结构和数据格式的交互能够完全的被Rust编译器优化.Serde支持多种格式的序列化,甚至能够自行增加格式(这也是被称为框架的原因)

Attributes

Atrributes用于定制化通过Serde的derive产生的Serialize和Deserialize实现,存在三种attributes的策略:

Container Attributes

应用于struct和enum声明

Variant Attributes

应用于enum变体

Field Attributes

应用于struct或enum变体的字段

Container attributes

#[serde(rename = "name")]

序列化或反序列化通过给定的名字而不是在Rust中的名称.允许为序列化和反序列化指定独立的名称

#[serde(rename(serialize = "ser_name"))]

#[serde(rename(deserialize = "deser_name"))]

#[serde(rename(serialize = "ser_name", deserailize = "deser_name"))]

#[serde(rename_all = "...")]

重命名所有的字段(如果是结构体)或变体(如果是枚举体),通过给定的情况转换,可能的情况有 "lowercase","UPPERCASE","PascalCase","camelCase","snake_case","SCREAM_SNAKE_CASE", "kebab-case", "SCREAM-KABAB-CASE" 允许为序列化和反序列化指定不同的情况.

#[serde(rename_all(serialize = "..."))]

#[serde(rename_all(deserialize = "..."))]

#[serde(rename_all(serialize = "...", deserialize = "..."))]

#[serde(deny_unknown_fields)]

在反序列化时遭遇到未知字段时总是反映错误,当这个属性不存在时,对于自描述的格式JSON默认未知的字段将被忽略.

#[serde(tag = "type")]

使用内部被标记的enum表示这个enum

#[serde(tag = "t", content = "c")]

使用相邻的被标记的enum表示这个enum,为tag和content通过给定的字段名称.

#[serde(untagged)]

使用未标记的enum表示这个enum

#[serde(bound = "T: MyTrait")]

Where-caluse对于Serialize和Deserialize实现,这将替换所有Serde推断的任何trait 限定,允许为序列化和反序列化指定独立的限定.

#[serde(bound(serialize = "MySeTrait: T"))]

#[serde(bound(deserialize = "MyDeTrait: T"))]

#[serde(bound(serialize = "MySeTrait: T", deserialize = "MyDeTrait: T"))]

#[serde(default)]

当反序列化,任何错过的字段将被结构体的Default实现填充,只允许用在结构体.

#[serde(default = "path")]

当反序列化时,任何错过的字段被给定函数或方法返回的对象填充,函数必须是可调用的 fn() -> T ,比如 default = "my_default" 将会触发 my_default() , default = "SomeTrait::some_default" 将会触发 SomeTrait::some_default() ,这个只能用在结构体.

#[serde(remote = "...")]

这个被用于Serialize和Deserialize的派生.

#[serde(transparent)]

序列化和反序列化一个有一个字段的newtype struct或braced struct明确的和序列化和反序列化本身相同,和#[repr(transparent)].

#[serde(from = "FromType")]

反序列化这个类型通过反序列化到 FromType ,然后转换,这个类型必须实现From,FromType必须实现Deserialize.

#[serde(try_from = "FromType"]

反序列化这个类型通过反序列化到FromType,然后转换,这个类型必须实现TryFrom,错误类型实现Display,FromType必须实现Deserialize.

#[serde(into = "IntoType")]

序列化这个类型通过将其转换为指定的IntoType然后序列化它,这个类型必须实现Clone和Into,而且IntoType必须实现Serialize.

#[serde(crate = "...")]

指定一个路径到 serde 包实例使用当引用Serde API产生代码,这个通常只用于当触发重新导入Serde从不同包公有的macros的派生.

Variant Attributes

#[serde(rename = "name")]

序列化或反序列化这个variant使用给定的name而不是Rust中的name. 允许为序列化或反序列化指定独立的名字

#[serde(rename(serialize = "ser_name"))]

#[serde(rename(deserialize = "de_name"))]

#[serde(rename(serialize = "ser_name", deserialize = "de_name"))]

#[serde(alias = "name")]

反序列化通过给定的name或Rust中的name.可能被重复在同一个变体指定多个name.

#[serde(rename_all = "...")]

重命名这个结构体的所有variant通过给定的情况case转换,case可以为以下值: "lowercase","UPPERCASE", "snake_case", "PascalCase", "camelCase", "SCREAM_SNAKE_CASE", "kebab-case", "STREAM-KEBAB-CASE" . 可以独立的为序列化和反序列化指定名字

#[serde(rename_all(serialize = "..."))]

#[serde(rename_all(deserialize = "..."))]

#[serde(rename_all(serialize = "...", deserialize = "..."))]

#[serde(skip)]

序列化和反序列化跳过该variant

#[serde(serializing_skip)]

不会序列化该variant,试图序列化该variant会被认为是错误.

#[serde(deserializing_skip)]

不会反序列化该variant,试图反序列化该variant会被认为是错误.

#[serde(serialize_with = "path")]

序列化variant使用不同于Serialize实现的函数,给定的函数必须像 
    fn<S>(&FIELD0, &FIELD1, ..., S) -> Result<S::Ok, S::Error> where S: Serializer
,尽管可能生成超过FIELD{n}类型,Variants使用serialize_with而不要求能够derive Serialize.Field{n}存在variant的每个字段,因此单元variant只有参数 S ,turple/struct有每个字段的参数.

#[serde(deserialize_with = "path")]

反序列化该variant使用特定函数而不是Deserialize的实现,给定的函数必须是形如 
    fn<'de, D>(D) -> Result<FIELDS, D::Error> where D: Deserializer<'de>
,尽管通用的超过FIELDS的元素,Variant使用deserialize_with,不被要求derive Deserialize.FIELDS是variant所有字段的turple.

#[serde(with = "module")]

serialize_with和deserialize_with的结合,Serde将会使用$module::serialize作为serialize_with,使用$module::deserialize作为deserialize_with函数.

#[serde(bound = "MyTrait::T")]

Where-caluse对于Serialize和/或Deserialize实现,这个替代Serde对于当前variant推断的限定,可以独立的指定序列化和反序列化的限定:

#[serde(bound(serialize = "MySeTrait::T"))]

#[serde(bound(deserialize = "MyDeTrait::T"))]

#[serde(bound(serialize = "MySeTrait::T", deserialize = "MyDeTrait::T"))]

#[serde(borrow)]和#[serde(borrow = "'a + 'b + ...")]

通过零复制的反序列化由反序列化器借用字段的数据,只被允许在newtype variant.(只有一个字段的turple variant).

#[serde(other)]

反序列化这个variant,如果该enum tag不同于其他变体内容在该enum中,只允许内部标记的单元variant或者连续的被标记的enum.比如,如果我们有内部被标记的enum,通过#[serde(tag = "variant")],包含variants A,B和Unknown,由serde(other)标记,Unknown字段将会被反序列化任何时候,无论输入的"variant"字段是A还是B.

Field Attributes

#[serde(rename = "name")]

序列化和反序列使用给定的名字而不是Rust的name,允许为序列化和反序列化指定独立的name

#[serde(rename(serialize = "se_name"))]

#[serde(rename(deserialize = "de_name"))]

#[serde(rename(serialize = "se_name", deserialize = "de_name"))]

#[serde(alias = "name")]

反序列化该字段通过给定的名字或Rust的name,为相同的字段指定多个可能的name,可能会被重复.

#[serde(default)]

如果该值在反序列时不存在,使用Default::default();

#[serde(default = "path")]

如果反序列化时该值不存在,调用函数得到默认值,给定的函数必须形如: fn() -> T ,比如