25. 乾貨系列從零用Rust編寫正反向代理，序列化之serde是如何工作的

問蒙服務框架發表於2023-11-10

wmproxy

wmproxy已用Rust實現http/https代理, socks5代理, 反向代理, 靜態檔案伺服器，四層TCP/UDP轉發，內網穿透，後續將實現websocket代理等，會將實現過程分享出來，感興趣的可以一起造個輪子

專案地址

國內: https://gitee.com/tickbh/wmproxy

github: https://github.com/tickbh/wmproxy

序列化

序列化（Serialization）是指將資料結構或物件狀態轉化為可以儲存或傳輸的形式的過程。

在序列化過程中，物件的成員屬性和型別資訊一起被轉換為一個位元組流或可列印字元流，以便於儲存或網路傳輸。

這個位元組流或字元流可以再次被反序列化（Deserialization）還原為原始物件狀態。

字元流比如JSON，位元組流比如ProtoBuf。

Rust中的序列化

在Rust中序列化最常用且支援最廣的為第三方庫serde，當前在github上已有8000顆star。

常用的比如JSON庫的serde_json，比如YAML，TOML，BSON等，依靠serde庫之上，對常用的格式已經有了廣泛的的支援。

在程式碼中，Serde資料模型的序列化部分由特定義 Serializer，反序列化部分由特徵定義Deserializer。這些是將每個 Rust 資料結構對映到 29 種可能型別之一的方法。特徵的每個方法Serializer對應於資料模型的一種型別。

支援基礎型別如常用的布林值，整型，浮點型，字串，位元組流

支援的高階型別，如tuple，struct，seq，enum可以對映成各種內建的資料結構。

如何使用serde

假如用現有的資料格式，如json之類的，可以輕鬆的實現。

配置Cargo.toml

[package]
name = "wmproxy"
version = "0.1.0"
authors = ["wenmeng <user@wm-proxy.com>"]

[dependencies]
serde = { version = "1.0", features = ["derive"] }

# 這僅僅是測試用例，需要用哪個可以選擇新增
serde_json = "1.0"

現在src/main.rs使用Serde的自定義匯出：

use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Debug)]
struct Point {
    x: i32,
    y: i32,
}

fn main() {
    let point = Point { x: 1, y: 2 };

    let serialized = serde_json::to_string(&point).unwrap();
    println!("serialized = {}", serialized);

    let deserialized: Point = serde_json::from_str(&serialized).unwrap();
    println!("deserialized = {:?}", deserialized);
}

以下輸出：

$ cargo run
serialized = {"x":1,"y":2}
deserialized = Point { x: 1, y: 2 }

serde中的屬性引數

在使用serde中經常可以看到在欄位前加一些屬性引數，這些是約定該欄位序列化或反序列化時將如何處理的，下面我們看以下的例子：

#[serde(default)]
這是設定預設引數，或者可以帶上#[serde(default="???")]，這裡???將是一個函式名，不能帶引數，可以直接訪問，如Vec::new可以直接訪問的函式。

fn default_y() -> i32  {
    1024
}
#[derive(Serialize, Deserialize, Debug)]
struct Point {
    #[serde(default)]
    x: i32,
    #[serde(default="default_y")]
    y: i32,
}

此時我們反序化一個值時，如果沒有x的引數會將x預設設定成0，如果沒有y引數，將會呼叫default_y函式，也就是y會預設為1024。

#[serde(rename = "name")]
重新命名欄位名字，在記憶體中顯示長的名字好理解，在配置中可以用短的名字好配置。此外還有#[serde(rename_all = "...")]可以將所有的名字結構變成全小寫，或者全大寫之類或者駝峰結構等。
#[serde(skip)]
該欄位跳過序列化及反序列化，也就是一些記憶體物件或者臨時資料不適合做序列化，用此來做約束。還有#[serde(skip_serializing)]跳過序列化和#[serde(skip_deserializing)]跳過反序列化等。
#[serde(flatten)]
將不能解析的資料統一挪入到另一個資料結構，在此專案中用到的通用的配置化結構，就將其均挪到了CommonConfig，可以極好的精簡配置結構

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct HttpConfig {
    #[serde(default = "Vec::new")]
    pub server: Vec<ServerConfig>,
    #[serde(default = "Vec::new")]
    pub upstream: Vec<UpstreamConfig>,
    #[serde(flatten)]
    #[serde(default = "CommonConfig::new")]
    pub comm: CommonConfig,
}

#[serde(with = "module")]
這個是自定義序列化的關鍵，也是他強大的基礎，可以很好的實現自定義的一些操作，就比如配置一個整型，現在要把他轉成Duration或者原來是一個字串"4k"表示大小，現在需要把他按資料大小轉成數字4096，就需要自定義的序列化過程。
該聲名同時包含了serialize_with和deserialize_with，該模組需實現$module::serialize及$module::deserialize做對應的序列化和反序列化。

serde的工作原理

序列化

以下過程是Rust中的資料結構是如何轉化成目標格式的

Rust （結構體列舉） 
  ↓
  -- Serialize（序列化） --> 當前結構體中，有對欄位進行協議說明的，加屬性標記
  ↓
  -- 資料的格式（如JSON/BSON/YAML等） --> 根據對應的輸出庫（serde_json/serde_yaml）輸出相應的位元組流

反序列化

以下以JSON格式是如何轉化成Rust的結構，在JSON中屬於鍵值對且值有特定的資料格式，其中key將解析成資料結構中的欄位名，值value將根據反序列化可以嘗試解析的型別嘗試是否能轉成目標型別。

比如value值為字串，且反序列反時選擇deserialize_str，將在反序列化的時候會嘗試呼叫

/// 我們將根據該字串的值能否解析成目標型別，如果失敗返回錯誤
fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
where
    E: de::Error,
{
}

比如value值為數值，且反序列反時選擇deserialize_i64，將在反序列化的時候會嘗試呼叫

/// 我們將根據該數值的值能否解析成目標型別，如果失敗返回錯誤
fn visit_i64<E>(self, v: i64) -> Result<Self::Value, E>
    where
        E: Error, {
}

或者以上兩種格式我們都是支援的，比如時間可以支援數字8或者"8s"，此時我們需要同時將數字或者字串同時支援轉成Duration::new(8,0)，那麼此時我們自定義的反序列化函式可以我選擇deserialize_any，並分別實現visit_i64及visit_str

舉個例子

以下是透過標準的Display做輸出及FromStr做反序列化，但是此時我們又需要同時支援數字的處理，首先我們先定義模組

pub struct DisplayFromStrOrNumber;

此時該模組需要實現序列化及反序列化。
實現序列化，將用標準的Display做輸出：

impl<T> SerializeAs<T> for DisplayFromStrOrNumber
where
    T: Display,
{
    fn serialize_as<S>(source: &T, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        serializer.collect_str(source)
    }
}

實現反序列化，我們將數字統一轉成字串，然後用FromStr做反序列化：


impl<'de, T> DeserializeAs<'de, T> for DisplayFromStrOrNumber
where
    T: FromStr,
    T::Err: Display,
{
    fn deserialize_as<D>(deserializer: D) -> Result<T, D::Error>
    where
        D: Deserializer<'de>,
    {
        struct Helper<S>(PhantomData<S>);
        impl<'de, S> Visitor<'de> for Helper<S>
        where
            S: FromStr,
            <S as FromStr>::Err: Display,
        {
            type Value = S;

            fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
                write!(formatter, "a string")
            }

            fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
            where
                E: de::Error,
            {
                value.parse::<Self::Value>().map_err(de::Error::custom)
            }

            /// 將數字轉成字串從而能呼叫FromStr函式
            fn visit_i64<E>(self, v: i64) -> Result<Self::Value, E>
                where
                    E: Error, {
                format!("{}", v).parse::<Self::Value>().map_err(de::Error::custom)
            }
        }

        deserializer.deserialize_any(Helper(PhantomData))
    }
}

此時我們已有了標準模組了，我們只能重新實現類的Display及FromStr，由於現有的型別如Duration我們不能重新實現impl Display for Duration因為介面Display和型別Duration均不是我們定義的，如果我們可以重新實現，那麼此有可能其它第三方庫也實現了，那麼我們在引用的時候可能就有多種實現方法，從而無法確定呼叫函式。

那麼此時我們做一層包裹方法

pub struct ConfigDuration(pub Duration);

此時我們只需要重新實現Display及FromStr就可以了


impl FromStr for ConfigDuration {
    type Err=io::Error;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        if s.len() == 0 {
            return Err(io::Error::new(io::ErrorKind::InvalidInput, ""));
        }

        let d = if s.ends_with("ms") {
            let new = s.trim_end_matches("ms");
            let s = new.parse::<u64>().map_err(|_| io::Error::new(io::ErrorKind::InvalidInput, ""))?;
            Duration::new(0, (s * 1000_000) as u32)
        } else if s.ends_with("h") {
            let new = s.trim_end_matches("h");
            let s = new.parse::<u64>().map_err(|_| io::Error::new(io::ErrorKind::InvalidInput, ""))?;
            Duration::new(s * 3600, 0)
        } else if s.ends_with("min") {
            let new = s.trim_end_matches("min");
            let s = new.parse::<u64>().map_err(|_| io::Error::new(io::ErrorKind::InvalidInput, ""))?;
            Duration::new(s * 60, 0)
        } else if s.ends_with("s") {
            let new = s.trim_end_matches("s");
            let s = new.parse::<u64>().map_err(|_| io::Error::new(io::ErrorKind::InvalidInput, ""))?;
            Duration::new(s, 0)
        } else {
            let s = s.parse::<u64>().map_err(|_| io::Error::new(io::ErrorKind::InvalidInput, ""))?;
            Duration::new(s, 0)
        };

        Ok(ConfigDuration(d))
    }
}


impl Display for ConfigDuration {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let ms = self.0.subsec_millis();
        let s = self.0.as_secs();
        if ms > 0 {
            f.write_str(&format!("{}ms", ms as u64 + s * 1000))
        } else {
            if s >= 3600 && s % 3600 == 0 {
                f.write_str(&format!("{}h", s / 3600))
            } else if s >= 60 && s % 60 == 0 {
                f.write_str(&format!("{}min", s / 60))
            } else {
                f.write_str(&format!("{}s", s))
            }
        }
    }
}

這樣子我們在加上聲名即可以實現自定義的序列化過程了：

pub struct CommonConfig {
    #[serde_as(as = "Option<DisplayFromStrOrNumber>")]
    pub rate_limit_per: Option<ConfigDuration>,
}

結語

序列化不管在配置還是在傳輸等過程中，都是必不可少的存在，瞭解序列化及反序列化的過程我們將可以更快的找到切入點去實現自己的功能。

點選 [關注]，[在看]，[點贊] 是對作者最大的支援

26. 乾貨系列從零用Rust編寫正反向代理，如何釋出Rust專案到Docker
2023-11-13
RustDocker
21. 從零用Rust編寫正反向代理，tokio竟然這樣對待socket！
2023-11-01
Rust
22. 從零用Rust編寫正反向代理，一個資料包的神奇HTTP歷險記!
2023-11-03
RustHTTP
反向代理是如何工作的？
2022-06-07
Rust是如何用Rust編寫的？ - Reddit
2022-04-25
Rust
代理IP是如何工作的？
2022-06-17
代理API是如何工作的？
2022-06-15
API
SOCKS代理是如何工作的？
2022-05-24
反向代理是啥？
2016-06-14
乾貨！如何正確使用Git Flow
2015-12-26
Git
【乾貨】JDK動態代理的實現原理以及如何手寫一個JDK動態代理
2018-10-18
JDK
解密BGPaaS代理是如何工作的
2020-08-04
解密
shell-【技術乾貨】工作中編寫shell指令碼實踐
2019-09-06
指令碼
什麼是反向海外IP代理？其工作原理是什麼？
2022-08-17
乾貨系列——模板之圖論1
2018-11-08
圖論
什麼是正向代理？什麼是反向代理？
2023-01-12
什麼是正向代理和反向代理？
2024-03-26
IPIDEA乾貨|動態代理IP是什麼？
2023-04-26
Idea
【譯】Arc 在 Rust 中是如何工作的
2020-11-19
Rust
代理伺服器是如何工作的？
2022-05-26
伺服器
反向代理的本質是什麼？
2022-05-26
Nginx 學習系列（一） ------------- 正向代理與反向代理
2018-08-06
Nginx
如何編寫乾淨高效的CSS程式碼
2014-05-09
CSS
淺談Nginx之反向代理
2019-03-02
Nginx
什麼是代理以及它是如何工作的？
2021-12-15
git乾貨系列：（五）多人協同工作之分支管理
2017-06-01
Git
編譯器是如何工作的？
2013-12-13
編譯
什麼是反向代理，什麼又是正向代理？
2021-04-16
使用Spring Boot重試失敗編寫一個反向代理 - Ashrith
2021-12-03
Spring Boot
什麼是正、反向海外HTTP代理？兩者各有什麼用處？
2022-09-19
HTTP
乾貨：HashMap的工作原理解析
2019-03-04
HashMap
nginx 學習之反向代理(1)
2019-02-17
Nginx
nginx大道至簡之反向代理
2020-09-24
Nginx
如何編寫python的正規表示式
2015-10-10
Python
乾貨系列之實現City Guides的動畫效果(一)
2016-04-03
GUIIDE動畫
乾貨系列之實現City Guides的動畫效果(二)
2016-04-03
GUIIDE動畫
substrate輕鬆學系列5：編寫pallet的Rust前置知識
2022-07-24
Rust
ES6 系列之 Babel 是如何編譯 Class 的(上)
2021-09-09
Babel編譯