2.3. API设计原则之不意外性(unsurprising) Pt.3实现serde下的Serialize和Deserialize trait、不建议实现Copy trait2.3.1. 建议实现serde下的Serialize和Deserializetraitserde是Rust中用于序列化serialization和反序列化deserialization的核心库-序列化Serialization把Rust结构体或枚举转换为JSON、YAML等格式的字符串或二进制数据。-反序列化Deserialization从JSON、YAML等格式的字符串或二进制数据解析回Rust结构体或枚举。Serialize和Deserialize都是serde库下的trait。SerializetraitSerializetrait允许一个类型转换为可序列化的数据格式如JSON、YAML、TOML。其主要方法有-serialize_bool-serialize_i32-serialize_str-serialize_struct这些是Serialize实现会调用的Serializer及相关trait 上的方法Serializetrait 本身只要求实现serialize。其定义是pub trait Serialize { fn serializeS(self, serializer: S) - ResultS::Ok, S::Error where S: Serializer; }我们用一个例子来介绍如何手动实现Serializetraituse serde::ser::{Serialize, SerializeStruct, Serializer}; struct Point { x: i32, y: i32, } impl Serialize for Point { fn serializeS(self, serializer: S) - ResultS::Ok, S::Error where S: Serializer, { let mut state serializer.serialize_struct(Point, 2)?; state.serialize_field(x, self.x)?; state.serialize_field(y, self.y)?; state.end() } }serializer.serialize_struct(Point, 2)?创建一个结构体序列化对象2 代表字段数量state.serialize_field(x, self.x)?依次序列化结构体字段state.end()结束序列化DeserializetraitDeserializetrait允许从各种数据格式解析Rust类型。其主要方法有-deserialize_bool-deserialize_i32-deserialize_string-deserialize_struct这些是Deserialize实现通过Visitor驱动的Deserializer及相关trait 上的方法Deserializetrait 本身只要求实现deserialize。其定义是pub trait Deserializede: Sized { fn deserializeD(deserializer: D) - ResultSelf, D::Error where D: Deserializerde; }deserialize方法的作用是使用deserializer从数据格式解析Rust类型我们用一个例子来介绍如何手动实现Deserializetraituse serde::de::{self, Deserialize, Deserializer, Visitor, MapAccess}; use std::fmt; struct Point { x: i32, y: i32, } implde Deserializede for Point { fn deserializeD(deserializer: D) - ResultSelf, D::Error where D: Deserializerde, { struct PointVisitor; implde Visitorde for PointVisitor { type Value Point; fn expecting(self, formatter: mut fmt::Formatter) - fmt::Result { formatter.write_str(a struct Point with fields x and y) } fn visit_mapM(self, mut map: M) - ResultPoint, M::Error where M: MapAccessde, { let mut x None; let mut y None; while let Some(key) map.next_key::String()? { match key.as_str() { x x Some(map.next_value()?), y y Some(map.next_value()?), _ {} } } let x x.ok_or_else(|| de::Error::missing_field(x))?; let y y.ok_or_else(|| de::Error::missing_field(y))?; Ok(Point { x, y }) } } deserializer.deserialize_struct(Point, [x, y], PointVisitor) } }PointVisitor结构体用于解析JSON字段visit_map解析x和y的值确保字段存在使用#[derive(Serialize, Deserialize)]标注自动实现Serialize和Deserialize手动实现Serialize和Deserialize非常繁琐通常我们会使用serde_derive宏use serde::{Serialize, Deserialize}; #[derive(Serialize, Deserialize, Debug)] struct Point { x: i32, y: i32, } fn main() { let p Point { x: 10, y: 20 }; let serialized serde_json::to_string(p).unwrap(); println!(Serialized: {}, serialized); // {x:10,y:20} let deserialized: Point serde_json::from_str(serialized).unwrap(); println!(Deserialized: {:?}, deserialized); // Point { x: 10, y: 20 } }使用了Serialize和Deserialize的例子use serde::{Serialize, Deserialize}; use serde_json; #[derive(Serialize, Deserialize, Debug)] struct User { name: String, age: u32, } fn main() { let user User { name: Alice.to_string(), age: 30, }; // 序列化 let json_str serde_json::to_string(user).unwrap(); println!(Serialized JSON: {}, json_str); // 反序列化 let deserialized: User serde_json::from_str(json_str).unwrap(); println!(Deserialized: {:?}, deserialized); }输出Serialized JSON: {name:Alice,age:30} Deserialized: User { name: Alice, age: 30 }其他注意事项serde下的serde_derivecrate提供了机制可以覆盖单个字段或枚举变体的序列化。由于serde是第三方库你可能不希望强制添加对它的依赖。大多数库都选择了提供了serde功能(feature)只有当用户选择启用该功能时才添加对serde的支持。也就是说你要在你的crate里这么写[dependencies] serde { version 1.0, optional true } [features] serde [dep:serde]在[dependencies]这一块引入了serde除了写了语义版本之外还有optional true这代表着是一个可选的依赖。这意味着默认情况下不包含 serde除非显式启用它。[features]这一块写了serde [dep:serde]意思是当用户启用serde feature时才会启用 serde 依赖dep:serde这部分表示依赖 serde 这个库dep:是依赖的前缀告诉Cargo这个feature依赖serde别人要用你的crate假设my_crate是你的crate的名字时这么写就可以启用serde[dependencies] my_crate { version 0.1, features [serde] }2.3.2. 不建议实现Copytrait用户通常不期望类型实现Copytrait。如果用户想要副本的话通常会调用clone方法。Copytrait改变了移动给定类型值的语义。看个例子#[derive(Debug,Copy, Clone)] struct Point { x: i32, y: i32, } fn main() { let point1 Point { x: 10, y: 10 }; let point2 point1; println!({:?}, point1); println!({:?}, point2); }point1的值赋给了point2。一般来说point1至此之后就会失效但是由于Point结构体实现了Copytrait所以point1的值赋给了point2发生的是复制而不是移动point1至此之后仍然保持有效。这点会让用户感到惊讶所以不建议实现Copytrait。除此以外实现Copy的类型会有很多限制一个最初简单的类型很容易变得不再满足Copytrait的要求。例如持有String或其他不支持Copytrait的类型都不得不移除Copytrait。
【Rust中级教程】2.3. API设计原则之不意外性(unsurprising) Pt.3：实现serde下的Serialize和Deserialize trait、不建议实现Copy trait
2.3. API设计原则之不意外性(unsurprising) Pt.3实现serde下的Serialize和Deserialize trait、不建议实现Copy trait2.3.1. 建议实现serde下的Serialize和Deserializetraitserde是Rust中用于序列化serialization和反序列化deserialization的核心库-序列化Serialization把Rust结构体或枚举转换为JSON、YAML等格式的字符串或二进制数据。-反序列化Deserialization从JSON、YAML等格式的字符串或二进制数据解析回Rust结构体或枚举。Serialize和Deserialize都是serde库下的trait。SerializetraitSerializetrait允许一个类型转换为可序列化的数据格式如JSON、YAML、TOML。其主要方法有-serialize_bool-serialize_i32-serialize_str-serialize_struct这些是Serialize实现会调用的Serializer及相关trait 上的方法Serializetrait 本身只要求实现serialize。其定义是pub trait Serialize { fn serializeS(self, serializer: S) - ResultS::Ok, S::Error where S: Serializer; }我们用一个例子来介绍如何手动实现Serializetraituse serde::ser::{Serialize, SerializeStruct, Serializer}; struct Point { x: i32, y: i32, } impl Serialize for Point { fn serializeS(self, serializer: S) - ResultS::Ok, S::Error where S: Serializer, { let mut state serializer.serialize_struct(Point, 2)?; state.serialize_field(x, self.x)?; state.serialize_field(y, self.y)?; state.end() } }serializer.serialize_struct(Point, 2)?创建一个结构体序列化对象2 代表字段数量state.serialize_field(x, self.x)?依次序列化结构体字段state.end()结束序列化DeserializetraitDeserializetrait允许从各种数据格式解析Rust类型。其主要方法有-deserialize_bool-deserialize_i32-deserialize_string-deserialize_struct这些是Deserialize实现通过Visitor驱动的Deserializer及相关trait 上的方法Deserializetrait 本身只要求实现deserialize。其定义是pub trait Deserializede: Sized { fn deserializeD(deserializer: D) - ResultSelf, D::Error where D: Deserializerde; }deserialize方法的作用是使用deserializer从数据格式解析Rust类型我们用一个例子来介绍如何手动实现Deserializetraituse serde::de::{self, Deserialize, Deserializer, Visitor, MapAccess}; use std::fmt; struct Point { x: i32, y: i32, } implde Deserializede for Point { fn deserializeD(deserializer: D) - ResultSelf, D::Error where D: Deserializerde, { struct PointVisitor; implde Visitorde for PointVisitor { type Value Point; fn expecting(self, formatter: mut fmt::Formatter) - fmt::Result { formatter.write_str(a struct Point with fields x and y) } fn visit_mapM(self, mut map: M) - ResultPoint, M::Error where M: MapAccessde, { let mut x None; let mut y None; while let Some(key) map.next_key::String()? { match key.as_str() { x x Some(map.next_value()?), y y Some(map.next_value()?), _ {} } } let x x.ok_or_else(|| de::Error::missing_field(x))?; let y y.ok_or_else(|| de::Error::missing_field(y))?; Ok(Point { x, y }) } } deserializer.deserialize_struct(Point, [x, y], PointVisitor) } }PointVisitor结构体用于解析JSON字段visit_map解析x和y的值确保字段存在使用#[derive(Serialize, Deserialize)]标注自动实现Serialize和Deserialize手动实现Serialize和Deserialize非常繁琐通常我们会使用serde_derive宏use serde::{Serialize, Deserialize}; #[derive(Serialize, Deserialize, Debug)] struct Point { x: i32, y: i32, } fn main() { let p Point { x: 10, y: 20 }; let serialized serde_json::to_string(p).unwrap(); println!(Serialized: {}, serialized); // {x:10,y:20} let deserialized: Point serde_json::from_str(serialized).unwrap(); println!(Deserialized: {:?}, deserialized); // Point { x: 10, y: 20 } }使用了Serialize和Deserialize的例子use serde::{Serialize, Deserialize}; use serde_json; #[derive(Serialize, Deserialize, Debug)] struct User { name: String, age: u32, } fn main() { let user User { name: Alice.to_string(), age: 30, }; // 序列化 let json_str serde_json::to_string(user).unwrap(); println!(Serialized JSON: {}, json_str); // 反序列化 let deserialized: User serde_json::from_str(json_str).unwrap(); println!(Deserialized: {:?}, deserialized); }输出Serialized JSON: {name:Alice,age:30} Deserialized: User { name: Alice, age: 30 }其他注意事项serde下的serde_derivecrate提供了机制可以覆盖单个字段或枚举变体的序列化。由于serde是第三方库你可能不希望强制添加对它的依赖。大多数库都选择了提供了serde功能(feature)只有当用户选择启用该功能时才添加对serde的支持。也就是说你要在你的crate里这么写[dependencies] serde { version 1.0, optional true } [features] serde [dep:serde]在[dependencies]这一块引入了serde除了写了语义版本之外还有optional true这代表着是一个可选的依赖。这意味着默认情况下不包含 serde除非显式启用它。[features]这一块写了serde [dep:serde]意思是当用户启用serde feature时才会启用 serde 依赖dep:serde这部分表示依赖 serde 这个库dep:是依赖的前缀告诉Cargo这个feature依赖serde别人要用你的crate假设my_crate是你的crate的名字时这么写就可以启用serde[dependencies] my_crate { version 0.1, features [serde] }2.3.2. 不建议实现Copytrait用户通常不期望类型实现Copytrait。如果用户想要副本的话通常会调用clone方法。Copytrait改变了移动给定类型值的语义。看个例子#[derive(Debug,Copy, Clone)] struct Point { x: i32, y: i32, } fn main() { let point1 Point { x: 10, y: 10 }; let point2 point1; println!({:?}, point1); println!({:?}, point2); }point1的值赋给了point2。一般来说point1至此之后就会失效但是由于Point结构体实现了Copytrait所以point1的值赋给了point2发生的是复制而不是移动point1至此之后仍然保持有效。这点会让用户感到惊讶所以不建议实现Copytrait。除此以外实现Copy的类型会有很多限制一个最初简单的类型很容易变得不再满足Copytrait的要求。例如持有String或其他不支持Copytrait的类型都不得不移除Copytrait。
